@bymax-one/nest-logger 1.4.2 → 1.4.4

package/CHANGELOG.md

@@ -11,6 +11,137 @@ heading here.
 
 ## [Unreleased]
 
+## [1.4.4] - 2026-11-01
+
+### Documentation
+
+- The Quick Start's "Output (JSON, production)" sample is now exactly what the flow prints:
+  it gains `deployment`, `userId` and `event.name`, and its version matches the snippet. The
+  request and trace fields (`requestId`, `tenantId`, `traceId`, `spanId`) are no longer in it, since
+  they are absent outside an HTTP request and an active span; a sentence says when they appear.
+
+### Tests
+
+- A unit test executes the README Quick Start (sections 2 and 4) as written and asserts the JSON
+  lines it logs. `check:published` only type-checks the snippets; this one runs them. It also
+  requires the README's "Output (JSON, production)" sample to have the same keys as the real line.
+
+## [1.4.3] - 2026-10-31
+
+### Added
+
+- `LOGGER_REDACTOR_TOKEN`, `REDACT_COMMON_FIELDS` and `isValidTraceId` are exported from the package
+  root. The token is the injection point of `PinoLoggerService`'s redactor, so a consumer composing
+  its own providers can now name it. `REDACT_COMMON_FIELDS` is the name list the
+  default redactor matches, and `DEFAULT_REDACT_PATHS` is built from it, so extending the defaults no
+  longer means copying the names. `isValidTraceId` is the check the trace mixin already applies.
+  `sanitizeError` stays internal: its output shape is not a contract this release commits to.
+
+### Deprecated
+
+- `@LogContext(name)` is marked `@deprecated`. It records a label as class metadata and nothing in
+  the package reads it, so the label has never been applied. `@InjectLogger(MyClass.name)` is the
+  working equivalent. `shouldUseAsNestLogger` was already deprecated and is unchanged.
+
+### Fixed
+
+- **A custom `timestamp` can no longer break the log line or add fields to it.** Pino inserts the
+  value into the JSON line verbatim, and the library wrapped it in quotes without encoding it, so a
+  quote, a backslash or a newline in the returned string produced invalid JSON for every entry, and a
+  crafted value such as `","injected":"x` added a field. The value is now encoded as a JSON string,
+  and `time` carries exactly what the function returned.
+
+### Breaking
+
+- **`http.excludePaths` now excludes `/health/live` and `/health/ready` by default**, the probes of
+  `@bymax-one/nest-core`, so the defaults are `/health`, `/health/live`, `/health/ready` and
+  `/metrics`. A probe hit every few seconds drowned the record (8272 of 8274 entries on one
+  deployment). Each default is an exact, anchored path, so a route such as `/health/other` is still
+  logged.
+- **Options are validated more strictly at bootstrap**, each rejection naming the option and, where
+  there is a value to show, what was received. Added checks: `maxEntrySizeBytes` must be a finite number (a `NaN` or `Infinity`
+  made the size gate never trip); `isGlobal`, `shouldDisableDefaultRedact` and the `http` and `otel`
+  switches must be booleans (the string `'false'` is truthy); `redactCensor` a string; `timestamp` a
+  function; `redactPaths` an array of non-empty strings; `serializers` an object of functions;
+  `destinations` an array whose entries have a `write` method, a non-empty `name` and function hooks;
+  `http` and `otel` objects; `http.excludePaths` an array of `RegExp` (a pattern from another realm,
+  such as a `vm` context, is accepted); `http.tenantIdHeader` and the
+  three `otel.*Field` names non-empty strings; `otel.fieldFormat` `'camelCase'` or `'snake_case'`
+  (an unknown value silently behaved as `camelCase`).
+- **`PrettyDevDestination` refuses to initialize when `NODE_ENV` is `production`.** The 0.1.0 entry
+  said it was auto-disabled in production, and nothing did that: registered there it rendered ANSI
+  colour through a main-thread transform into the log stream. It now fails at `onInit()` with a
+  message naming the cause; the registry reports `LOGGER_DESTINATION_INIT_FAILED` on stderr, later
+  writes to it are dropped, and when it is the only destination entries go to stdout as raw NDJSON.
+  Only the exact value `production` refuses.
+
+#### Apply to a consumer
+
+- A deployment whose own `/health/live` or `/health/ready` route should stay in the log now sets
+  `http.excludePaths` itself. A value replaces the defaults, and `[/^\/health$/, /^\/metrics$/]`
+  restores the previous list.
+- An application that passed a value of the wrong kind, such as `http: { isEnabled: 'false' }` or a
+  destination without a `name`, now fails at bootstrap with a message naming the option, where it
+  previously booted with that value ignored or misread. Correct the value.
+- A deployment that registers `PrettyDevDestination` with `NODE_ENV=production` now gets raw JSON on
+  stdout and one stderr line instead of coloured output. Register it only outside production, for
+  example `...(process.env.NODE_ENV === 'production' ? [] : [new PrettyDevDestination()])`, and keep
+  `DefaultStdoutDestination` in the list.
+
+### Documentation
+
+- The error catalog listed codes that nothing in the library emits (for example
+  `LOGGER_INVALID_OPTIONS` and `LOGGER_OTEL_API_UNAVAILABLE`), and described them as thrown. A thrown
+  error carries a message, not a code, so the catalog now separates the message each thrown error
+  starts with from the log keys the library writes. It also gains the errors it omitted and the real
+  surface of a missing `@opentelemetry/api`, a `LOGGER_BOOTSTRAP_WARNING` with
+  `reason: 'OTEL_API_UNAVAILABLE'`.
+  `readme-error-catalog.spec.ts` scans every throw site in `src` and fails when a row and the code
+  disagree in either direction.
+- The README documents the injection tokens and the exported helpers, the `useClass` and
+  `useExisting` forms of `forRootAsync`, the rules the request-id middleware applies to an inbound
+  `x-request-id` and tenant header (a value that fails them is replaced, not cleaned), and that a
+  Fastify adapter is not supported.
+- `forRootAsync` does not register the exception filter, which `forRoot` does, and the README now
+  says so under the async example, in the options table and in the `http` option JSDoc. Measured with
+  the same failing controller on both paths: with `http.isEnabled`, `forRootAsync` emits the access
+  log (`HTTP_REQUEST_START`, `_CLIENT_ERROR`, `_SERVER_ERROR`) and the real error reaches its terminal
+  entry, but not `HTTP_EXCEPTION_HANDLED` or `HTTP_EXCEPTION_UNHANDLED`; the 500 response is
+  identical. Registering `{ provide: APP_FILTER, useClass: HttpExceptionFilter }` yields them. The
+  difference is deliberate, and a spec pins the behaviour and the remedy.
+- `ILogDestination` JSDoc: `write` no longer says a failing destination "may be temporarily
+  skipped". Nothing skips a destination that initialized: every failed entry is dropped for it and
+  reported, and it keeps receiving entries. Only one whose `onInit()` failed receives none.
+  `minLevel` says it can only narrow what the module `level` lets through.
+- The README prose and tables are corrected against the code; that correction touches no source file.
+  - The options table gave `level` a default of `'info'`. Outside `NODE_ENV=production` the default
+    is `'debug'`. It now lists the options it omitted: `isGlobal`, `serializers`, `timestamp`, the
+    deprecated `shouldUseAsNestLogger`, and `otel.traceIdField`, `otel.spanIdField` and
+    `otel.traceFlagsField`.
+  - `DefaultStdoutDestination` was called "always active". It is the default sink only while
+    `destinations` is empty, as the Destinations section already said. A destination whose
+    `onInit()` rejects was described as staying in the write fan-out. It is removed from the fan-out
+    and from shutdown.
+  - The architecture diagram showed `info(logKey, msg, context, metadata)`; the third parameter is
+    `userId`. It named a `composedMixin()` that does not exist (the function is
+    `createTraceContextMixin`) and put `userId` in the scope `RequestIdMiddleware` opens, which holds
+    `requestId` and `tenantId`.
+  - The tech stack badges now read pnpm 11 and tsup 9. The URL normalization lists name ULID and
+    nanoid segments as well as UUID and numeric ones. The `LogContextService` table lists `get()`.
+    The last two HTTP log keys sit inside their table.
+  - The Pino throughput figures are attributed to Pino's own benchmarks, the `Scope.REQUEST` cost
+    to NestJS's estimate, and the EPIPE guard note names its one exception, `pino-pretty`'s own
+    stream.
+  - The resource identity example passed `process.env.POD_UID` to `service.instanceId`, which does
+    not compile under `exactOptionalPropertyTypes` because the value can be `undefined`. It now reads
+    `process.env.POD_UID!`.
+
+### Tests
+
+- `readme-options.spec.ts` parses the three option tables in the README and checks every default
+  against the defaults the module applies, and checks that the tables list exactly the options the
+  module resolves, so a default that drifts, or an option added without a row, fails the suite.
+
 ## [1.4.2] - 2026-10-30
 
 No breaking changes. Dependency and build-tooling maintenance only. No source file under `src/` changes and the
@@ -2076,7 +2207,9 @@ published `dist/` is identical — no runtime behaviour changes for consumers.
 - Professional CI suite: `ci.yml`, `bench.yml`, `codeql.yml`, `scorecard.yml`,
   `release.yml`, Dependabot, and issue templates
 
-[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.4.2...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.4.4...HEAD
+[1.4.4]: https://github.com/bymaxone/nest-logger/compare/v1.4.3...v1.4.4
+[1.4.3]: https://github.com/bymaxone/nest-logger/compare/v1.4.2...v1.4.3
 [1.4.2]: https://github.com/bymaxone/nest-logger/compare/v1.4.1...v1.4.2
 [1.4.1]: https://github.com/bymaxone/nest-logger/compare/v1.4.0...v1.4.1
 [1.4.0]: https://github.com/bymaxone/nest-logger/compare/v1.3.1...v1.4.0