@bymax-one/nest-logger 1.2.5 → 1.2.7

package/CHANGELOG.md

@@ -11,6 +11,223 @@ heading here.
 
 ## [Unreleased]
 
+## [1.2.7] - 2026-08-15
+
+### Security
+
+- **Serializer output is redacted by name under `redactStrategy: 'paths'` too.** Carrying an
+  error's own properties at every depth of the `cause` chain (below) opened a hole in that legacy
+  mode: the name walk is a pass-through there, so redaction fell entirely to `fast-redact`, and
+  `DEFAULT_REDACT_PATHS` reaches `*.*.*.*.password` — four wildcard levels. A serialized cause chain
+  goes deeper. Measured on the built artifact with a password on the deepest link of
+  `err.errors[0].cause.cause`:
+
+  ```json
+  { "cause": { "name": "Error", "message": "deep", "password": "LEAK-deep" } }
+  ```
+
+  Confirmed absent from `1.2.6`, where the field was not carried at all — so this was a regression
+  introduced inside this release rather than an inherited one, and it never reached a published
+  artifact.
+
+  `redactStrategy` is the consumer's choice about **their own payload**; what a serializer
+  synthesizes is this library's output, and the name walk — which has no depth ceiling — now covers
+  it either way. The caller's record is untouched by this: `'paths'` still means exactly what it
+  documented, four-level ceiling included, and the e2e case that pins that ceiling is what caught
+  the first attempt at this fix collapsing both hooks onto one redactor.
+
+  Reported by Copilot on the pull request that introduced the deeper copy.
+
+- **An own `__proto__` key on an error is now stored as data instead of being applied as a
+  prototype.** The own-property copy assigned each key, and `__proto__` is an accessor inherited
+  from `Object.prototype` — so the assignment walked the chain, invoked that setter, and replaced
+  the sanitized node's prototype. An error-like object arriving from JSON (a worker boundary, a
+  queue, an HTTP body) carries `__proto__` as an ordinary own enumerable key, and `Object.entries`
+  hands it over like any other.
+
+  Measured rather than assumed. `Object.prototype` itself is never touched, so this is prototype
+  injection into a single log node rather than global pollution, and with a JSON-sourced payload the
+  emitted line was unchanged — `JSON.stringify` ignores inherited fields. The live hazard is the
+  node: given `{"__proto__": null}` it loses `hasOwnProperty` and `toString`, which then **throw**
+  for anything downstream that touches them, inside the one path whose contract is that logging
+  never crashes the application.
+
+  The copy now defines an own data property, which makes the key inert and keeps its value — an
+  error that genuinely carries a `__proto__` field gets it logged as the data it is. Reported by
+  Copilot on the pull request that introduced the deeper copy.
+
+### Documentation
+
+- **`ignore` needs an escaped dot for `event.name`, and every example here taught the opposite.**
+  `pino-pretty` reads a dot as a nested path, and this library emits `event.name` as a literal
+  top-level key — so `ignore: '…,event.name'` looks for an `event` object with a `name` inside,
+  finds neither, and hides nothing without a word of complaint. Measured on one entry with only the
+  option changing:
+
+  ```
+  ignore: '…,event.name'    → INFO: msg {"logKey":"X","event.name":"x"}   ← still there
+  ignore: '…,event\\.name'  → INFO: msg {"logKey":"X"}                    ← hidden
+  ```
+
+  Found by a consumer who copied the `1.2.6` example verbatim, configured it, and saw the field
+  still on screen. The escaped form is now in the `PrettyViewOptions` JSDoc — where an editor's
+  autocomplete shows it, which is where someone actually is when writing the option — in the README,
+  and in the `1.2.6` example itself, which is corrected rather than left to keep teaching it.
+
+### Fixed
+
+- **An error's own properties now survive at every depth of the `cause` chain, not just at the top.**
+  `code`, `statusCode` and any domain field an application attaches were copied onto the error handed
+  to the log call and **dropped the moment that same error was wrapped as someone else's `cause`** —
+  which is what a `catch` in `main.ts` does routinely. Measured on the published `1.2.6`:
+
+  ```json
+  {
+    "type": "Error",
+    "message": "bootstrap failed",
+    "code": "EBOOT",
+    "cause": { "name": "Error", "message": "config invalid" }
+  }
+  ```
+
+  The inner error carried `code: "BYMAX_CONFIG_VALIDATION"` and an `issues` array holding one entry
+  per invalid variable. Both vanished. The reporting consumer framed the severity exactly right:
+  because `message` survives and their message is the full aggregated report, **the human stayed
+  served while the machine went blind** — the text an operator reads was intact, and the fields an
+  alert or a dashboard keys on were gone.
+
+  Nothing justified the asymmetry. The reason own properties are "part of the contract" at the top —
+  `pino.stdSerializers.err` copied them, so dropping them is a silent compatibility loss — is the
+  same reason one level down, and a wrapped error is the common case rather than the exotic one.
+  They still never shadow a field the serializer derives, and they still pass through the same
+  name-based redaction and size bound as any other serializer output.
+
+  Found by following up an asymmetry noticed while answering a consumer's question about how to pass
+  an error through the NestJS bridge — not by a bug report.
+
+### Changed
+
+- **The own-property copy lives in one place instead of two.** The `err` serializer read the raw
+  thrown value and walked its properties itself, duplicating what the sanitizer now does at every
+  node; it copies from the sanitized node instead. Same fields, one walk — and no second copy to
+  drift away from the first.
+
+## [1.2.6] - 2026-08-15
+
+### Added
+
+- **`PrettyDevDestination` takes a `view`, so the terminal rendering is the consumer's choice.**
+  Requested with the measurement that makes the case — one real entry rendered three ways through
+  `pino-pretty`, where only the options differ:
+
+  ```
+  A) the built-in view                                   7 lines for one entry
+  B) singleLine + an extended ignore list                1 line, fields kept
+  C) hideObject + messageFormat '[{context}] {msg}'      1 line, message only
+  ```
+
+  All of it was reachable in `pino-pretty` and none of it was reachable through this library, which
+  hard-coded five options and read only `minLevel` from its constructor.
+
+  ```ts
+  new PrettyDevDestination({
+    view: { singleLine: true, ignore: 'pid,hostname,service,deployment,event\\.name' }
+  })
+  ```
+
+  `PrettyViewOptions` covers `singleLine`, `ignore`, `hideObject`, `messageFormat`, `translateTime`
+  and `colorize`. **Additive** — every field defaults to what it rendered before, so
+  `new PrettyDevDestination()` is unchanged.
+
+  **`destination` is deliberately not exposed.** The library owns where entries go; a redirected
+  stream would route around the multistream fan-out and the last-resort rescue. It is absent from
+  the type AND applied after the consumer's options are spread, so an untyped JavaScript caller
+  cannot smuggle one in either — omitting it from a type is a suggestion, ordering the spread is the
+  guarantee.
+
+  The options bag is this library's **own** interface rather than `pino-pretty`'s `PrettyOptions`,
+  and that is load-bearing rather than stylistic: a type import from the peer emits a hard
+  `import { PrettyOptions } from 'pino-pretty'` on line 4 of the published `.d.ts`, so every consumer
+  who type-checks without the optional peer installed would hit an unresolved module. That would make
+  an optional peer effectively required. Measured on the built artifact.
+
+### Fixed
+
+- **Entries emitted before the pretty transform exists are now rendered, not dumped raw.** A real
+  boot put **43 raw NDJSON lines on screen before the first rendered one** — every entry NestJS emits
+  while instantiating providers, because the transform cannot be built until `onInit` (loading the
+  optional peer is async). Nothing was ever lost, but a developer who had just enabled pretty output
+  saw a screen of JSON and concluded it had not worked. That is what was reported.
+
+  Those entries are now held and flushed **through** the transform once it exists, in arrival order.
+  Nothing is lost on any path, which is the property the raw passthrough had and the buffer had to
+  keep:
+
+  - **init fails** → the held entries are drained raw, because the renderer they were waiting for is
+    never coming;
+  - **a bound is reached** (1000 entries or 4 MiB, whichever trips first — nothing guarantees
+    `onInit` ever runs) → the buffer drains raw _before_ the entry that tripped it, so output stays
+    in order rather than replaying old entries after newer ones;
+  - **shutdown before init** → drained raw rather than dying with the process.
+
+  The byte ceiling is there because the entry count alone does not bound memory: a payload has no
+  whole-record size limit (`maxEntrySizeBytes` bounds what a serializer emits for one field, not the
+  entry), so 1000 held entries carrying large metadata could retain far more than the count suggests
+  — where the raw passthrough this buffer replaced retained nothing at all.
+
+- **A closed pipe can no longer crash the host, which the `try/catch` around
+  `process.stdout.write` never actually prevented.** Every fallback path in this library — the
+  last-resort NDJSON rescue, the pre-init drain, the destination failure reports — wrapped its raw
+  write in a `try/catch` and documented that as EPIPE protection. It is not, and this was measured
+  rather than argued:
+
+  ```
+  stdout error listeners at start: 0
+  sync result: no-throw          ← the try/catch caught nothing
+  UNCAUGHT:EPIPE                 ← arrived later, as an uncaught exception
+  child exit code: 42            ← the process died
+  ```
+
+  A closed pipe (`node app | head`) reports EPIPE **asynchronously**, through the stream's `'error'`
+  event, after `write()` has already returned. Node attaches no default handler, so the emit becomes
+  an uncaught exception. The guarantee was asserted in prose and absent from the code, on exactly the
+  paths whose purpose is to survive a broken sink.
+
+  Every library-owned write to a process stream now goes through one `safe-stdio` helper that
+  installs a swallow-EPIPE handler on first use, covering the asynchronous half; the `try/catch`
+  remains for the synchronous half, since either alone leaves a way to die. The handler is found by
+  identity rather than remembered, so anything that strips listeners from a process stream cannot
+  silently disable the protection permanently.
+
+  **This includes `DefaultStdoutDestination`, and that is the half that actually mattered.** The
+  first version of the fix guarded only the fallback paths — the rescue, the drain, the failure
+  reports — none of which a healthy application ever takes. The default sink, which is what a
+  consumer gets when they configure nothing, still called `process.stdout.write` directly, so the
+  ordinary install was exactly as crashable as before. Caught in review and then reproduced against
+  the built artifact: `0` listeners, no synchronous throw, `UNCAUGHT:EPIPE`, exit 42. Re-measured
+  after the fix: survived, exit 0.
+
+  `PrettyDevDestination` is deliberately **not** guarded by this library. `pino-pretty` receives
+  `process.stdout` and attaches two `'error'` listeners of its own; a child piped to a closed reader
+  survived and exited 0 with nothing from us on the stream, so a guard there would be code whose
+  need is disproven. A test pins that, and goes red if `pino-pretty` ever stops attaching them.
+
+  One consequence worth stating rather than burying: after the first log line, `process.stdout` has a
+  swallowing `'error'` listener that belongs to this library, so an EPIPE raised by **your** writes
+  to stdout also stops being an uncaught exception. That is the trade — the alternative is the crash
+  above — and your own `'error'` listener is never removed or replaced.
+
+  Reported by Copilot against the new pre-init buffer, then a second time against the incomplete
+  fix; the same ineffective pattern was already shipped in `1.2.3` and `1.2.5`, so this corrects
+  those paths too.
+
+- **A write after a failed init is verifiably dropped, not merely silent.** Adding the buffer made
+  "dropped" and "held" observationally identical — the existing case asserted only that nothing
+  reached stdout, and buffering produces the same silence. A **cold** mutation run caught it
+  (the incremental runs had been reporting 100% while the cold run read 99.62%, with all three
+  survivors in this file). The case now shuts down after the failed init, which drains anything
+  still held: a merely-buffered entry surfaces there, a dropped one does not.
+
 ## [1.2.5] - 2026-08-14
 
 ### Fixed
@@ -1014,7 +1231,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.2.5...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.2.7...HEAD
+[1.2.7]: https://github.com/bymaxone/nest-logger/compare/v1.2.6...v1.2.7
+[1.2.6]: https://github.com/bymaxone/nest-logger/compare/v1.2.5...v1.2.6
 [1.2.5]: https://github.com/bymaxone/nest-logger/compare/v1.2.4...v1.2.5
 [1.2.4]: https://github.com/bymaxone/nest-logger/compare/v1.2.3...v1.2.4
 [1.2.3]: https://github.com/bymaxone/nest-logger/compare/v1.2.2...v1.2.3

package/README.md

@@ -60,7 +60,7 @@ pnpm add @bymax-one/nest-logger
 - ✅ **Structured JSON** — every entry has `level`, `time`, `service`, `logKey`, `msg`, and arbitrary metadata fields
 - ✅ **`MODULE_ACTION_RESULT` Log Keys** — a naming convention enforced by an exported regex for CI validation
 - ✅ **NestJS `LoggerService` Bridge** — drop-in replacement; all NestJS internal logs flow through Pino
-- ✅ **Pretty-Print in Dev** — opt-in `PrettyDevDestination` for readable local output (requires optional `pino-pretty`)
+- ✅ **Pretty-Print in Dev** — opt-in `PrettyDevDestination` with a configurable `view` (single-line, hidden fields, message-only) for readable local output (requires optional `pino-pretty`)
 - ✅ **Field Size Guard** — a serialized field over the ceiling (default 64 KB) is replaced by a compact truncation envelope instead of flooding the sink
 
 ### 🛡️ Security & Privacy
@@ -534,6 +534,32 @@ any other field. `AggregateError` members reach the entry as `err.errors`. There
 OpenTelemetry attribute for a cause chain, so these stay namespaced under `err` rather than
 inventing an `exception.cause` the spec does not define.
 
+**An error's own enumerable properties travel with it at every depth** — `code` on a Node system
+error, `statusCode` from an HTTP layer, whatever domain fields you attached — including on a nested
+`cause` and on each `AggregateError` member:
+
+```json
+{
+  "err": {
+    "type": "Error",
+    "message": "bootstrap failed",
+    "code": "EBOOT",
+    "cause": {
+      "name": "Error",
+      "message": "config invalid",
+      "code": "BYMAX_CONFIG_VALIDATION",
+      "issues": [{ "variable": "DATABASE_URL", "code": "invalid_url" }]
+    }
+  }
+}
+```
+
+This matters because `code` is usually the field you alert on. Until 1.2.7 those properties survived
+only on the error handed to the log call and were dropped the moment the same error was wrapped as
+someone else's `cause` — which is what a `catch` in `main.ts` does routinely. They never shadow a
+field the serializer derives, and they pass through the same name-based redaction and size bound as
+any other serializer output.
+
 An error's own enumerable properties (`code`, `statusCode`, domain fields) are carried through, as
 Pino's standard serializer did.
 
@@ -753,6 +779,48 @@ The consequence worth knowing: a sink you supply may be the **only** one the app
 
 So the common accident — adding `new PrettyDevDestination()` without installing the optional `pino-pretty` — costs you colours and a line on stderr telling you why, never your logs.
 
+### Choosing how the dev terminal renders
+
+`PrettyDevDestination` takes a `view`. Every field defaults to what it rendered before, so `new PrettyDevDestination()` is unchanged — the options exist because the default view is deliberately verbose, and one entry can be seven lines.
+
+```typescript
+// One line per entry, with the fields your project repeats on every line hidden.
+new PrettyDevDestination({
+  view: { singleLine: true, ignore: 'pid,hostname,service,deployment,event\\.name' }
+})
+
+// Message only, with the context pulled back into the line.
+new PrettyDevDestination({
+  view: { hideObject: true, messageFormat: '[{context}] {msg}' }
+})
+```
+
+| Field           | Default                  | Notes                                                                        |
+| --------------- | ------------------------ | ---------------------------------------------------------------------------- |
+| `singleLine`    | `false`                  | The single biggest change to how a terminal reads                            |
+| `ignore`        | `'pid,hostname,service'` | Display-only — what a real sink receives is untouched                        |
+| `hideObject`    | `false`                  | Hides the record entirely; see the caveat below                              |
+| `messageFormat` | —                        | e.g. `'[{context}] {msg}'`; how to keep one field visible under `hideObject` |
+| `translateTime` | `'SYS:HH:MM:ss.l'`       | Or `false` for the raw timestamp                                             |
+| `colorize`      | `true`                   | ANSI colour                                                                  |
+
+> **`hideObject` hides it everywhere.** In pretty mode there is no JSON copy behind the rendering, because `destinations` **replaces** stdout — so a field hidden here, `logKey` included, is not visible anywhere. That is what the option is for; `messageFormat` is how you pull a specific field back.
+
+> **A dot in `ignore` means "nested path", so a field name that CONTAINS a dot must escape it.** This library emits `event.name` as a literal top-level key, so the obvious spelling hides nothing at all — `pino-pretty` looks for an `event` object with a `name` inside, finds neither, and says nothing. Measured on one entry with 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`. `service` and `deployment` need no escape; they really are nested objects. Reported by a consumer who copied the example above when it still had the unescaped form.
+
+The shape is exported as `PrettyViewOptions` when you want to build the view separately — it is this library's own interface, not a re-export of `pino-pretty`'s `PrettyOptions`, so type-checking without the optional peer installed still resolves.
+
+> **`destination` is not exposed, by design.** The library owns where entries go — a redirected stream would route around the fan-out and the last-resort rescue above. It is absent from the type and applied after your options are merged, so it cannot be overridden from untyped JavaScript either.
+
+**The first entries of a boot are held, not lost.** The transform cannot exist until `onInit` — loading the optional peer is async — so everything NestJS emits while instantiating providers arrives before it. Those entries are buffered and then rendered through the transform in arrival order. If the peer is missing, the bound is reached, or the app shuts down before init, they are written as raw NDJSON instead: degraded, never dropped.
+
 ### Postgres destination (Prisma)
 
 ```typescript
@@ -975,6 +1043,14 @@ Trace context is never copied verbatim into a log entry. The OTel mixin reads th
 
 Every `write()` runs inside a try/catch. A destination that throws or rejects produces a `LOGGER_DESTINATION_WRITE_FAILED` line on `stderr` — never back through the logger, which would turn a broken sink into a write → log → write feedback loop — and the entry is dropped for that sink only. A destination whose `onInit()` rejects is reported as `LOGGER_DESTINATION_INIT_FAILED` and excluded from the shutdown sequence without blocking boot; it stays in the write fan-out, where the same fail-soft wrapper contains it. A logging backend going down degrades logging — it never takes the application with it.
 
+### A closed pipe does not kill the process
+
+`node app | head` closes the read end of stdout while the application is still writing. The stream reports that as `EPIPE` **asynchronously**, through its `'error'` event, after `write()` has already returned — so a `try/catch` around the write catches nothing, and because Node attaches no default handler to `process.stdout`, the emit becomes an uncaught exception and the process dies. Measured, not assumed: `0` listeners, no synchronous throw, `UNCAUGHT:EPIPE`, exit 42.
+
+Every write this library makes to a process stream — the default stdout sink, the last-resort rescue, the pre-init drain, the `stderr` failure reports — installs a swallowing `'error'` listener on first use. **The side effect is worth knowing:** that listener is on the shared `process.stdout`, so after the first log line an EPIPE raised by _your_ writes stops being an uncaught exception too. The alternative is the crash above. Your own `'error'` listener is never removed or replaced — this only ever adds one.
+
+If you write to `process.stdout` from a custom `ILogDestination`, do the same in your own sink; the [destinations guide](./docs/guidelines/DESTINATIONS-IMPLEMENTATION-GUIDELINES.md) has the exact pattern.
+
 ### Bounded field size
 
 Every serializer — the default `err` one and any you supply — is wrapped so a field whose serialized JSON exceeds `maxEntrySizeBytes` (64 KB by default) is replaced by a compact envelope: `_truncated`, `_logKey: 'LOGGER_ENTRY_TRUNCATED'`, `_originalSize`, and a 200-character `_preview`. An accidentally logged webhook payload costs a bounded number of bytes and leaves a record that truncation happened, instead of flooding the sink.