@bymax-one/nest-logger 1.2.4 → 1.2.6

package/CHANGELOG.md

@@ -11,6 +11,214 @@ heading here.
 
 ## [Unreleased]
 
+## [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
+
+- **An `Error` handed to the NestJS logger methods is no longer silently dropped.** Reported from a
+  real run rather than a unit test. `@bymax-one/nest-auth` logs the cause the way every caller does,
+  an SMTP `STARTTLS 502` failed, and this is what came out:
+
+  ```js
+  // the call site, nest-auth
+  this.logger.error(`delivery failed for "${subject}"`, error)
+  ```
+
+  ```json
+  {
+    "level": "error",
+    "context": "DefaultAuthEmailProvider",
+    "msg": "delivery failed for \"Verify your email address\""
+  }
+  ```
+
+  No `err`, no `stack`, no warning. The cause existed the whole time and was discarded. The dispatch
+  is fire-and-forget, so the HTTP response was `204` while nothing had been delivered: **the log was
+  the only surface where that failure could appear, and it appeared without its reason.** In CI you
+  can raise the level and re-run; in production nobody runs at `debug`, so the reason was never
+  written at all.
+
+  Neither side was obviously wrong, which is what made it survive. NestJS types the slot as
+  `error(message, stack?: string, context?: string)`, so this library read a string and discarded
+  anything else — implementing the contract faithfully. Passing the `Error` itself is what callers
+  actually do, because every other logger in the ecosystem accepts it.
+
+  **Measured before the fix: eleven of the twelve level/position combinations lost the `Error`.**
+  Only `error(err)` survived — every other level (`log`, `warn`, `debug`, `verbose`, `fatal`) routes
+  through a shared helper that handled no `Error` in either position. `fatal` was the worst of them,
+  being the level a caller reaches for when the process is about to die.
+
+  An `Error` anywhere in the variadic tail is now attached as `err`, the same field the leading-`Error`
+  branch already wrote, at every level. A trailing _string_ is still the `stack`, and `stack` is never
+  populated from an `Error` — the `err` serializer derives it, so writing both would emit the same
+  trace under two names.
+
+  **Detection is structural, not `instanceof`.** The first version of this fix used
+  `instanceof Error`, which is realm-local — so it would still have dropped a genuine `Error` built in
+  a `vm` context, and one already normalized into a plain `{ name, message, stack }`, which is what
+  `HttpExceptionFilter` produces and what any error crossing a process or worker boundary becomes.
+  That is the population most likely to be carrying the reason something failed, and this repository
+  had already recorded the same lesson in `sanitizeError` ("too narrow, and the gap was a live
+  defect"). The bridge now shares `isErrorLike` with `sanitizeError`, so the two cannot disagree about
+  what an error is. The bar stays deliberately narrow — string `name` AND string `message` — so an
+  ordinary metadata object is not mistaken for a cause.
+
+  **Two output changes to expect, since "additive" would overstate it.** Nothing is removed or
+  renamed, and a caller passing a string stack is untouched. But a caller who was passing an `Error`
+  necessarily sees a difference, because that is the defect:
+
+  - entries that silently dropped a cause now carry an `err` object — a **new field** on lines that
+    previously had none, which a strict log-pipeline schema will see;
+  - `warn(new Error('x'))` and the other non-`error` levels now emit `msg: "x"` instead of
+    `msg: "Error: x"`, matching what `error(new Error('x'))` already produced. A query grepping for
+    the `"Error: "` prefix on those levels will stop matching.
+
+  Both are the point of the change rather than side effects, but neither is invisible.
+
+  Scope, as measured by the reporting consumer across the ten `@bymax-one/*` packages that backend
+  installs at its pinned versions: **37 affected call sites, all of them in `nest-auth`**, none
+  elsewhere. Two are security-relevant — a breach check that fails open and logs that it admitted a
+  password it could not verify, and the `onRefreshTokenReuseDetected` hook, the tripwire for a stolen
+  token. Both said something went wrong and threw away what.
+
+### Documentation
+
+- **The `pnpm prune --prod` note named the wrong mechanism.** It described the peer surviving as a
+  _residue_ of an incomplete prune. A second consumer whose Dockerfile never prunes — a clean
+  `pnpm install --prod --frozen-lockfile` in a fresh runtime stage — measured the peer present anyway.
+  In both images the peer was recorded in the lockfile and pnpm placed it in the store for a
+  production-only install. The distinction matters because "we do a clean prod install, not a prune"
+  reads like an exemption and is not one; it is what that consumer expected before measuring their
+  own image.
+
+  The note is now phrased as **two measurements rather than a law of pnpm** — whether a prod install
+  always carries an optional peer, however the lockfile was produced, has not been tested here. The
+  first version of this note over-generalized from the evidence, which is the same class of error as
+  the two corrections it documents.
+
+  The note now also says what is different **elsewhere**: under npm's or yarn's flat `node_modules` a
+  pruned devDependency really is gone, so the warning must not be read as universal. And it records
+  the probe that nearly produced the opposite conclusion — `require.resolve` from the library's
+  app-visible path returns `MODULE_NOT_FOUND` while the lazy import still succeeds, because the
+  library resolves from its real `.pnpm/` path. Verify by behaviour, not from a path the library
+  never uses.
+
 ## [1.2.4] - 2026-08-14
 
 ### Documentation
@@ -922,7 +1130,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.4...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.2.6...HEAD
+[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
 [1.2.2]: https://github.com/bymaxone/nest-logger/compare/v1.2.1...v1.2.2

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
@@ -149,16 +149,31 @@ pnpm add @opentelemetry/api @opentelemetry/sdk-node
 
 ```
 
-> ⚠️ **`-D` does not make it absent in production.** Under pnpm, `pnpm prune --prod` removes the
-> **top-level link** but leaves the package in the store, linked beside this library as the resolved
-> optional peer — and `PrettyDevDestination` imports it lazily, relative to the library's own
-> directory, so it resolves. Verified inside a real pruned production image by a consumer who had
-> assumed the opposite.
+> ⚠️ **Under pnpm, `-D` may not make it absent in production — measure, do not assume.** Two
+> consumers who had assumed otherwise measured the peer **present** in their real production images,
+> by two different build routes: `pnpm prune --prod` keeps the store entry, and a clean
+> `pnpm install --prod --frozen-lockfile` in a fresh stage installs it too. In both, the peer was
+> recorded in the lockfile. `PrettyDevDestination` imports it lazily, relative to the library's own
+> directory under `.pnpm/`, where it is a sibling — so it resolves.
 >
-> So "it is a devDependency, therefore this path cannot run in production" is **not** a safe premise.
-> A `PrettyDevDestination` left registered in production will not crash and will not warn: it renders
-> ANSI colour into a log pipeline that has silently failed to parse every line since the deploy. Gate
-> it on an explicit configuration value you can see, not on the packaging.
+> That is two measurements, not a law of pnpm: whether a production install always carries an optional
+> peer, however the lockfile was produced, has not been tested here. The advice below does not depend
+> on it.
+>
+> The clean-install case is worth stating separately, because "we do a fresh prod install, not a
+> prune" reads like an exemption and is not one. It is what one of those consumers concluded before
+> measuring their own image.
+>
+> **On other package managers this is different**, and the difference cuts the other way: under npm's
+> or yarn's flat `node_modules`, a pruned devDependency really is gone. If you install with those,
+> do not read this warning as universal.
+>
+> Either way, the rule that survives both layouts: **"it is a devDependency, therefore this path
+> cannot run in production" is not a safe premise, because the premise is about someone else's
+> install command.** A `PrettyDevDestination` left registered in production will not crash and will
+> not warn — it renders ANSI colour into a log pipeline that has silently failed to parse every line
+> since the deploy, which is indistinguishable from a service that went quiet. Gate it on an explicit
+> configuration value you can see, not on the packaging.
 
 > [!NOTE]
 > `@opentelemetry/api` is resolved lazily when the Pino instance is built. When it is absent the trace mixin silently steps aside — the logger never fails to start, and never warns, over an optional peer.
@@ -738,6 +753,39 @@ 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.
+
+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
@@ -960,6 +1008,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.