Skip to content

Remove handleExceptions/handleRejections from LoggerOptions types - #2642

Open
hxperl wants to merge 1 commit into
winstonjs:masterfrom
hxperl:types-logger-options-exception-handling
Open

hxperl wants to merge 1 commit into
winstonjs:masterfrom
hxperl:types-logger-options-exception-handling

Conversation

@hxperl

@hxperl hxperl commented Sep 11, 2026

Copy link
Copy Markdown

index.d.ts declares handleExceptions and handleRejections on LoggerOptions:

interface LoggerOptions {
    ...
    transports?: Transport[] | Transport;
    handleExceptions?: boolean;
    handleRejections?: boolean;
    exceptionHandlers?: any;

Logger#configure never reads either one. Its destructuring list is silent, format, defaultMeta, levels, level, exitOnError, transports, colors, emitErrs, formatters, padLevels, rewriters, stripColors, exceptionHandlers, rejectionHandlers — neither name appears, and
nothing else on the logger path looks at them. The only place the implementation reads them is
logger.js:387, off a transport:

if (transport.handleExceptions) {

So TypeScript accepts createLogger({handleExceptions: true}) and it silently does nothing.

Reproduction

Against master (ff0b79d), before any change.

Compile side — tsc accepts it:

import * as winston from './index';
winston.createLogger({ handleExceptions: true, handleRejections: true });
$ npx tsc --ignoreConfig --noEmit --strict --esModuleInterop --skipLibCheck probe.ts
$ echo $?
0

Runtime side — nothing is registered:

const logger = winston.createLogger({
  handleExceptions: true,
  handleRejections: true,
  transports: [new winston.transports.Console({ silent: true })],
});
logger.exceptions.handlers.size      = 0
logger.rejections.handlers.size      = 0
process listeners uncaughtException  = 0
process listeners unhandledRejection = 0
own prop handleExceptions on logger  = false

--- with exceptionHandlers instead ---
logger2.exceptions.handlers.size     = 1
process listeners uncaughtException  = 1

The README is already correct on this — it documents the flag as a transport option ("you can
set handleExceptions to true when adding transports", and "pass in separate transports to the
exceptionHandlers property or set handleExceptions on any transport"). Only the type
declaration disagrees.

The change

Drops the two properties from LoggerOptions, and adds @ts-expect-error cases to
test/typescript-definitions.ts so they cannot come back unnoticed.

Removing them does not affect the supported usage: winston-transport's
TransportStreamOptions already declares both, so
new transports.Console({handleExceptions: true}) still type-checks. The test I added asserts
exactly that, alongside the two negative cases.

Judgement call

I removed the properties rather than marking them @deprecated. @deprecated would imply they
used to work at this level and are being phased out; as far as I can tell they never did
anything here, so a deprecation notice would be misleading. The cost of removing is that anyone
passing them today gets a new compile error — but their code is already not doing what they
think it is, so surfacing that seems like the point. If you would rather keep them as
@deprecated no-ops for a release to soften the break, say so and I will switch it.

Verification

$ npx tsc --project test          # npm run test:typescript
$ echo $?
0

$ npx jest -c test/jest.config.unit.js
Test Suites: 20 passed, 20 total
Tests:       3 todo, 234 passed, 237 total
Time:        49.89 s

I checked that the new test actually catches the regression rather than passing vacuously — with
index.d.ts reverted to master and the test file kept, tsc --project test fails:

test/typescript-definitions.ts(70,1): error TS2578: Unused '@ts-expect-error' directive.
test/typescript-definitions.ts(73,1): error TS2578: Unused '@ts-expect-error' directive.

Limits: macOS arm64, Node 22.18, TypeScript from npx --package typescript as test:typescript
invokes it. I did not run the integration suite. CI will need to confirm Linux and the
TypeScript versions in the matrix.

No linked issue — I found this by diffing index.d.ts against the implementation. I searched
open and closed issues and PRs first; nothing covers it, and none of the eight open PRs touching
index.d.ts (#2636, #2601, #2541, #2349, #2323, #2038, #1901, #1766) modifies these lines.

Logger#configure never reads either option off the options object, so
createLogger({handleExceptions: true}) type-checked and then did nothing.
They are transport options, and winston-transport's TransportStreamOptions
already declares them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017D7mLNAWavucy6fFFPZise
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant