@ddd-ts-kit/winston 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,283 @@
-# Temporary Holding Version
+# @ddd-ts-kit/winston
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The kernel `Logger` port on [winston](https://github.com/winstonjs/winston): JSON lines on the
+standard output, the correlation fields of the work in progress on every line, credentials
+redacted, a flush for the shutdown. Nothing in `domain/` or `application/` imports this
+package, or logs anything: the composition root binds the adapter, and infrastructure,
+presentation and the aspects write through the port.
+
+```
+npm i @ddd-ts-kit/winston winston
+```
+
+Written against winston 3.19.
+
+## Composition root
+
+```ts
+// platform/observability/create-logger.ts
+import type { ExecutionScope, LogLevel } from '@ddd-ts-kit/kernel';
+import { traceLogFields } from '@ddd-ts-kit/tracing';
+import { createWinstonLogger, type WinstonLogger } from '@ddd-ts-kit/winston';
+
+export interface LogSettings {
+  readonly level: LogLevel; // LOG_LEVEL
+  readonly format: 'json' | 'pretty'; // LOG_FORMAT
+  readonly service: string;
+  readonly environment: string;
+  readonly scrubMessages: boolean; // LOG_SCRUB_MESSAGES
+}
+
+export function createLogger(scope: ExecutionScope, settings: LogSettings): WinstonLogger {
+  return createWinstonLogger({ ...settings, fields: () => traceLogFields(scope) });
+}
+```
+
+```ts
+// main.ts
+import { tracing } from '@/platform/tracing.js'; // first
+import { AsyncLocalStorageExecutionScope } from '@ddd-ts-kit/kernel';
+import { createApplication, kernelModule } from '@ddd-ts-kit/di';
+
+const scope = new AsyncLocalStorageExecutionScope();
+const logger = createLogger(scope, config.log);
+
+const app = createApplication({
+  modules: [kernelModule({ executionScope: scope, logger }), ...contexts],
+});
+
+process.once('SIGTERM', () => void shutdown());
+
+async function shutdown(): Promise<void> {
+  await app.stop(); // flushes the error reporter, then the logger, last: that ends the winston logger
+  await tracing.shutdown();
+}
+```
+
+`init --logger winston` writes this `create-logger.ts` (it answers a `NoopLogger` when given no
+settings, which is how the tools and the tests stay silent); `platform/lay-foundations.ts`
+calls it once and `composeApplication` hands the logger to `kernelModule({ logger })`.
+
+One line of the application, as it is written:
+
+```json
+{"actorId":"user-1","context":"shipping","correlationId":"9f2c","environment":"production","level":"info","message":"order shipped","origin":"http","service":"shop-api","span_id":"00f067aa0ba902b7","tenantId":"acme","time":"2026-03-01T10:00:00.000Z","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736"}
+```
+
+**Correlation.** `fields` is read at each line that is written, by a winston format: no call
+site passes an id. `traceLogFields(scope)` answers the trace and span ids inside a span, and
+inside the execution scope the correlation id, the causation id, the origin, the actor and the
+tenant. This package does not depend on the tracing package: any `() => LogFields` fits,
+`() => logFieldsOf(scope.current())` included. A function that throws gives no field, never a
+lost line. The fields of the line win over those of a child, which win over `fields`: the
+format only fills the keys nobody gave. `StdoutLogger` and `@ddd-ts-kit/pino` differ on the
+second step (there `fields` win over a child), so do not bind in a child a key that `fields`
+answers if the logger may be swapped.
+
+**An instance of your own.** The project that already configures winston keeps doing so, and
+takes the formats it wants:
+
+```ts
+import { CREDENTIAL_KEYS } from '@ddd-ts-kit/kernel';
+import winston from 'winston';
+import { WinstonLogger, correlationFields, redactCredentials } from '@ddd-ts-kit/winston';
+
+const instance = winston.createLogger({
+  level: 'info',
+  format: winston.format.combine(
+    correlationFields(() => traceLogFields(scope)),
+    redactCredentials([...CREDENTIAL_KEYS, 'iban']), // after the formats that add fields
+    winston.format.timestamp(),
+    winston.format.json(),
+  ),
+  transports: [new winston.transports.Console()],
+});
+
+const logger = new WinstonLogger(instance);
+```
+
+`createWinstonLogger` writes the instant under `time`, the level by its name and the message
+under `message`, like the `StdoutLogger` of the aspects package and like `@ddd-ts-kit/pino`:
+one dashboard reads the three. The keys of a line come out sorted: winston's JSON format
+serializes with a stable stringifier.
+
+## Development mode
+
+```ts
+createWinstonLogger({ level: 'debug', format: 'pretty', fields: () => traceLogFields(scope) });
+```
+
+```
+10:00:00.000 info order shipped { context: 'shipping', service: 'shop-api', correlationId: '9f2c' }
+```
+
+The `pretty` format is made of winston's own combinators (`colorize`, `printf`), in the
+process: no other package, the local time of day, the level in colour, the fields as Node
+prints an object, a stack over several lines. Choose the format from configuration
+(`LOG_FORMAT=pretty` in `.env`, `json` everywhere else).
+
+## Privacy
+
+Log lines are where personal data leaks: they are written everywhere, read by everyone and kept
+for long. Three things are done in the adapter, so that no call site has to remember them.
+
+**Credentials are redacted** by a winston format, in the fields of a line, of a child and of
+`fields` alike. The value of these keys is replaced by `[redacted]`, at the top of a line and
+one level below (`headers.authorization`, `body.password`):
+
+`password`, `authorization`, `cookie`, `set-cookie`, `token`, `secret`, `apiKey`, `api_key`,
+`access_token`, `refresh_token`, `accessToken`, `refreshToken`, `client_secret`
+
+`redact: ['iban', 'ssn']` adds to the list. Names are matched exactly, case included, and
+nothing is looked for deeper than one level: log the part you mean, not a whole request. The
+objects you pass are never written to: a nested one is copied when a key has to be hidden.
+
+**An error passed as a field** (`logger.error('payment failed', { error })`: the `LogValue` of
+the port admits an `Error`) is written as `describeError` of the kernel describes it, the same
+from every logger of the port: its class as `type`, its `code` when
+it is a `DomainError`, its `message`, its own `stack`, then its `cause` the same way, up to
+eight deep. Each error of a chain is written once. Errors are looked for among the fields of
+the line, not inside nested objects. `CREDENTIAL_KEYS`, `REDACTED` and `SCRUBBED_MESSAGE` are
+those of the kernel too.
+
+**Messages of unexpected errors can be dropped.** The message of an error is the first place
+where personal data shows up: a driver quotes the row it refused. The default keeps it, because
+a log line that says `[message removed]` costs every investigation. With one option only the
+messages the project wrote itself survive, those of its `DomainError`s; class, code, stack and
+cause remain for the others, and the stack loses its first line, which repeats the message:
+
+```ts
+createWinstonLogger({ scrubMessages: true }); // or new WinstonLogger(instance, { scrubMessages: true })
+```
+
+This is the `scrubMessages` every logger of the port takes (`StdoutLogger`, pino, winston,
+`InMemoryLogger`) and the one of `@ddd-ts-kit/sentry`, with the same rule, the same
+`SCRUBBED_MESSAGE` and the same trade-off: turn it on when the logs leave your hands or when no
+operator should read that data there. What the message of a log line itself says stays yours:
+write `order shipped` and put the identifiers in fields.
+
+The kit itself never hands an error to a logger: the `logged` aspect, `loggingMiddleware` and
+the job scheduler write `errorType` and `errorCode` only (`identifyError` of the kernel), never
+a message, whatever `scrubMessages` says, and the error goes to the `ErrorReporter`. The
+description above is for the error your own code chooses to log:
+`logger.error('payment failed', { error })`.
+
+## Levels
+
+| Port | winston (`npm` levels) | |
+|---|---|---|
+| `debug` | `debug` | below it, winston also has `silly` |
+| `info` | `info` | the default threshold; `http` and `verbose` stand between `info` and `debug` |
+| `warn` | `warn` | |
+| `error` | `error` | |
+
+The names are the same in the `cli` levels. An instance on the `syslog` levels has no `warn`:
+say where it goes, or the line is dropped, since winston does not write at a level it does
+not know.
+
+```ts
+new WinstonLogger(instance, { levels: { warn: 'warning' } });
+```
+
+A line below the threshold costs one comparison: the adapter asks `isLevelEnabled` first,
+because winston alone would run every format before its transports drop the line. The
+threshold of an instance changed while running (`instance.level = 'debug'`) is followed by the
+adapter and by its children. `isLevelEnabled(level)` of the port answers the same question for
+the mapped level: ask it before building fields that cost. Once the logger was flushed it
+answers `false` for every level.
+
+`child(fields)` is a winston child: the fields are bound once, and winston merges them under
+the fields of each line. Three things differ from what winston does when called directly, all
+on purpose: a field named `level` or `message` never replaces the level or the message of the
+line; the message is never read as a format string (`%s`); and with `createWinstonLogger` a
+field named `time` is overwritten by the instant of the line. One thing is winston's:
+`service`, `environment` and `base` are its `defaultMeta`, which wins over a field of the
+same name on a line or in a child, where the other two loggers of the kit let the line and
+the child win.
+
+## Flush
+
+`flush(): Promise<void>` ends the winston logger and resolves once each of its transports has
+written what it was handed (their `finish` event). It never rejects, and a second call answers
+the same promise. `app.stop()` calls it, last, after the modules stopped and the error reporter
+was flushed: stopping logs too. Without the application of the di package, call it yourself at
+that place.
+
+The port calls a flush once, at shutdown, and leaves what is logged afterwards unspecified.
+Here the flush is final: a winston logger does not reopen, so what is logged afterwards,
+through this logger or one of its children, is dropped without an error, and `isLevelEnabled`
+answers `false`. Whatever must be logged about the shutdown is logged before `app.stop()`
+returns. A transport over a stream you opened yourself
+(a socket, a file stream given to the `Stream` transport) has handed its lines to that stream
+when `flush()` resolves: ending that stream is yours.
+
+## Performance
+
+winston writes each line through a Node stream, a chain of formats and its transports, all in
+the process and in the call: about 7 microseconds a line where `@ddd-ts-kit/pino` takes 3
+(Node 24, a child, four correlation fields, three fields, a sink that discards), and more
+with each format you add. Each line costs here one copy of its fields, one merge per level of
+child, the format reading `fields`, the redaction pass over the top-level values, the instant,
+and `JSON.stringify` through a safe serializer. That is nothing at a few hundred lines per
+second and visible at tens of thousands: there, lower the level or take `@ddd-ts-kit/pino`.
+
+Nothing is buffered by the adapter, so nothing is lost on a crash beyond what the transport
+itself had not written. Log calls never throw: fields that cannot be read or serialized (a
+getter that throws) give the line without them, marked `logError: "unserializable fields"`,
+and `createWinstonLogger` holds its formats to the same rule inside the stream.
+
+## Which one
+
+Take `StdoutLogger` of the aspects package when JSON lines on the standard output are all you
+need: no dependency, the same line shape. Take `@ddd-ts-kit/pino` when logging volume matters
+or when the framework already speaks pino (Fastify). Take winston when the team already runs
+its transports and formats (files with rotation, syslog, a vendor transport) and wants to keep
+them. The three implement one port and are held by one contract suite: swapping is one line of
+the composition root.
+
+## NestJS
+
+Nest has its own `LoggerService`, used by the framework for its own messages and by
+`new Logger(context)` in Nest classes. Application code of the kit never needs it: handlers and
+adapters receive the kernel `Logger`. To send what Nest itself logs through the same instance,
+hand it a bridge of a few lines; the kit ships none, since it would bind this package to Nest:
+
+```ts
+const nest = logger.child({ context: 'nest' });
+const bridge: LoggerService = {
+  log: (message: unknown) => nest.info(String(message)),
+  warn: (message: unknown) => nest.warn(String(message)),
+  error: (message: unknown) => nest.error(String(message)),
+  debug: (message: unknown) => nest.debug(String(message)),
+};
+
+const app = await NestFactory.create(AppModule, { logger: bridge });
+```
+
+`nest-winston` is the alternative when Nest classes log a lot: give it the winston instance
+you built, and wrap the same instance in `new WinstonLogger(instance)` for the kit.
+
+## In a test
+
+Nothing of this package: the test application binds `InMemoryLogger` of the kernel, and its
+`entries` are data. To hold another adapter of the port to the same behaviour, run the contract:
+
+```ts
+import { loggerContract } from '@ddd-ts-kit/testing/contracts';
+
+loggerContract({ describe, it, expect, beforeEach }, {
+  name: 'WinstonLogger',
+  createLogger: (setup) => { // { level, fields, scrubMessages }
+    const written: string[] = [];
+    const stream = new Writable({
+      write: (chunk, _encoding, done) => {
+        written.push(String(chunk));
+        done();
+      },
+    });
+    const logger = createWinstonLogger({ ...setup, transports: [new winston.transports.Stream({ stream })] });
+
+    return { logger, lines: () => written.map((line) => lineOf(JSON.parse(line))) }; // { level, message, fields }
+  },
+});
+```

package/dist/create-winston-logger.d.ts

@@ -0,0 +1,33 @@
+import { type LogFields, type LogLevel } from '@ddd-ts-kit/kernel';
+import winston from 'winston';
+import { WinstonLogger, type WinstonLoggerOptions } from './winston-logger.js';
+export interface CreateWinstonLoggerOptions extends Pick<WinstonLoggerOptions, 'scrubMessages'> {
+    /** Entries below it are not written. Default `info`. */
+    readonly level?: LogLevel;
+    /**
+     * `json`: one JSON object per line, what a container platform collects. `pretty`: one
+     * coloured line for a human, with winston's own formats. Default `json`.
+     */
+    readonly format?: 'json' | 'pretty';
+    /** Written on every line as `service`. */
+    readonly service?: string;
+    /** Written on every line as `environment`. */
+    readonly environment?: string;
+    /** Added to every line next to `service` and `environment`: version, region. */
+    readonly base?: LogFields;
+    /**
+     * Read at each line that is written: correlation fields of the work in progress, such as
+     * `traceLogFields` of the tracing package or `logFieldsOf` of the current execution context.
+     */
+    readonly fields?: () => LogFields;
+    /** Field names hidden in addition to `CREDENTIAL_KEYS`, at the top of a line and one level below. */
+    readonly redact?: readonly string[];
+    /** Where the lines go. Default: the console transport, on the standard output. */
+    readonly transports?: NonNullable<winston.LoggerOptions['transports']>;
+}
+/**
+ * A `WinstonLogger` on a winston logger with the defaults of the kit: `time` in ISO 8601,
+ * `level` by its name, `message`, then the fields; credentials redacted; errors described once.
+ */
+export declare function createWinstonLogger(options?: CreateWinstonLoggerOptions): WinstonLogger;
+//# sourceMappingURL=create-winston-logger.d.ts.map

package/dist/create-winston-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-winston-logger.d.ts","sourceRoot":"","sources":["../src/create-winston-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,OAAO,MAAM,SAAS,CAAC;AAM9B,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE/E,MAAM,WAAW,0BAA2B,SAAQ,IAAI,CAAC,oBAAoB,EAAE,eAAe,CAAC;IAC7F,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IACpC,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,SAAS,CAAC;IAClC,qGAAqG;IACrG,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;CACxE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,aAAa,CAW3F"}

package/dist/create-winston-logger.js

@@ -0,0 +1,34 @@
+import { CREDENTIAL_KEYS } from '@ddd-ts-kit/kernel';
+import winston from 'winston';
+import { correlationFields } from './formats/correlation-fields.js';
+import { isoTime } from './formats/iso-time.js';
+import { readableLine } from './formats/readable-line.js';
+import { redactCredentials } from './formats/redact-credentials.js';
+import { unbreakable } from './formats/unbreakable.js';
+import { WinstonLogger } from './winston-logger.js';
+/**
+ * A `WinstonLogger` on a winston logger with the defaults of the kit: `time` in ISO 8601,
+ * `level` by its name, `message`, then the fields; credentials redacted; errors described once.
+ */
+export function createWinstonLogger(options = {}) {
+    const logger = winston.createLogger({
+        level: options.level ?? 'info',
+        levels: winston.config.npm.levels,
+        defaultMeta: baseFields(options),
+        format: unbreakable(lineFormat(options)),
+        transports: options.transports ?? [new winston.transports.Console()],
+        exitOnError: false,
+    });
+    return new WinstonLogger(logger, options.scrubMessages === undefined ? {} : { scrubMessages: options.scrubMessages });
+}
+function baseFields(options) {
+    return {
+        ...(options.service === undefined ? {} : { service: options.service }),
+        ...(options.environment === undefined ? {} : { environment: options.environment }),
+        ...options.base,
+    };
+}
+function lineFormat(options) {
+    return winston.format.combine(...(options.fields === undefined ? [] : [correlationFields(options.fields)]), redactCredentials([...CREDENTIAL_KEYS, ...(options.redact ?? [])]), isoTime(), options.format === 'pretty' ? readableLine() : winston.format.json());
+}
+//# sourceMappingURL=create-winston-logger.js.map

package/dist/create-winston-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-winston-logger.js","sourceRoot":"","sources":["../src/create-winston-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAiC,MAAM,oBAAoB,CAAC;AACpF,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,aAAa,EAA6B,MAAM,qBAAqB,CAAC;AA2B/E;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAO,GAA+B,EAAE;IAC1E,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;QAClC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,MAAM;QAC9B,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM;QACjC,WAAW,EAAE,UAAU,CAAC,OAAO,CAAC;QAChC,MAAM,EAAE,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACxC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;QACpE,WAAW,EAAE,KAAK;KACnB,CAAC,CAAC;IAEH,OAAO,IAAI,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;AACxH,CAAC;AAED,SAAS,UAAU,CAAC,OAAmC;IACrD,OAAO;QACL,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;QACtE,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;QAClF,GAAG,OAAO,CAAC,IAAI;KAChB,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,OAAmC;IACrD,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,CAC3B,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAC5E,iBAAiB,CAAC,CAAC,GAAG,eAAe,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,EAClE,OAAO,EAAE,EACT,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CACrE,CAAC;AACJ,CAAC"}

package/dist/end-of.d.ts

@@ -0,0 +1,4 @@
+import type winston from 'winston';
+/** Ends the logger and resolves once each of its transports has written what it was handed. */
+export declare function endOf(logger: winston.Logger): Promise<void>;
+//# sourceMappingURL=end-of.d.ts.map

package/dist/end-of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"end-of.d.ts","sourceRoot":"","sources":["../src/end-of.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAInC,+FAA+F;AAC/F,wBAAsB,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKjE"}

package/dist/end-of.js

@@ -0,0 +1,15 @@
+/** Ends the logger and resolves once each of its transports has written what it was handed. */
+export async function endOf(logger) {
+    const finished = logger.transports.map(finishOf);
+    logger.end();
+    await Promise.all(finished);
+}
+function finishOf(transport) {
+    return new Promise((resolve) => {
+        transport.once('finish', resolve);
+        transport.once('error', () => {
+            resolve();
+        });
+    });
+}
+//# sourceMappingURL=end-of.js.map

package/dist/end-of.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"end-of.js","sourceRoot":"","sources":["../src/end-of.ts"],"names":[],"mappings":"AAIA,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,MAAsB;IAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAEjD,MAAM,CAAC,GAAG,EAAE,CAAC;IACb,MAAM,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,QAAQ,CAAC,SAAoB;IACpC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAElC,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;YAC3B,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/formats/correlation-fields.d.ts

@@ -0,0 +1,9 @@
+import type { LogFields } from '@ddd-ts-kit/kernel';
+import winston from 'winston';
+/**
+ * A winston format reading the fields of the work in progress at each line that is written,
+ * under the fields of the line and of its children. A source that throws (no active span, no
+ * execution context) gives no field, never a lost line.
+ */
+export declare function correlationFields(fields: () => LogFields): winston.Logform.Format;
+//# sourceMappingURL=correlation-fields.d.ts.map

package/dist/formats/correlation-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation-fields.d.ts","sourceRoot":"","sources":["../../src/formats/correlation-fields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAUjF"}

package/dist/formats/correlation-fields.js

@@ -0,0 +1,25 @@
+import winston from 'winston';
+/**
+ * A winston format reading the fields of the work in progress at each line that is written,
+ * under the fields of the line and of its children. A source that throws (no active span, no
+ * execution context) gives no field, never a lost line.
+ */
+export function correlationFields(fields) {
+    return winston.format((info) => {
+        for (const [key, value] of Object.entries(fieldsOrNone(fields))) {
+            if (info[key] === undefined) {
+                info[key] = value;
+            }
+        }
+        return info;
+    })();
+}
+function fieldsOrNone(fields) {
+    try {
+        return fields();
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=correlation-fields.js.map

package/dist/formats/correlation-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation-fields.js","sourceRoot":"","sources":["../../src/formats/correlation-fields.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAuB;IACvD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QAC7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;YAChE,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;gBAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACpB,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,EAAE,CAAC;AACP,CAAC;AAED,SAAS,YAAY,CAAC,MAAuB;IAC3C,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/formats/iso-time.d.ts

@@ -0,0 +1,4 @@
+import winston from 'winston';
+/** Stamps the line with `time` in ISO 8601, over a field of that name. */
+export declare function isoTime(): winston.Logform.Format;
+//# sourceMappingURL=iso-time.d.ts.map

package/dist/formats/iso-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iso-time.d.ts","sourceRoot":"","sources":["../../src/formats/iso-time.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,0EAA0E;AAC1E,wBAAgB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAMhD"}

package/dist/formats/iso-time.js

@@ -0,0 +1,9 @@
+import winston from 'winston';
+/** Stamps the line with `time` in ISO 8601, over a field of that name. */
+export function isoTime() {
+    return winston.format((info) => {
+        info.time = new Date().toISOString();
+        return info;
+    })();
+}
+//# sourceMappingURL=iso-time.js.map

package/dist/formats/iso-time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iso-time.js","sourceRoot":"","sources":["../../src/formats/iso-time.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,0EAA0E;AAC1E,MAAM,UAAU,OAAO;IACrB,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAErC,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,EAAE,CAAC;AACP,CAAC"}

package/dist/formats/readable-line.d.ts

@@ -0,0 +1,4 @@
+import winston from 'winston';
+/** One line for a human: the local time of day, the level in colour, the message, then the fields. */
+export declare function readableLine(): winston.Logform.Format;
+//# sourceMappingURL=readable-line.d.ts.map

package/dist/formats/readable-line.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readable-line.d.ts","sourceRoot":"","sources":["../../src/formats/readable-line.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,SAAS,CAAC;AAS9B,sGAAsG;AACtG,wBAAgB,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAWrD"}

package/dist/formats/readable-line.js

@@ -0,0 +1,18 @@
+import { inspect } from 'node:util';
+import winston from 'winston';
+const TIME_OF_DAY = new Intl.DateTimeFormat('en-GB', {
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    fractionalSecondDigits: 3,
+});
+/** One line for a human: the local time of day, the level in colour, the message, then the fields. */
+export function readableLine() {
+    return winston.format.combine(winston.format.colorize(), winston.format.printf(({ level, message, time, ...rest }) => {
+        // By its string keys: winston keeps the level and the rendered line under symbols.
+        const fields = Object.fromEntries(Object.entries(rest));
+        const shown = Object.keys(fields).length === 0 ? '' : ` ${inspect(fields, { depth: 6, breakLength: 120 })}`;
+        return `${TIME_OF_DAY.format(new Date(String(time)))} ${level} ${String(message)}${shown}`;
+    }));
+}
+//# sourceMappingURL=readable-line.js.map

package/dist/formats/readable-line.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readable-line.js","sourceRoot":"","sources":["../../src/formats/readable-line.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE;IACnD,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,SAAS;IACjB,MAAM,EAAE,SAAS;IACjB,sBAAsB,EAAE,CAAC;CAC1B,CAAC,CAAC;AAEH,sGAAsG;AACtG,MAAM,UAAU,YAAY;IAC1B,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,CAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,EACzB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE;QAC1D,mFAAmF;QACnF,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;QAE5G,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,EAAE,CAAC;IAC7F,CAAC,CAAC,CACH,CAAC;AACJ,CAAC"}

package/dist/formats/redact-credentials.d.ts

@@ -0,0 +1,7 @@
+import winston from 'winston';
+/**
+ * A winston format hiding the value of the given keys at the top of a line and one level
+ * below. Names are matched exactly, case included. Place it after the formats that add fields.
+ */
+export declare function redactCredentials(keys?: readonly string[]): winston.Logform.Format;
+//# sourceMappingURL=redact-credentials.d.ts.map

package/dist/formats/redact-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact-credentials.d.ts","sourceRoot":"","sources":["../../src/formats/redact-credentials.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,SAAS,MAAM,EAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAcnG"}

package/dist/formats/redact-credentials.js

@@ -0,0 +1,32 @@
+import { CREDENTIAL_KEYS, REDACTED } from '@ddd-ts-kit/kernel';
+import winston from 'winston';
+/**
+ * A winston format hiding the value of the given keys at the top of a line and one level
+ * below. Names are matched exactly, case included. Place it after the formats that add fields.
+ */
+export function redactCredentials(keys = CREDENTIAL_KEYS) {
+    const hidden = new Set(keys);
+    return winston.format((info) => {
+        for (const [key, value] of Object.entries(info)) {
+            if (hidden.has(key)) {
+                info[key] = REDACTED;
+            }
+            else if (isRecord(value)) {
+                info[key] = withoutCredentials(value, hidden);
+            }
+        }
+        return info;
+    })();
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date);
+}
+/** A nested object belongs to the caller: it is copied when a key has to be hidden, never written to. */
+function withoutCredentials(nested, hidden) {
+    const credentials = Object.keys(nested).filter((key) => hidden.has(key));
+    if (credentials.length === 0) {
+        return nested;
+    }
+    return { ...nested, ...Object.fromEntries(credentials.map((key) => [key, REDACTED])) };
+}
+//# sourceMappingURL=redact-credentials.js.map

package/dist/formats/redact-credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact-credentials.js","sourceRoot":"","sources":["../../src/formats/redact-credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAI,GAAsB,eAAe;IACzE,MAAM,MAAM,GAAwB,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAElD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QAC7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpB,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;YACvB,CAAC;iBAAM,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC3B,IAAI,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,EAAE,CAAC;AACP,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,YAAY,IAAI,CAAC,CAAC;AAC1G,CAAC;AAED,yGAAyG;AACzG,SAAS,kBAAkB,CACzB,MAAyC,EACzC,MAA2B;IAE3B,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAEzE,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;AACzF,CAAC"}

package/dist/formats/unbreakable.d.ts

@@ -0,0 +1,8 @@
+import winston from 'winston';
+/**
+ * The format, and when it throws on a line (a getter that throws, a `toJSON` that fails), that
+ * line as JSON without its fields. winston formats a line inside its stream: an exception
+ * there reaches the caller, or the process when the stream was holding the line back.
+ */
+export declare function unbreakable(format: winston.Logform.Format): winston.Logform.Format;
+//# sourceMappingURL=unbreakable.d.ts.map

package/dist/formats/unbreakable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unbreakable.d.ts","sourceRoot":"","sources":["../../src/formats/unbreakable.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,SAAS,CAAC;AAM9B;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAYlF"}

package/dist/formats/unbreakable.js

@@ -0,0 +1,24 @@
+import { UNWRITABLE_FIELDS } from '@ddd-ts-kit/kernel';
+import winston from 'winston';
+import { isoTime } from './iso-time.js';
+/** The key under which winston and its transports read the level of a line (package `triple-beam`). */
+const LEVEL = Symbol.for('level');
+/**
+ * The format, and when it throws on a line (a getter that throws, a `toJSON` that fails), that
+ * line as JSON without its fields. winston formats a line inside its stream: an exception
+ * there reaches the caller, or the process when the stream was holding the line back.
+ */
+export function unbreakable(format) {
+    const bare = winston.format.combine(isoTime(), winston.format.json());
+    return {
+        transform: (info, options) => {
+            try {
+                return format.transform(info, options);
+            }
+            catch {
+                return bare.transform({ level: info.level, message: info.message, ...UNWRITABLE_FIELDS, [LEVEL]: info[LEVEL] });
+            }
+        },
+    };
+}
+//# sourceMappingURL=unbreakable.js.map

package/dist/formats/unbreakable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unbreakable.js","sourceRoot":"","sources":["../../src/formats/unbreakable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,uGAAuG;AACvG,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAElC;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,MAA8B;IACxD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAEtE,OAAO;QACL,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE;YAC3B,IAAI,CAAC;gBACH,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACzC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,iBAAiB,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAClH,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createWinstonLogger, type CreateWinstonLoggerOptions } from './create-winston-logger.js';
+export { correlationFields } from './formats/correlation-fields.js';
+export { redactCredentials } from './formats/redact-credentials.js';
+export { WinstonLogger, type WinstonLoggerOptions } from './winston-logger.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAClG,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createWinstonLogger } from './create-winston-logger.js';
+export { correlationFields } from './formats/correlation-fields.js';
+export { redactCredentials } from './formats/redact-credentials.js';
+export { WinstonLogger } from './winston-logger.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAmC,MAAM,4BAA4B,CAAC;AAClG,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,aAAa,EAA6B,MAAM,qBAAqB,CAAC"}

package/dist/winston-logger.d.ts

@@ -0,0 +1,49 @@
+import { type LogFields, type LogLevel, type Logger } from '@ddd-ts-kit/kernel';
+import type winston from 'winston';
+export interface WinstonLoggerOptions {
+    /**
+     * Writes `SCRUBBED_MESSAGE` for the message of every logged error that is not a
+     * `DomainError`. Default `false`: see "Privacy" in the README for the trade-off.
+     */
+    readonly scrubMessages?: boolean;
+    /**
+     * The winston level each level of the port is written at. Default: the level of the same
+     * name, which the `npm` and `cli` levels of winston have. An instance on the `syslog`
+     * levels needs `{ warn: 'warning' }`: a level the instance does not know is dropped.
+     */
+    readonly levels?: Partial<Readonly<Record<LogLevel, string>>>;
+}
+/**
+ * The `Logger` port on a winston logger: a child is a winston child, and the formats and the
+ * transports the instance was configured with apply to every line. `createWinstonLogger`
+ * builds one with the defaults of the kit; build it yourself around an instance you configured.
+ */
+export declare class WinstonLogger implements Logger {
+    private readonly winston;
+    private readonly options;
+    private root;
+    private ended;
+    constructor(winston: winston.Logger, options?: WinstonLoggerOptions);
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+    child(fields: LogFields): WinstonLogger;
+    /**
+     * Whether winston would hand an entry of that level to a transport. winston filters by level
+     * in its transports, after the formats: asked here, a dropped entry costs nothing. `false`
+     * for every level once the logger was flushed.
+     */
+    isLevelEnabled(level: LogLevel): boolean;
+    /**
+     * Ends the winston logger and resolves once its transports have written everything. Final:
+     * what is logged afterwards, through this logger or a child, is dropped without a throw. A
+     * second call answers the same promise. Never rejects.
+     */
+    flush(): Promise<void>;
+    private nativeChild;
+    private write;
+    private nativeLevel;
+    private writeWithoutFields;
+}
+//# sourceMappingURL=winston-logger.d.ts.map

package/dist/winston-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"winston-logger.d.ts","sourceRoot":"","sources":["../src/winston-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0C,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACxH,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAGnC,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;GAIG;AACH,qBAAa,aAAc,YAAW,MAAM;IAKxC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,KAAK,CAA4B;IAEzC,YACmB,OAAO,EAAE,OAAO,CAAC,MAAM,EACvB,OAAO,GAAE,oBAAyB,EACjD;IAEJ,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAE/C;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAE9C;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAE9C;IAED,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAE/C;IAED,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,aAAa,CAMtC;IAED;;;;OAIG;IACH,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAEvC;IAED;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAIrB;IAED,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,KAAK;IAcb,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,kBAAkB;CAO3B"}

package/dist/winston-logger.js

@@ -0,0 +1,83 @@
+import { UNWRITABLE_FIELDS, describeErrorFields } from '@ddd-ts-kit/kernel';
+import { endOf } from './end-of.js';
+/**
+ * The `Logger` port on a winston logger: a child is a winston child, and the formats and the
+ * transports the instance was configured with apply to every line. `createWinstonLogger`
+ * builds one with the defaults of the kit; build it yourself around an instance you configured.
+ */
+export class WinstonLogger {
+    winston;
+    options;
+    root = this;
+    ended;
+    constructor(winston, options = {}) {
+        this.winston = winston;
+        this.options = options;
+    }
+    debug(message, fields) {
+        this.write('debug', message, fields);
+    }
+    info(message, fields) {
+        this.write('info', message, fields);
+    }
+    warn(message, fields) {
+        this.write('warn', message, fields);
+    }
+    error(message, fields) {
+        this.write('error', message, fields);
+    }
+    child(fields) {
+        const child = new WinstonLogger(this.nativeChild(fields), this.options);
+        child.root = this.root;
+        return child;
+    }
+    /**
+     * Whether winston would hand an entry of that level to a transport. winston filters by level
+     * in its transports, after the formats: asked here, a dropped entry costs nothing. `false`
+     * for every level once the logger was flushed.
+     */
+    isLevelEnabled(level) {
+        return this.root.ended === undefined && this.winston.isLevelEnabled(this.nativeLevel(level));
+    }
+    /**
+     * Ends the winston logger and resolves once its transports have written everything. Final:
+     * what is logged afterwards, through this logger or a child, is dropped without a throw. A
+     * second call answers the same promise. Never rejects.
+     */
+    flush() {
+        this.root.ended ??= endOf(this.root.winston).catch(() => undefined);
+        return this.root.ended;
+    }
+    nativeChild(fields) {
+        try {
+            return this.winston.child(describeErrorFields(fields, this.options));
+        }
+        catch {
+            return this.winston.child(UNWRITABLE_FIELDS);
+        }
+    }
+    write(level, message, fields = {}) {
+        if (!this.isLevelEnabled(level)) {
+            return;
+        }
+        const native = this.nativeLevel(level);
+        try {
+            this.winston.log({ ...describeErrorFields(fields, this.options), level: native, message });
+        }
+        catch {
+            this.writeWithoutFields(native, message);
+        }
+    }
+    nativeLevel(level) {
+        return this.options.levels?.[level] ?? level;
+    }
+    writeWithoutFields(level, message) {
+        try {
+            this.winston.log({ ...UNWRITABLE_FIELDS, level, message });
+        }
+        catch {
+            return;
+        }
+    }
+}
+//# sourceMappingURL=winston-logger.js.map

package/dist/winston-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"winston-logger.js","sourceRoot":"","sources":["../src/winston-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAA8C,MAAM,oBAAoB,CAAC;AAExH,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAgBpC;;;;GAIG;AACH,MAAM,OAAO,aAAa;IAKL,OAAO;IACP,OAAO;IALlB,IAAI,GAAkB,IAAI,CAAC;IAC3B,KAAK,CAA4B;IAEzC,YACmB,OAAuB,EACvB,OAAO,GAAyB,EAAE;uBADlC,OAAO;uBACP,OAAO;IACvB,CAAC;IAEJ,KAAK,CAAC,OAAe,EAAE,MAAkB;QACvC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,MAAkB;QACtC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,MAAkB;QACtC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,MAAkB;QACvC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,MAAiB;QACrB,MAAM,KAAK,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAExE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAEvB,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,KAAe;QAC5B,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/F,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAEpE,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;IACzB,CAAC;IAEO,WAAW,CAAC,MAAiB;QACnC,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QACvE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,KAAe,EAAE,OAAe,EAAE,MAAM,GAAc,EAAE;QACpE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAEvC,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;QAC7F,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAEO,WAAW,CAAC,KAAe;QACjC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;IAC/C,CAAC;IAEO,kBAAkB,CAAC,KAAa,EAAE,OAAe;QACvD,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,iBAAiB,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QAC7D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;IACH,CAAC;CACF"}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@ddd-ts-kit/winston",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Adapter of the kernel Logger port on winston, with trace and execution correlation on every line.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gbourgeat/ddd-ts-kit.git",
+    "directory": "packages/winston"
+  },
+  "homepage": "https://github.com/gbourgeat/ddd-ts-kit/tree/main/packages/winston#readme",
+  "bugs": "https://github.com/gbourgeat/ddd-ts-kit/issues",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@ddd-ts-kit/kernel": "0.1.1"
+  },
+  "devDependencies": {
+    "@ddd-ts-kit/testing": "0.1.1",
+    "winston": "^3.19.0"
+  },
+  "peerDependencies": {
+    "winston": "^3.19.0"
+  }
+}