@bymax-one/nest-logger 1.2.6 → 1.2.9

package/dist/server/index.d.cts

@@ -69,12 +69,55 @@ interface ILogDestination {
      *
      * @param payload — Newline-terminated JSON entry, UTF-8 encoded.
      */
-    write(payload: string): void | Promise<void>;
+    write(payload: string): void | PromiseLike<void>;
     /**
      * Optional lifecycle hook — called once during NestJS module init.
      * Use for opening connections, allocating buffers, scheduling flushers.
      */
-    onInit?(): void | Promise<void>;
+    onInit?(): void | PromiseLike<void>;
+    /**
+     * Optional lifecycle hook — called once after EVERY destination's `onInit`
+     * has settled, successfully or not, and before the bootstrap entry is emitted.
+     *
+     * Only useful to a destination that holds entries written before its own
+     * `onInit` ran: until this point it cannot know what became of them. The
+     * fan-out hands each entry to every registered destination whose level accepts
+     * it, so a held copy may be a SECOND copy.
+     *
+     * **This is a deduplication signal, not a proof — and the difference is the
+     * whole contract.** A held copy may be a second copy, so emitting it duplicates
+     * a line and dropping it may lose one. The flag says which risk is smaller, as
+     * far as this library can see; it does not say the entry is safe.
+     *
+     * The library's own destinations act on it by discarding when it is `true` and
+     * emitting otherwise, because a duplicated boot line is a smaller harm than a
+     * lost one. **A destination that cannot tolerate ANY loss should emit
+     * regardless** — see the accounting limits on the flag below.
+     *
+     * Called on failed destinations too, which is the point: the one that could not
+     * initialize is exactly the one still holding entries.
+     *
+     * @param status.heldEntriesDeliveredElsewhere - Whether another live sink
+     *   accepted everything this destination accepted, as far as this library can
+     *   see. `true` requires that sink to be not this one, initialized, at or below
+     *   this level, with no write failure and no write still in flight; anything
+     *   less certain is `false`.
+     *
+     *   **What it cannot see:** a write still QUEUED inside the `Writable` adapter,
+     *   behind a slow async sink that has not been called yet. So `true` can precede
+     *   a queued write that later fails, and there is no flag that distinguishes
+     *   that case — which is exactly why this is a tradeoff rather than a
+     *   guarantee. It normally arrives, being queued rather than lost.
+     *
+     * @returns Nothing, or a promise the library AWAITS. Returning one is
+     *   supported deliberately: TypeScript accepts an `async` implementation where
+     *   a void-returning member is declared, so a hook that was not awaited would
+     *   reject into nothing and let the bootstrap entry be emitted before the
+     *   buffer had been resolved.
+     */
+    onRegistryReady?(status: {
+        readonly heldEntriesDeliveredElsewhere: boolean;
+    }): void | PromiseLike<void>;
     /**
      * Optional lifecycle hook — called during NestJS `onApplicationShutdown`.
      * MUST flush any pending writes and close resources.
@@ -82,7 +125,7 @@ interface ILogDestination {
      * The library awaits this — graceful shutdown blocks until all destinations
      * return.
      */
-    onShutdown?(): void | Promise<void>;
+    onShutdown?(): void | PromiseLike<void>;
 }
 
 /**
@@ -636,10 +679,30 @@ declare class PinoLoggerService implements LoggerService, OnApplicationShutdown
     private readonly redact;
     private context?;
     /**
+     * **A hand-built instance is NOT this library's behaviour.** Constructing
+     * `new PinoLoggerService(pino({...}, sink))` directly works in the sense of not
+     * throwing, and the parameter default below exists for exactly that — but the
+     * Pino instance you built has none of the wiring `buildPinoInstance` installs,
+     * and the omissions are silent:
+     *
+     *   - **no `err` serializer**, so an `Error` is serialized by Pino's default.
+     *     The `cause` chain disappears ENTIRELY — no marker, no warning, and a
+     *     `cause` that reads as "the field was never set";
+     *   - **no name-based redaction** of serializer output or child bindings;
+     *   - **no trace-context mixin**, so `requestId` / `tenantId` / OTel ids are
+     *     absent;
+     *   - **no size bound**, so nothing is truncated.
+     *
+     * That matters most for tests, which is the use this doc used to invite without
+     * qualification: a consumer wrote one to check whether a `cause` carried its
+     * `code`, measured absence, and nearly filed it against this library. The
+     * absence was their harness. For a faithful harness, boot the module (or use
+     * `BymaxLoggerModule.forRoot` in a testing module) rather than hand-building.
+     *
      * @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.
+     *   Defaults to the identity so a hand-built instance still works; the module
+     *   always injects the configured one.
      */
     constructor(pino: Logger, redact?: Redactor);
     /**
@@ -899,7 +962,7 @@ declare class DefaultStdoutDestination implements ILogDestination {
  *   // One line per entry, with the fields a project repeats on every line hidden.
  *   const view: PrettyViewOptions = {
  *     singleLine: true,
- *     ignore: 'pid,hostname,service,deployment,event.name'
+ *     ignore: 'pid,hostname,service,deployment,event\\.name'
  *   }
  */
 interface PrettyViewOptions {
@@ -914,19 +977,60 @@ interface PrettyViewOptions {
      * what a real sink receives is untouched. Extend rather than replace when the
      * goal is quieter output — the default already hides the noisiest fields.
      * Default: `'pid,hostname,service'`.
+     *
+     * **A dot means "nested path", so a field name CONTAINING a dot has to escape
+     * it.** This library emits `event.name` as a literal top-level key, so the
+     * obvious spelling silently hides nothing — `pino-pretty` looks for an `event`
+     * object with a `name` inside and finds neither. Measured on one entry, only
+     * the option changing:
+     *
+     * ```
+     * ignore: '…,event.name'    → INFO: msg {"logKey":"X","event.name":"x"}   ← still there
+     * ignore: '…,event\\.name'  → INFO: msg {"logKey":"X"}                    ← hidden
+     * ```
+     *
+     * In a TypeScript string literal that is `'event\\.name'` — one real backslash
+     * reaching `pino-pretty`. Nested objects (`service`, `deployment`) need no
+     * escape; they really are paths.
      */
     ignore?: string;
     /**
-     * Render only the message line, hiding the record entirely. In pretty mode
-     * there is no JSON copy behind it (`destinations` REPLACES stdout), so a field
-     * hidden here is not visible anywhere — including `logKey`. That is the point
-     * of the option rather than a caveat; use `messageFormat` to pull a specific
-     * field back into the line. Default: `false`.
+     * Render only the message line, hiding the record entirely. Display-only, and
+     * scoped to THIS destination: a field hidden here is still delivered in full to
+     * every other destination registered alongside it.
+     *
+     * When pretty is the ONLY destination, that scope makes it total — `destinations`
+     * replaces the default stdout sink, so there is no JSON copy behind the
+     * rendering and a hidden field, `logKey` included, is not visible anywhere. That
+     * is the point of the option rather than a caveat; use `messageFormat` to pull a
+     * specific field back into the line. Default: `false`.
      */
     hideObject?: boolean;
     /**
      * Template for the message line, e.g. `'[{context}] {msg}'`. The way to keep a
      * chosen field visible when `hideObject` is on.
+     *
+     * **Every placeholder EXCEPT `{msg}` is interpolated raw, and that reopens
+     * terminal log forging.** This library normalizes line separators and control
+     * characters in `msg` and in the stack — not in metadata, because escaping data
+     * would mean rewriting what you asked to be logged. `pino-pretty` substitutes
+     * whatever the field holds, so a newline in an interpolated field splits one
+     * entry into two, and the second reads like a genuine record. Measured, with a
+     * newline in `context`:
+     *
+     * ```
+     * lines produced by ONE entry: 2
+     *   1: "[10:35:14.484] INFO: [Auth"
+     *   2: "[10:00:00.000] INFO: FORGED admin promoted] real entry …"
+     * ```
+     *
+     * So: interpolate only fields whose values your own code sets. Never a field
+     * carrying user input — `{tenantId}`, `{userId}`, a header, a query value. If
+     * you need one of those visible, leave it in the record instead of the format
+     * string. That closes THIS path — the raw placeholder — and no more: a metadata
+     * value is not safe terminal text either, because `JSON.stringify` escapes only
+     * C0 and emits DEL, the C1 range (U+0085 NEL included), U+2028 and U+2029
+     * verbatim. Only `msg` and the stack carry the one-entry-one-line guarantee.
      */
     messageFormat?: string;
     /** Timestamp format, or `false` to leave it raw. Default: `'SYS:HH:MM:ss.l'`. */
@@ -949,7 +1053,7 @@ interface PrettyViewOptions {
  *
  *   // One line per entry, with this project's repeated fields hidden.
  *   new PrettyDevDestination({
- *     view: { singleLine: true, ignore: 'pid,hostname,service,deployment,event.name' }
+ *     view: { singleLine: true, ignore: 'pid,hostname,service,deployment,event\\.name' }
  *   })
  *
  *   // Message-only, with the context pulled back into the line.
@@ -1031,6 +1135,39 @@ declare class PrettyDevDestination implements ILogDestination {
      * @param payload — Newline-terminated JSON entry, UTF-8 encoded.
      */
     write(payload: string): void;
+    /**
+     * Resolve anything still held, now that the registry knows what became of it.
+     *
+     * **Discard only where another sink is believed to have taken the same entries;
+     * emit everything else.** Losing a boot entry is not an acceptable outcome, and
+     * every richer policy tried here had a losing branch: trusting "a sink survived"
+     * lost entries to a sink at a higher level, trusting a level lost them to a sink
+     * that was itself the asker, then to one whose writes were throwing, then to one
+     * whose write had not settled yet. Each of those is now folded into the single
+     * signal handed in — and where it is uncertain, it says `false` and this drains.
+     *
+     * That signal is not a proof, and this hook does not treat it as one. It cannot
+     * see an entry still queued inside the `Writable` adapter, because the adapter
+     * has not called `destination.write()` for it yet. Discarding on it is a bet
+     * that a duplicated boot line costs less than a lost one — which is the trade
+     * this destination accepts, and which a destination that cannot lose anything
+     * should decline by ignoring the flag and always emitting.
+     *
+     * The cost is stated rather than hidden: when nothing survived, every holding
+     * destination drains, so N of them produce N copies of the boot entries. A
+     * duplicated line in an already-degraded boot is a smaller harm than a lost one,
+     * and it is loud rather than silent.
+     *
+     * A no-op once {@link onInit} succeeded — the buffer was flushed through the
+     * transform there and is already empty.
+     *
+     * @param status.heldEntriesDeliveredElsewhere - Another live sink appears to
+     *   have taken everything this one took. A deduplication signal, not a proof —
+     *   see `ILogDestination.onRegistryReady` for what it cannot see.
+     */
+    onRegistryReady(status: {
+        readonly heldEntriesDeliveredElsewhere: boolean;
+    }): void;
     /**
      * Hand every buffered entry to `emit`, in arrival order, and empty the buffer.
      *

package/dist/server/index.d.ts

@@ -69,12 +69,55 @@ interface ILogDestination {
      *
      * @param payload — Newline-terminated JSON entry, UTF-8 encoded.
      */
-    write(payload: string): void | Promise<void>;
+    write(payload: string): void | PromiseLike<void>;
     /**
      * Optional lifecycle hook — called once during NestJS module init.
      * Use for opening connections, allocating buffers, scheduling flushers.
      */
-    onInit?(): void | Promise<void>;
+    onInit?(): void | PromiseLike<void>;
+    /**
+     * Optional lifecycle hook — called once after EVERY destination's `onInit`
+     * has settled, successfully or not, and before the bootstrap entry is emitted.
+     *
+     * Only useful to a destination that holds entries written before its own
+     * `onInit` ran: until this point it cannot know what became of them. The
+     * fan-out hands each entry to every registered destination whose level accepts
+     * it, so a held copy may be a SECOND copy.
+     *
+     * **This is a deduplication signal, not a proof — and the difference is the
+     * whole contract.** A held copy may be a second copy, so emitting it duplicates
+     * a line and dropping it may lose one. The flag says which risk is smaller, as
+     * far as this library can see; it does not say the entry is safe.
+     *
+     * The library's own destinations act on it by discarding when it is `true` and
+     * emitting otherwise, because a duplicated boot line is a smaller harm than a
+     * lost one. **A destination that cannot tolerate ANY loss should emit
+     * regardless** — see the accounting limits on the flag below.
+     *
+     * Called on failed destinations too, which is the point: the one that could not
+     * initialize is exactly the one still holding entries.
+     *
+     * @param status.heldEntriesDeliveredElsewhere - Whether another live sink
+     *   accepted everything this destination accepted, as far as this library can
+     *   see. `true` requires that sink to be not this one, initialized, at or below
+     *   this level, with no write failure and no write still in flight; anything
+     *   less certain is `false`.
+     *
+     *   **What it cannot see:** a write still QUEUED inside the `Writable` adapter,
+     *   behind a slow async sink that has not been called yet. So `true` can precede
+     *   a queued write that later fails, and there is no flag that distinguishes
+     *   that case — which is exactly why this is a tradeoff rather than a
+     *   guarantee. It normally arrives, being queued rather than lost.
+     *
+     * @returns Nothing, or a promise the library AWAITS. Returning one is
+     *   supported deliberately: TypeScript accepts an `async` implementation where
+     *   a void-returning member is declared, so a hook that was not awaited would
+     *   reject into nothing and let the bootstrap entry be emitted before the
+     *   buffer had been resolved.
+     */
+    onRegistryReady?(status: {
+        readonly heldEntriesDeliveredElsewhere: boolean;
+    }): void | PromiseLike<void>;
     /**
      * Optional lifecycle hook — called during NestJS `onApplicationShutdown`.
      * MUST flush any pending writes and close resources.
@@ -82,7 +125,7 @@ interface ILogDestination {
      * The library awaits this — graceful shutdown blocks until all destinations
      * return.
      */
-    onShutdown?(): void | Promise<void>;
+    onShutdown?(): void | PromiseLike<void>;
 }
 
 /**
@@ -636,10 +679,30 @@ declare class PinoLoggerService implements LoggerService, OnApplicationShutdown
     private readonly redact;
     private context?;
     /**
+     * **A hand-built instance is NOT this library's behaviour.** Constructing
+     * `new PinoLoggerService(pino({...}, sink))` directly works in the sense of not
+     * throwing, and the parameter default below exists for exactly that — but the
+     * Pino instance you built has none of the wiring `buildPinoInstance` installs,
+     * and the omissions are silent:
+     *
+     *   - **no `err` serializer**, so an `Error` is serialized by Pino's default.
+     *     The `cause` chain disappears ENTIRELY — no marker, no warning, and a
+     *     `cause` that reads as "the field was never set";
+     *   - **no name-based redaction** of serializer output or child bindings;
+     *   - **no trace-context mixin**, so `requestId` / `tenantId` / OTel ids are
+     *     absent;
+     *   - **no size bound**, so nothing is truncated.
+     *
+     * That matters most for tests, which is the use this doc used to invite without
+     * qualification: a consumer wrote one to check whether a `cause` carried its
+     * `code`, measured absence, and nearly filed it against this library. The
+     * absence was their harness. For a faithful harness, boot the module (or use
+     * `BymaxLoggerModule.forRoot` in a testing module) rather than hand-building.
+     *
      * @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.
+     *   Defaults to the identity so a hand-built instance still works; the module
+     *   always injects the configured one.
      */
     constructor(pino: Logger, redact?: Redactor);
     /**
@@ -899,7 +962,7 @@ declare class DefaultStdoutDestination implements ILogDestination {
  *   // One line per entry, with the fields a project repeats on every line hidden.
  *   const view: PrettyViewOptions = {
  *     singleLine: true,
- *     ignore: 'pid,hostname,service,deployment,event.name'
+ *     ignore: 'pid,hostname,service,deployment,event\\.name'
  *   }
  */
 interface PrettyViewOptions {
@@ -914,19 +977,60 @@ interface PrettyViewOptions {
      * what a real sink receives is untouched. Extend rather than replace when the
      * goal is quieter output — the default already hides the noisiest fields.
      * Default: `'pid,hostname,service'`.
+     *
+     * **A dot means "nested path", so a field name CONTAINING a dot has to escape
+     * it.** This library emits `event.name` as a literal top-level key, so the
+     * obvious spelling silently hides nothing — `pino-pretty` looks for an `event`
+     * object with a `name` inside and finds neither. Measured on one entry, only
+     * the option changing:
+     *
+     * ```
+     * ignore: '…,event.name'    → INFO: msg {"logKey":"X","event.name":"x"}   ← still there
+     * ignore: '…,event\\.name'  → INFO: msg {"logKey":"X"}                    ← hidden
+     * ```
+     *
+     * In a TypeScript string literal that is `'event\\.name'` — one real backslash
+     * reaching `pino-pretty`. Nested objects (`service`, `deployment`) need no
+     * escape; they really are paths.
      */
     ignore?: string;
     /**
-     * Render only the message line, hiding the record entirely. In pretty mode
-     * there is no JSON copy behind it (`destinations` REPLACES stdout), so a field
-     * hidden here is not visible anywhere — including `logKey`. That is the point
-     * of the option rather than a caveat; use `messageFormat` to pull a specific
-     * field back into the line. Default: `false`.
+     * Render only the message line, hiding the record entirely. Display-only, and
+     * scoped to THIS destination: a field hidden here is still delivered in full to
+     * every other destination registered alongside it.
+     *
+     * When pretty is the ONLY destination, that scope makes it total — `destinations`
+     * replaces the default stdout sink, so there is no JSON copy behind the
+     * rendering and a hidden field, `logKey` included, is not visible anywhere. That
+     * is the point of the option rather than a caveat; use `messageFormat` to pull a
+     * specific field back into the line. Default: `false`.
      */
     hideObject?: boolean;
     /**
      * Template for the message line, e.g. `'[{context}] {msg}'`. The way to keep a
      * chosen field visible when `hideObject` is on.
+     *
+     * **Every placeholder EXCEPT `{msg}` is interpolated raw, and that reopens
+     * terminal log forging.** This library normalizes line separators and control
+     * characters in `msg` and in the stack — not in metadata, because escaping data
+     * would mean rewriting what you asked to be logged. `pino-pretty` substitutes
+     * whatever the field holds, so a newline in an interpolated field splits one
+     * entry into two, and the second reads like a genuine record. Measured, with a
+     * newline in `context`:
+     *
+     * ```
+     * lines produced by ONE entry: 2
+     *   1: "[10:35:14.484] INFO: [Auth"
+     *   2: "[10:00:00.000] INFO: FORGED admin promoted] real entry …"
+     * ```
+     *
+     * So: interpolate only fields whose values your own code sets. Never a field
+     * carrying user input — `{tenantId}`, `{userId}`, a header, a query value. If
+     * you need one of those visible, leave it in the record instead of the format
+     * string. That closes THIS path — the raw placeholder — and no more: a metadata
+     * value is not safe terminal text either, because `JSON.stringify` escapes only
+     * C0 and emits DEL, the C1 range (U+0085 NEL included), U+2028 and U+2029
+     * verbatim. Only `msg` and the stack carry the one-entry-one-line guarantee.
      */
     messageFormat?: string;
     /** Timestamp format, or `false` to leave it raw. Default: `'SYS:HH:MM:ss.l'`. */
@@ -949,7 +1053,7 @@ interface PrettyViewOptions {
  *
  *   // One line per entry, with this project's repeated fields hidden.
  *   new PrettyDevDestination({
- *     view: { singleLine: true, ignore: 'pid,hostname,service,deployment,event.name' }
+ *     view: { singleLine: true, ignore: 'pid,hostname,service,deployment,event\\.name' }
  *   })
  *
  *   // Message-only, with the context pulled back into the line.
@@ -1031,6 +1135,39 @@ declare class PrettyDevDestination implements ILogDestination {
      * @param payload — Newline-terminated JSON entry, UTF-8 encoded.
      */
     write(payload: string): void;
+    /**
+     * Resolve anything still held, now that the registry knows what became of it.
+     *
+     * **Discard only where another sink is believed to have taken the same entries;
+     * emit everything else.** Losing a boot entry is not an acceptable outcome, and
+     * every richer policy tried here had a losing branch: trusting "a sink survived"
+     * lost entries to a sink at a higher level, trusting a level lost them to a sink
+     * that was itself the asker, then to one whose writes were throwing, then to one
+     * whose write had not settled yet. Each of those is now folded into the single
+     * signal handed in — and where it is uncertain, it says `false` and this drains.
+     *
+     * That signal is not a proof, and this hook does not treat it as one. It cannot
+     * see an entry still queued inside the `Writable` adapter, because the adapter
+     * has not called `destination.write()` for it yet. Discarding on it is a bet
+     * that a duplicated boot line costs less than a lost one — which is the trade
+     * this destination accepts, and which a destination that cannot lose anything
+     * should decline by ignoring the flag and always emitting.
+     *
+     * The cost is stated rather than hidden: when nothing survived, every holding
+     * destination drains, so N of them produce N copies of the boot entries. A
+     * duplicated line in an already-degraded boot is a smaller harm than a lost one,
+     * and it is loud rather than silent.
+     *
+     * A no-op once {@link onInit} succeeded — the buffer was flushed through the
+     * transform there and is already empty.
+     *
+     * @param status.heldEntriesDeliveredElsewhere - Another live sink appears to
+     *   have taken everything this one took. A deduplication signal, not a proof —
+     *   see `ILogDestination.onRegistryReady` for what it cannot see.
+     */
+    onRegistryReady(status: {
+        readonly heldEntriesDeliveredElsewhere: boolean;
+    }): void;
     /**
      * Hand every buffered entry to `emit`, in arrival order, and empty the buffer.
      *