feat: optionally filter rejected levels before logger formatting

[jeswr]

Logger-wide formatting currently runs even when every transport rejects a record's level. This filters those records before formatting, while retaining transport-level overrides and conservative fallbacks for handler records, startup buffering, unknown levels and custom streams.

The draft currently uses filterBeforeFormat: true, defaulting to false, in the shared _transform path.

Open question: configurable or a breaking change?

Should this remain opt-in, or should filtering before formatting become unconditional and be released as a breaking change, removing the configuration option entirely?

Filtering earlier changes two observable behaviors: rejected records disappear from the logger's readable output, and their formatters no longer run. This can affect data listeners and stateful formats such as ms(), as well as custom formatter side effects. The opt-in implementation preserves existing behavior by default, but the API choice is open for maintainer feedback. Exception handling, buffering and custom-transport fallbacks remain necessary safeguards under either approach.

Validation

• 19 targeted tests cover formatter counts, logging entry points, default/readable behavior, transport thresholds, reconfiguration, buffering, marked handler records, custom streams and callback cleanup.
• Unit suite: 253 passed, 3 todo, across 21 suites; repository coverage thresholds pass.
• Changed-file lint passes with one warning. The unchanged runtime implementation previously passed integration tests, TypeScript 5.5.3 checks, the Babel build and repository lint.

npm run test:unit -- --runInBand --forceExit

The focused suite exits normally. The broader suite previously reported open handles after completion, so the coverage run uses --forceExit.

Reported benchmark results

For 100,000 messages on Node 22.21.1 / macOS arm64, using label/color/timestamp/metadata/printf formatting and the real Console transport filter with output I/O stubbed:

Messages	Formatter calls, before → after	Median loop time, before → after
Rejected debug	100,000 → 0	164.78 ms → 25.55 ms
Accepted info	100,000 → 100,000	185.02 ms → 192.10 ms

Counts and timings were measured separately, with two warmup pairs and nine alternating measured pairs. The measured tradeoff is about 6.4× faster rejected-message logging and 3.8% overhead for accepted messages. These are logging-loop measurements, not application throughput. The benchmark is reported here rather than included in the patch.

Related: #2441, #1627, #1669 and CommunitySolidServer/CommunitySolidServer#2226.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Address the two moderate filtering issues involving handler wrappers and silent transports.

Review effort: Lite
Findings: None

What changed in this PR

Adds opt-in logger-level filtering before formatting to avoid unnecessary formatter work for rejected records.

Changes:

• Adds filterBeforeFormat runtime behavior and TypeScript support.
• Adds unit coverage for filtering and fallback cases.
• Documents configuration and behavioral effects.

File	Summary
test/​unit/​winston/​logger-filter-before-format.test.js	Tests filtering behavior and edge cases.
test/​typescript-definitions.ts	Validates TypeScript usage.
README.md	Documents configuration and behavior.
lib/​winston/​logger.js	Implements pre-format filtering; handler wrappers and silent transports require correction.
index.d.ts	Adds TypeScript declarations.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.