@bymax-one/nest-logger 1.2.7 → 1.3.0

package/dist/server/index.mjs

@@ -351,10 +351,30 @@ function assignIfDefined(payload, key, value) {
 }
 var PinoLoggerService = class {
   /**
+   * **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(pino2, redact = (value) => value) {
     this.pino = pino2;
@@ -1094,9 +1114,35 @@ function reportDestinationFailure(logKey, name, cause, msg) {
   } catch {
   }
 }
+function safeDestinationName(destination) {
+  try {
+    return String(destination.name);
+  } catch {
+    return "unknown";
+  }
+}
+function isLogLevel(value) {
+  return LOG_LEVEL_PRIORITY.includes(value);
+}
+var resolvedMinLevels = /* @__PURE__ */ new WeakMap();
+function safeMinLevel(destination) {
+  if (resolvedMinLevels.has(destination)) {
+    return resolvedMinLevels.get(destination);
+  }
+  let resolved;
+  try {
+    const read = destination.minLevel;
+    resolved = isLogLevel(read) ? read : void 0;
+  } catch {
+    resolved = void 0;
+  }
+  resolvedMinLevels.set(destination, resolved);
+  return resolved;
+}
 
 // src/server/utils/destination-to-stream.ts
-function reportWriteFailure(name, cause) {
+function reportWriteFailure(destination, cause) {
+  const name = safeDestinationName(destination);
   reportDestinationFailure(
     RESERVED_LOG_KEYS.LOGGER_DESTINATION_WRITE_FAILED,
     name,
@@ -1116,7 +1162,8 @@ function destinationToStream(destination, health) {
     decodeStrings: false,
     write(chunk, _encoding, callback) {
       const onFailure = (cause) => {
-        reportWriteFailure(destination.name, cause);
+        health.markWriteFailed(destination);
+        reportWriteFailure(destination, cause);
         callback();
       };
       try {
@@ -1129,10 +1176,20 @@ function destinationToStream(destination, health) {
           return;
         }
         const result = destination.write(payload);
-        if (result instanceof Promise) {
-          result.then(() => callback(), onFailure);
-        } else {
+        if (result === void 0) {
           callback();
+        } else {
+          health.markWritePending(destination);
+          Promise.resolve(result).then(
+            () => {
+              health.markWriteSettled(destination);
+              callback();
+            },
+            (cause) => {
+              health.markWriteSettled(destination);
+              onFailure(cause);
+            }
+          );
         }
       } catch (cause) {
         onFailure(cause);
@@ -1164,10 +1221,11 @@ function resolveToJson(value) {
   };
 }
 function cloneError(error) {
-  const clone = Object.create(
-    Object.getPrototypeOf(error),
-    Object.getOwnPropertyDescriptors(error)
-  );
+  const descriptors = Object.getOwnPropertyDescriptors(error);
+  for (const descriptor of Object.values(descriptors)) {
+    descriptor.configurable = true;
+  }
+  const clone = Object.create(Object.getPrototypeOf(error), descriptors);
   const { stack } = error;
   if (typeof stack === "string") {
     Reflect.defineProperty(clone, "stack", { value: stack, enumerable: false });
@@ -1175,11 +1233,8 @@ function cloneError(error) {
   return clone;
 }
 var BUFFER_TO_JSON = Buffer.prototype.toJSON;
-var WRITE_FAILED = new Error();
 function defineOwn(target, key, value) {
-  if (!Reflect.defineProperty(target, key, { value, enumerable: true })) {
-    throw WRITE_FAILED;
-  }
+  Reflect.defineProperty(target, key, { value, enumerable: true });
 }
 function walkArray(value, sensitive, censor, depth2, ancestors) {
   const length = value.length;
@@ -1577,7 +1632,11 @@ function buildPinoInstance(options, logContext, destinations, health) {
     }
   };
   const streams = destinations.map((destination) => ({
-    level: destination.minLevel ?? options.level,
+    // Guarded: this runs at provider construction, BEFORE any lifecycle hook, so a
+    // consumer implementing `minLevel` as a throwing getter would fail the factory
+    // and the application would never start — earlier than any fail-soft path can
+    // contain. Unreadable and absent give the same answer: the module level.
+    level: safeMinLevel(destination) ?? options.level,
     stream: destinationToStream(destination, health)
   }));
   return pino(pinoOptions, pino.multistream(streams));
@@ -1587,24 +1646,91 @@ var DestinationHealth = class {
     /** Destinations whose `onInit()` rejected. Identity-keyed, not name-keyed. */
     this.failed = /* @__PURE__ */ new Set();
     /**
-     * Whether ANY destination initialized successfully.
+     * Destinations that initialized, each with its effective level as an index into
+     * {@link LOG_LEVEL_PRIORITY}.
+     *
+     * Keyed by identity rather than reduced to a flag or a minimum, because the
+     * question a buffering destination asks is "did SOMEONE ELSE receive what I
+     * received?" — and a minimum cannot exclude the asker. A destination that is
+     * itself the only healthy sink would otherwise be told its held entries were
+     * delivered elsewhere, and discard its only copies.
+     *
+     * The level matters for the same reason it does everywhere here: `pino.multistream`
+     * filters per stream, so "alive" and "received what I received" are different
+     * facts.
+     */
+    this.healthy = /* @__PURE__ */ new Map();
+    /**
+     * Destinations whose `write()` threw or rejected at least once.
+     *
+     * Init health says a sink is LIVE; it does not say the sink accepted anything.
+     * A destination that throws on write is reported and skipped per entry, so
+     * inferring delivery from level alone would credit it with entries it dropped.
+     * Uncertainty drains, so any write failure disqualifies it as proof of delivery
+     * for the whole window — coarser than per-entry tracking, and wrong only in the
+     * direction that duplicates rather than loses.
+     */
+    this.writeFailed = /* @__PURE__ */ new Set();
+    /**
+     * In-flight asynchronous writes per destination.
+     *
+     * A rejected async write is only recorded when its promise settles, and the
+     * registry can compute readiness while one is still pending — so "no failure
+     * recorded" is not "every write landed". A destination with anything in flight
+     * is UNPROVEN rather than trusted: counting it as delivery would let a
+     * buffering sink discard its copy moments before the pending write rejects.
      *
-     * A boolean rather than a count, deliberately: the only question ever asked of
-     * it is "is there somewhere to write?". Mutation testing made the point — a
-     * counter incremented with `+=` survived being flipped to `-=`, because
-     * `count === 0` means the same thing either way. A value whose arithmetic
-     * cannot be observed was not a counter, it was a flag wearing a number.
+     * A counter rather than a flag because writes overlap; it returns to zero only
+     * when the last one settles.
      */
-    this.hasHealthy = false;
+    this.pendingWrites = /* @__PURE__ */ new Map();
     /**
      * The rescuer's severity index within {@link LOG_LEVEL_PRIORITY}. Starts above
      * every real level so the first `markFailed` always wins the comparison.
      */
     this.rescuerLevel = Number.POSITIVE_INFINITY;
   }
-  /** Record that a destination initialized successfully. */
-  markHealthy() {
-    this.hasHealthy = true;
+  /**
+   * Record that a destination's `write()` threw or rejected.
+   *
+   * Called from the fan-out's failure path, which already reports the entry as
+   * dropped. This is what stops {@link deliveredByHealthySink} from crediting a
+   * throwing sink with entries it never accepted.
+   *
+   * @param destination - The destination whose write failed.
+   */
+  markWriteFailed(destination) {
+    this.writeFailed.add(destination);
+  }
+  /**
+   * Record that an asynchronous write to a destination has started.
+   *
+   * @param destination - The destination being written to.
+   */
+  markWritePending(destination) {
+    this.pendingWrites.set(destination, (this.pendingWrites.get(destination) ?? 0) + 1);
+  }
+  /**
+   * Record that an asynchronous write has settled, however it settled.
+   *
+   * Paired with {@link markWritePending} on both the fulfilled and rejected
+   * paths — a counter that only decremented on success would never return to
+   * zero for a failing sink, which is a different claim from the one this makes.
+   *
+   * @param destination - The destination whose write settled.
+   */
+  markWriteSettled(destination) {
+    this.pendingWrites.set(destination, (this.pendingWrites.get(destination) ?? 1) - 1);
+  }
+  /**
+   * Record that a destination initialized successfully.
+   *
+   * @param destination - The destination that initialized.
+   * @param effectiveLevel - Its multistream level: `minLevel` when set, otherwise
+   *   the module-wide `level`.
+   */
+  markHealthy(destination, effectiveLevel) {
+    this.healthy.set(destination, LOG_LEVEL_PRIORITY.indexOf(effectiveLevel));
   }
   /**
    * Record that a destination failed to initialize, and re-elect the rescuer.
@@ -1655,7 +1781,31 @@ var DestinationHealth = class {
    *   rescuer.
    */
   shouldRescue(destination) {
-    return !this.hasHealthy && this.rescuer === destination;
+    return this.healthy.size === 0 && this.rescuer === destination;
+  }
+  /**
+   * Whether a LIVE sink received everything a destination at `effectiveLevel`
+   * received — the question a destination holding pre-init entries actually has
+   * before discarding them.
+   *
+   * Not "did any sink survive": `pino.multistream` filters per stream, so a
+   * healthy `error` sink never saw the `info` entries a pretty sink at `info`
+   * buffered. Discarding those because something else was alive would lose them,
+   * which is the failure the buffer exists to prevent. A healthy sink whose level
+   * is at or below this one accepted a superset, so those entries are delivered.
+   *
+   * @param effectiveLevel - The asking destination's multistream level.
+   * @returns `true` when a live sink accepted everything this destination did.
+   */
+  deliveredByHealthySink(asking, effectiveLevel) {
+    const level = LOG_LEVEL_PRIORITY.indexOf(effectiveLevel);
+    for (const [destination, healthyLevel] of this.healthy) {
+      const unproven = this.writeFailed.has(destination) || (this.pendingWrites.get(destination) ?? 0) > 0;
+      if (destination !== asking && !unproven && healthyLevel <= level) {
+        return true;
+      }
+    }
+    return false;
   }
 };
 DestinationHealth = __decorateClass([
@@ -1707,14 +1857,70 @@ var DestinationRegistry = class {
       try {
         await destination.onInit?.();
         this.active.push(destination);
-        this.health.markHealthy();
+        this.health.markHealthy(destination, this.effectiveLevelOf(destination));
       } catch (cause) {
-        this.health.markFailed(destination, destination.minLevel ?? this.options.level);
-        this.reportInitFailure(destination.name, cause);
+        this.health.markFailed(destination, this.effectiveLevelOf(destination));
+        this.reportInitFailure(destination, cause);
       }
     }
+    await this.notifyRegistryReady();
     this.announceBootstrap();
   }
+  /**
+   * Tell every REGISTERED destination — live or failed — what happened to the
+   * entries it may be holding, before the first post-init entry is emitted.
+   *
+   * The signal it carries is one the destination cannot compute: whether ANOTHER
+   * live sink appears to have accepted everything this one accepted.
+   * `pino.multistream` filters per stream, a destination is not its own witness, a
+   * sink whose write threw did not receive that entry, and one whose write has not
+   * settled has shown nothing yet — all of which live in `deliveredByHealthySink`.
+   *
+   * A signal rather than a proof, deliberately: a write still queued inside the
+   * `Writable` adapter is invisible to that accounting, so the flag says which
+   * risk is smaller, not that the entry is safe. See `ILogDestination.onRegistryReady`.
+   *
+   * Each notification is isolated: a destination that throws here is reported and
+   * skipped rather than aborting the remaining ones or the bootstrap entry.
+   * Failing at this hook cannot be allowed to cost more than the hook was worth.
+   */
+  async notifyRegistryReady() {
+    for (const destination of this.registered) {
+      try {
+        await destination.onRegistryReady?.({
+          heldEntriesDeliveredElsewhere: this.health.deliveredByHealthySink(
+            destination,
+            this.effectiveLevelOf(destination)
+          )
+        });
+      } catch (cause) {
+        this.reportHookFailure(destination, cause);
+      }
+    }
+  }
+  /**
+   * The severity a destination actually receives: the STRICTER of the module
+   * level and its own `minLevel`.
+   *
+   * Pino filters at the instance level BEFORE `pino.multistream` sees an entry,
+   * so a `minLevel` below the global one cannot widen what a destination gets —
+   * the factory's own docs say so. Recording the raw `minLevel` therefore
+   * understated delivery: with a global `error` and a healthy sink at `info`,
+   * both sinks in fact receive the same `error` entries, but a pretty sink
+   * declared at `trace` compared as `trace`, delivery read as unproven, and the
+   * buffer drained raw — a duplicate produced by arithmetic rather than by any
+   * real gap.
+   *
+   * @param destination - The destination whose threshold is being computed.
+   * @returns The level entries must clear to reach it.
+   */
+  effectiveLevelOf(destination) {
+    const configured = safeMinLevel(destination);
+    if (configured === void 0) {
+      return this.options.level;
+    }
+    return LOG_LEVEL_PRIORITY.indexOf(configured) > LOG_LEVEL_PRIORITY.indexOf(this.options.level) ? configured : this.options.level;
+  }
   /**
    * Report one destination init failure as a structured
    * `LOGGER_DESTINATION_INIT_FAILED` line on `process.stderr`.
@@ -1723,10 +1929,13 @@ var DestinationRegistry = class {
    * than restating the shape, so an operator greps one `logKey` regardless of
    * which stage failed — and the two cannot drift apart.
    *
-   * @param name - The failing destination's name.
+   * @param destination - The failing destination. Passed whole, so its `name` is
+   *   read under `safeDestinationName` rather than at the call site — which sits
+   *   inside the catch, where a throwing getter would abort bootstrap.
    * @param cause - The thrown or rejected value.
    */
-  reportInitFailure(name, cause) {
+  reportInitFailure(destination, cause) {
+    const name = safeDestinationName(destination);
     reportDestinationFailure(
       RESERVED_LOG_KEYS.LOGGER_DESTINATION_INIT_FAILED,
       name,
@@ -1734,6 +1943,30 @@ var DestinationRegistry = class {
       `Log destination "${name}" failed to initialize and will receive no entries. If no destination initializes, entries fall back to raw NDJSON on stdout.`
     );
   }
+  /**
+   * Report a failure from the readiness hook, with wording that matches the
+   * destination's actual state.
+   *
+   * The loop calls every registered destination, healthy and failed alike, so one
+   * message cannot be true for both. A healthy one keeps receiving entries and was
+   * never an init failure; a failed one was already dropped from the fan-out and
+   * saying it "remains active" would contradict the report it just got. The key
+   * stays `LOGGER_DESTINATION_INIT_FAILED` either way so an operator greps one
+   * thing across every destination-lifecycle problem.
+   *
+   * @param destination - The destination whose hook threw.
+   * @param cause - The thrown value.
+   */
+  reportHookFailure(destination, cause) {
+    const stillActive = !this.health.isFailed(destination);
+    const name = safeDestinationName(destination);
+    reportDestinationFailure(
+      RESERVED_LOG_KEYS.LOGGER_DESTINATION_INIT_FAILED,
+      name,
+      cause,
+      `Log destination "${name}" threw from onRegistryReady. ` + (stillActive ? "It initialized successfully and keeps receiving entries; only anything it was holding from before init may be affected." : "It had already failed to initialize and receives no entries; anything it was still holding is lost.")
+    );
+  }
   /**
    * Emit the one-shot bootstrap entries, AFTER every destination has been
    * initialized.
@@ -1790,14 +2023,50 @@ var DestinationRegistry = class {
       try {
         await destination.onShutdown?.();
       } catch (cause) {
-        const detail = cause instanceof Error ? cause.stack ?? cause.message : String(cause);
-        writeStderrSafely(
-          `[DestinationRegistry] Shutdown failed for "${destination.name}": ${detail}
-`
-        );
+        this.reportShutdownFailure(destination, cause);
       }
     }
   }
+  /**
+   * Report a failing `onShutdown` on stderr without letting the report itself
+   * abort the teardown of the destinations still queued behind it.
+   *
+   * The coercion is INSIDE the guard, not above it. Reading `stack`/`message` on
+   * an `Error` with hostile getters, and `String(cause)` on a value with a
+   * throwing `toString`/`Symbol.toPrimitive`, both throw — and this runs inside
+   * the `catch` that exists to keep one bad sink from mattering, so an escape
+   * here would propagate out of `onApplicationShutdown` and skip every remaining
+   * destination's flush. The never-throw contract has to cover READING the value,
+   * not just writing it, which is the same correction `reportDestinationFailure`
+   * already carries.
+   *
+   * The text is escaped for the same reason every other terminal-bound path is:
+   * a stack is legitimately multi-line, so `escapeControlCharacters` keeps its
+   * newlines and neutralizes everything else that can drive a terminal.
+   *
+   * The DESTINATION is passed rather than its name, so that read happens in here
+   * too. `name` is declared `readonly name: string` but nothing stops a consumer
+   * implementing it as a getter, and reading it at the call site would put it back
+   * outside the guard — inside the `catch`, where a throw has the same cost.
+   *
+   * Two separate guards, not one: a name that cannot be read must not also cost
+   * the failure detail, and a detail that cannot be read must not cost the name.
+   * Either alone still identifies which sink failed.
+   *
+   * @param destination - The destination whose `onShutdown` threw.
+   * @param cause - The thrown value, of any shape.
+   */
+  reportShutdownFailure(destination, cause) {
+    const name = toSingleLineMessage(safeDestinationName(destination));
+    let detail = "UnknownError";
+    try {
+      const stack = isErrorLike(cause) ? cause.stack : void 0;
+      detail = stack === void 0 ? toSingleLineMessage(isErrorLike(cause) ? String(cause.message) : String(cause)) : escapeControlCharacters(String(stack));
+    } catch {
+    }
+    writeStderrSafely(`[DestinationRegistry] Shutdown failed for "${name}": ${detail}
+`);
+  }
   /**
    * The destinations that initialized successfully.
    *
@@ -2148,9 +2417,6 @@ var PrettyDevDestination = class {
       });
     } catch {
       this.initFailed = true;
-      this.flushBuffer((payload) => {
-        writeRawToStdout(payload);
-      });
       throw new Error(
         "[PrettyDevDestination] pino-pretty is not installed. Install it as a peer dependency (`pnpm add -D pino-pretty`) or remove PrettyDevDestination from `destinations`."
       );
@@ -2201,6 +2467,41 @@ var PrettyDevDestination = class {
     this.buffer.push(payload);
     this.bufferedBytes += payloadBytes;
   }
+  /**
+   * 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) {
+    this.flushBuffer(
+      status.heldEntriesDeliveredElsewhere ? () => void 0 : writeRawToStdout
+    );
+  }
   /**
    * Hand every buffered entry to `emit`, in arrival order, and empty the buffer.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-logger",
-  "version": "1.2.7",
+  "version": "1.3.0",
   "description": "Structured JSON logging for NestJS based on Pino 10, with optional OpenTelemetry correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -57,6 +57,7 @@
     "bench": "node --expose-gc --import tsx bench/throughput.bench.ts",
     "build": "pnpm clean && tsup",
     "check:exports": "attw --pack .",
+    "check:docs": "node scripts/check-doc-snippets.mjs",
     "check:mutants": "node scripts/check-mutation-directives.mjs",
     "check:published": "node scripts/check-published-surface.mjs",
     "clean": "rm -rf dist coverage",
@@ -66,7 +67,7 @@
     "mutation:full": "node -e \"require('node:fs').rmSync('reports/stryker-incremental.json',{force:true,recursive:true})\" && stryker run",
     "mutation:dry-run": "stryker run --dryRunOnly",
     "prepare": "husky",
-    "prepublishOnly": "pnpm clean && pnpm typecheck && pnpm lint && pnpm check:mutants && pnpm test:cov:all && pnpm build && pnpm check:published",
+    "prepublishOnly": "pnpm clean && pnpm typecheck && pnpm lint && pnpm check:mutants && pnpm check:docs && pnpm test:cov:all && pnpm build && pnpm check:published",
     "release": "npm publish --provenance --access public",
     "size": "node scripts/check-size.mjs",
     "test": "jest",