@bymax-one/nest-logger 1.1.0 → 1.2.0

package/dist/server/index.d.cts

@@ -174,8 +174,23 @@ interface BymaxLoggerModuleOptions {
      *   `BymaxLoggerModule.useNestLogger(app)` in `main.ts` instead. Default: true.
      */
     shouldUseAsNestLogger?: boolean;
-    /** Additional Pino redact paths — merged with `DEFAULT_REDACT_PATHS`. */
+    /**
+     * Additional `fast-redact` paths, applied on top of the default coverage
+     * whatever `redactStrategy` is in force.
+     */
     redactPaths?: readonly string[];
+    /**
+     * Engine backing the DEFAULT redaction set (never the consumer's own
+     * `redactPaths`, which are always `fast-redact` paths).
+     *
+     *   - `'names'` (default) — one recursive walk censoring any value whose KEY
+     *     NAME is in `REDACT_COMMON_FIELDS`, at ANY depth. ~943 k logs/s.
+     *   - `'paths'` — the pre-1.2 engine: `DEFAULT_REDACT_PATHS` handed to
+     *     `fast-redact`. Matches only wildcard depths 1–4 and measures ~9.3 k
+     *     logs/s. Provided as an escape hatch for a consumer depending on exact
+     *     path-matching semantics; expect it to be removed in a future major.
+     */
+    redactStrategy?: 'names' | 'paths';
     /** Censor string written in place of redacted values. Default: `[REDACTED]`. */
     redactCensor?: string;
     /** Disable default redact paths (use with caution). Default: false. */
@@ -328,6 +343,127 @@ declare class BymaxLoggerModule extends BymaxLoggerModuleBase {
     static useNestLogger(app: INestApplication): void;
 }
 
+/**
+ * Log keys reserved by `@bymax-one/nest-logger` for its own structured events.
+ *
+ * Consumer apps SHOULD NOT use these names for application-level events
+ * to avoid collision in log aggregation queries (Datadog, Loki, Elastic).
+ *
+ * Every key here is emitted by some code path, EXCEPT the ones listed in
+ * {@link RESERVED_LOG_KEYS_NOT_EMITTED}, which are reserved-only and carry the
+ * reason they stay that way. `reserved-log-keys.constants.spec.ts` enforces the
+ * split, so a key can never again be declared, documented as a signal, and then
+ * silently never written.
+ */
+declare const RESERVED_LOG_KEYS: Readonly<{
+    readonly LOGGER_BOOTSTRAP_OK: "LOGGER_BOOTSTRAP_OK";
+    readonly LOGGER_BOOTSTRAP_WARNING: "LOGGER_BOOTSTRAP_WARNING";
+    readonly LOGGER_SHUTDOWN_OK: "LOGGER_SHUTDOWN_OK";
+    readonly HTTP_REQUEST_START: "HTTP_REQUEST_START";
+    readonly HTTP_REQUEST_SUCCESS: "HTTP_REQUEST_SUCCESS";
+    readonly HTTP_REQUEST_REDIRECT: "HTTP_REQUEST_REDIRECT";
+    readonly HTTP_REQUEST_CLIENT_ERROR: "HTTP_REQUEST_CLIENT_ERROR";
+    readonly HTTP_REQUEST_SERVER_ERROR: "HTTP_REQUEST_SERVER_ERROR";
+    readonly HTTP_REQUEST_COMPLETED: "HTTP_REQUEST_COMPLETED";
+    readonly HTTP_REQUEST_ABORTED: "HTTP_REQUEST_ABORTED";
+    readonly HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED";
+    readonly HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED";
+    readonly METHOD_EXECUTION: "METHOD_EXECUTION";
+    readonly METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION";
+    readonly LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED";
+    readonly LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED";
+    readonly LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED";
+    readonly LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED";
+}>;
+/**
+ * Keys that are reserved but intentionally never emitted, each with the reason.
+ *
+ * A name in this map is claimed so no application event can take it, but the
+ * library commits to not writing it. Anything NOT listed here must be reachable
+ * from some code path — the spec asserts both directions.
+ */
+declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
+    /**
+     * Superseded before it was ever used. The request lifecycle terminates in one
+     * of `HTTP_REQUEST_SUCCESS` / `_REDIRECT` / `_CLIENT_ERROR` / `_SERVER_ERROR`,
+     * each carrying the same `duration` a generic "completed" entry would. Emitting
+     * it as well would double the terminal access-log volume to say nothing new.
+     * It stays claimed so an application cannot repurpose a name that reads like a
+     * library event.
+     */
+    readonly HTTP_REQUEST_COMPLETED: "reserved: superseded by the four status-specific terminal keys";
+}>;
+
+/**
+ * Name-based recursive redaction.
+ *
+ * Layer: server/utils — the engine behind the library's DEFAULT PII protection.
+ * It walks a log record once and censors every value whose KEY NAME is in the
+ * sensitive set, to a bounded depth (see {@link REDACT_MAX_TRAVERSAL_DEPTH}).
+ *
+ * Why this replaced path matching. The previous default compiled 140
+ * `fast-redact` paths, 108 of them multi-level wildcards (`*.password`,
+ * `*.*.password`, …). `fast-redact` walks every key at every listed level on
+ * every log call, so the cost grew with the PATH COUNT, not with the payload:
+ * measured at ~107 µs per entry (≈9.3 k logs/s) against ~0.9 µs with redaction
+ * off. A single traversal is O(nodes) — the same order Pino's serializer already
+ * pays. The shipped configuration measures 462 k logs/s against 9.3 k, for
+ * byte-identical output on every payload the old paths covered.
+ *
+ * It is also STRICTLY SAFER than the paths it replaces:
+ *   - depth 100 instead of four, and past it the value is DROPPED rather than
+ *     passed through, so the ceiling cannot become a leak the way the old one
+ *     was (anything below the wildcard list's fourth level was emitted in clear);
+ *   - a sensitive key is caught wherever it appears, so a headers bag logged as
+ *     `{ headers: { authorization } }` is covered, not only the exact
+ *     `req.headers.authorization` shape the absolute paths pinned.
+ *
+ * Three value kinds need special handling, and getting any of them wrong is a
+ * leak rather than a cosmetic issue:
+ *   - `Error` — copied through its prototype and descriptors, so it stays an
+ *     `Error` (Pino's `err` serializer keys off the instance, and `message` /
+ *     `stack` are own but NON-enumerable). Skipping errors entirely left an
+ *     error under any key WITHOUT a serializer serializing its own enumerable
+ *     properties in clear.
+ *   - anything carrying `toJSON` (`Date`, `Decimal`, Luxon, Prisma types) — the
+ *     method decides the serialized form, so the walk inspects its OUTPUT.
+ *     Skipping these let a `toJSON` SYNTHESIZE a secret straight past both hooks.
+ *   - `ArrayBuffer` views (`Buffer`, typed arrays) — indexed byte containers,
+ *     returned untouched.
+ *
+ * What this file cannot reach: bindings passed to `child()`. Pino pre-serializes
+ * them into the instance's `chindings` fragment before any formatter runs, so
+ * `PinoLoggerService.child()` applies this redactor itself.
+ *
+ * Contract: SNAPSHOT and NEVER-THROW. Nothing the caller passed is mutated; the
+ * result is a fresh structure built from values read exactly ONCE. That is a
+ * deliberate trade against an earlier copy-on-write design which returned a
+ * clean subtree by reference: doing so left every accessor in it to be evaluated
+ * a SECOND time by `JSON.stringify`, and a stateful getter (or `toJSON`) can
+ * answer clean to the walk and `{ password }` to the serializer. Inspection
+ * cannot close that window — only reading once and pinning the result can. It
+ * costs ~26 % of the entry throughput, measured, and the walk is still ~36x
+ * faster than the path expansion it replaced.
+ *
+ * Any internal failure — including a censor that cannot be written — degrades the
+ * whole record to a marked, secret-free envelope rather than crashing the request
+ * that produced it.
+ *
+ * @see {@link createNameRedactor}
+ */
+
+/**
+ * A configured redactor.
+ *
+ * @param value - The value to redact.
+ * @param isRecordRoot - `true` when `value` is the ROOT of a log record — the
+ *   object Pino iterates rather than serializes. A root must not honour a
+ *   `toJSON` method, because doing so would replace the entire record with that
+ *   method's return value; nested values and serializer outputs do reach
+ *   `JSON.stringify` and keep it.
+ */
+type Redactor = (value: unknown, isRecordRoot?: boolean) => unknown;
+
 /**
  * Pino-backed implementation of the NestJS `LoggerService` contract plus the
  * structured `MODULE_ACTION_RESULT` API.
@@ -346,8 +482,15 @@ declare class BymaxLoggerModule extends BymaxLoggerModuleBase {
  */
 declare class PinoLoggerService implements LoggerService, OnApplicationShutdown {
     private readonly pino;
+    private readonly redact;
     private context?;
-    constructor(pino: Logger);
+    /**
+     * @param pino - The wrapped Pino instance.
+     * @param redact - The DEFAULT-coverage redactor, applied to `child()` bindings.
+     *   Defaults to the identity so a hand-built instance (benchmarks, unit tests)
+     *   still works; the module always injects the configured one.
+     */
+    constructor(pino: Logger, redact?: Redactor);
     /**
      * NestJS `log` (info level). Last string parameter is treated as the context.
      *
@@ -701,6 +844,21 @@ declare class HttpLoggingInterceptor implements NestInterceptor {
      * @returns The (unmodified) response stream.
      */
     intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    /**
+     * Hand the lifecycle to the access-log middleware, recording only the thrown
+     * error for its terminal entry.
+     *
+     * The interceptor cannot be the recorder: it never runs for a request a guard
+     * rejected or one that matched no route. It also cannot judge DELIVERY — at the
+     * moment it completes, the response has not been flushed yet, which is why an
+     * aborted request used to be logged as the 200 the handler intended. What it
+     * uniquely has is the thrown value, so that is all it contributes.
+     *
+     * @param req - The request whose lifecycle the middleware owns.
+     * @param next - The downstream call handler.
+     * @returns The response stream, unmodified and with exceptions re-thrown.
+     */
+    private recordOnly;
     /**
      * Log a non-throwing completion: SUCCESS for 2xx, REDIRECT for 3xx, nothing
      * for any other status (those are surfaced via the error path instead).
@@ -731,8 +889,12 @@ declare class HttpLoggingInterceptor implements NestInterceptor {
  *
  * Layer: server/middlewares — NestJS requires middleware to be wired in a
  * module's `configure(consumer)` hook, which the library cannot do on the
- * consumer's behalf. This helper encapsulates the one-liner so consumers do not
- * import the middleware class directly.
+ * consumer's behalf. This helper encapsulates the wiring so consumers do not
+ * import the middleware classes directly.
+ *
+ * It registers TWO middlewares, in order: the correlation scope, then the access
+ * log that runs inside it. Both run before any guard, which is the whole point —
+ * an interceptor never observes a request a guard rejected.
  */
 
 /**
@@ -791,6 +953,18 @@ interface LoggableRequest {
     readonly method: string;
     /** Request target, normalized and query-stripped before it reaches a log. */
     readonly url: string;
+    /**
+     * The request target as it arrived, before any mount point was stripped.
+     *
+     * Middleware mounted at a path sees `url` RELATIVE to that mount: measured
+     * under `setGlobalPrefix('api')`, a request for `/api/users/7` reaches a
+     * root-mounted middleware as `url = '/users/7'` and
+     * `originalUrl = '/api/users/7'`, and `/api` itself arrives as `url = '/'`.
+     * Logging `url` there would drop the prefix from every entry and make an
+     * `excludePaths` pattern written against the real path stop matching. Absent
+     * on adapters that do not provide it, in which case `url` is already whole.
+     */
+    readonly originalUrl?: string | undefined;
     /** Client address when the adapter resolves one. */
     readonly ip?: string | undefined;
     /**
@@ -811,12 +985,26 @@ interface LoggableRequest {
 interface LoggableResponse {
     /** Status code, read when logging the completed request. */
     readonly statusCode: number;
+    /**
+     * `true` once every byte has been flushed to the socket. Read in the `'close'`
+     * handler to tell a delivered response from one the client never received:
+     * `'close'` fires for both, and `'finish'` never fires for an aborted request
+     * at all. It is what keeps an aborted request from being logged as the success
+     * the handler intended.
+     */
+    readonly writableFinished: boolean;
     /** Sets a response header (used for the correlation id). */
     setHeader(name: string, value: string): void;
     /** Selects the status code and returns the chainable body writer. */
     status(code: number): {
         json(body: unknown): unknown;
     };
+    /**
+     * Registers a lifecycle listener. Only `'close'` is used: it fires exactly
+     * once whether the response completed or the connection died early, where
+     * `'finish'` is blind to the aborted case.
+     */
+    on(event: 'close', listener: () => void): unknown;
 }
 /** Continuation passed to a middleware; invoked with no arguments here. */
 type NextHandler = () => void;
@@ -928,9 +1116,12 @@ declare const LOGGER_DESTINATIONS_TOKEN: unique symbol;
 declare const LOG_CONTEXT_TOKEN: unique symbol;
 
 /**
- * Canonical list of redact paths merged into Pino's `redact.paths` option by
- * default. Expected length: 27 root fields + 27 common fields × 4 depths + 5
- * absolute = **140**.
+ * The legacy `fast-redact` path expansion of {@link REDACT_COMMON_FIELDS}:
+ * every name at the record root plus wildcard depths 1–4, followed by the
+ * absolute header paths. Length is derived, not fixed — `fields × 5 + absolute`.
+ *
+ * Fed to Pino only under the opt-in `redactStrategy: 'paths'`. Kept exported at
+ * full fidelity because it is public API and append-only by contract.
  *
  * The bare field names come first, at depth 0 — the log record's own root.
  * `emitStructured` spreads caller metadata there (`{ ...metadata, logKey, ... }`),
@@ -942,18 +1133,48 @@ declare const LOG_CONTEXT_TOKEN: unique symbol;
  */
 declare const DEFAULT_REDACT_PATHS: readonly string[];
 
+/**
+ * Pino numeric level mapping. Frozen at runtime so destinations and the
+ * NestJS bridge can rely on a stable wire-format contract.
+ *
+ * @see {@link https://github.com/pinojs/pino/blob/main/docs/api.md#level-string}
+ */
+declare const PINO_LEVEL_NUMBERS: Record<LogLevel, number>;
+/**
+ * Reverse lookup — numeric Pino level → string. Derived from
+ * {@link PINO_LEVEL_NUMBERS} so the two cannot drift, then frozen so it is
+ * read-only at runtime.
+ */
+declare const PINO_LEVEL_NAMES: Record<number, LogLevel>;
+
 /**
  * Shape of a single log entry as serialized to JSON output.
  *
- * Used by destinations and downstream parsers (Datadog, Loki, Elastic).
+ * Used by destinations and downstream parsers (Loki, Elastic, Datadog).
  * The trailing index signature `[key: string]: unknown` covers arbitrary
  * structured fields injected by application logs.
+ *
+ * `level` and `time` describe what the library ACTUALLY writes. Before `1.2.0`
+ * they were declared `number`, which the runtime never produced: the Pino
+ * instance is built with `formatters.level` returning the string label and a
+ * `timestamp` function emitting an ISO 8601 string. A destination written
+ * against the old declaration type-checked and then failed at runtime — the
+ * README's own Loki example called `BigInt(entry.time)` on an ISO string, which
+ * throws. See `log-entry-contract.e2e-spec.ts`, which asserts the declaration
+ * against a real serialized record so the two can never drift again.
  */
 interface LogEntry {
-    /** Pino numeric level (30 = info, 50 = error, etc.). */
-    level: number;
-    /** ISO 8601 UTC timestamp string OR epoch milliseconds (numeric). */
-    time: string | number;
+    /**
+     * Severity as the Pino string label (`'info'`, `'error'`, …) — NOT the numeric
+     * code. Convert with `PINO_LEVEL_NUMBERS` when a numeric column is needed.
+     */
+    level: LogLevel;
+    /**
+     * ISO 8601 UTC timestamp string, e.g. `'2026-08-12T09:25:46.520Z'`. Parse with
+     * `Date.parse(entry.time)` for epoch milliseconds. A consumer-supplied
+     * `timestamp` option may change the format, but never the type.
+     */
+    time: string;
     /** Human-readable message. */
     msg: string;
     /** Convention key — `MODULE_ACTION_RESULT` format. */
@@ -1002,29 +1223,4 @@ interface LogEntry {
  */
 declare const LOG_KEYS_CONVENTION_REGEX: RegExp;
 
-/**
- * Log keys reserved by `@bymax-one/nest-logger` for its own structured events.
- *
- * Consumer apps SHOULD NOT use these names for application-level events
- * to avoid collision in log aggregation queries (Datadog, Loki, Elastic).
- */
-declare const RESERVED_LOG_KEYS: Readonly<{
-    readonly LOGGER_BOOTSTRAP_OK: "LOGGER_BOOTSTRAP_OK";
-    readonly LOGGER_BOOTSTRAP_WARNING: "LOGGER_BOOTSTRAP_WARNING";
-    readonly LOGGER_SHUTDOWN_OK: "LOGGER_SHUTDOWN_OK";
-    readonly HTTP_REQUEST_START: "HTTP_REQUEST_START";
-    readonly HTTP_REQUEST_SUCCESS: "HTTP_REQUEST_SUCCESS";
-    readonly HTTP_REQUEST_REDIRECT: "HTTP_REQUEST_REDIRECT";
-    readonly HTTP_REQUEST_CLIENT_ERROR: "HTTP_REQUEST_CLIENT_ERROR";
-    readonly HTTP_REQUEST_SERVER_ERROR: "HTTP_REQUEST_SERVER_ERROR";
-    readonly HTTP_REQUEST_COMPLETED: "HTTP_REQUEST_COMPLETED";
-    readonly HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED";
-    readonly HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED";
-    readonly METHOD_EXECUTION: "METHOD_EXECUTION";
-    readonly METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION";
-    readonly LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED";
-    readonly LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED";
-    readonly LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED";
-}>;
-
-export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RequestIdMiddleware, type ResolvedBymaxLoggerModuleOptions, type ServiceMetadata, applyRequestIdMiddleware };
+export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ResolvedBymaxLoggerModuleOptions, type ServiceMetadata, applyRequestIdMiddleware };