@bymax-one/nest-config 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -11,6 +11,93 @@ as the GitHub Release body, so each released version needs a matching
 
 ## [Unreleased]
 
+## [1.1.3] - 2026-08-18
+
+**Documentation.** The runtime bundles are byte-identical to `1.1.2`. Five files differ: the
+two `./internal` declaration files, by the JSDoc noted below; `README.md` and `CHANGELOG.md`;
+and `package.json`, by its `version` field alone. Verified by hashing every file in the
+published `1.1.2` tarball against this build.
+
+### Documentation
+
+- **How to report the failure is documented, because the two obvious ways are not
+  equivalent.** `onValidationError` said what the hook is and nothing about logging what it
+  hands you, which left the choice at the call site with no way to know the cost. `code` and
+  `issues` are the only two own enumerable properties of `BymaxConfigValidationError`,
+  while `name`, `message` and `stack` are non-enumerable as on any `Error`. That splits the
+  outcome three ways by representation: an error object keeps everything when the serializer
+  extracts the standard fields and copies the own enumerables, which are two separate steps; `error.stack` keeps the report and drops `code` and `issues`;
+  and a plain `JSON.stringify(error)` keeps `code` and `issues` and drops the report.
+  Which representation reaches the sink is decided by the logging call, and that call is
+  library-specific — Pino serializes an error only as the merging object or under `err`,
+  and drops it entirely when it is passed as a trailing argument. The machine-readable half is the easy one to
+  lose, precisely because the report keeps arriving — `code` separates a configuration
+  failure from any other boot failure, and `issues` is what an alert keys on per variable.
+
+  Wrapping the error as a `cause` also keeps all of it, wherever the serializer walks the
+  chain the same way. Measured against `@bymax-one/nest-logger` 1.2.7 and 1.2.9 rather
+  than assumed: a fifteen-issue report crosses the chain with every issue and the full multi-line
+  `message` intact.
+
+  Versions 1.2.6 through 1.2.9 carry a defect the README states in full: handed this error
+  **directly**, the redactor dropped the whole `err` field, leaving `_redactionFailed: true`
+  and no report at all. The trigger was `issues` rather than `code`, and the property
+  definition rather than freezing: this error is not frozen — it defines `code` and `issues`
+  as non-writable, non-configurable own properties and freezes the issue list, while the
+  instance stays extensible. Only the locked object property failed, because the redactor's
+  clone inherited the locked descriptors and redefining a non-configurable property fails
+  exactly when the value differs, which a structurally copied object does and an identical
+  string does not.
+
+  **Fixed upstream in `1.3.0`**, measured against the published package rather than taken on
+  report: a real failure logged directly now arrives with `type, message, stack, code,
+issues`, the full issue array and the multi-line report intact, and this error is left
+  untouched. On an affected version the workaround stands, and it is something a consumer
+  writes: a `catch` receives this error unchanged, since the module rethrows the instance it
+  caught, so wrapping is an explicit `new Error(message, { cause: error })`.
+
+  The rule also covers the call site where this failure usually lands: a `catch` in
+  `main.ts` runs before any logging module is registered, so it reports through
+  `console.error`. Node's inspector appends an error's own enumerables after the stack,
+  so `console.error(message, error)` prints the report, the `code` and the expanded `issues`, while
+  `console.error(message, error.stack)` prints the report alone — the same split, one layer
+  earlier.
+
+  The same fact is now stated on `BymaxConfigValidationError` itself, so it reaches a
+  consumer through the published types and not only through the README.
+
+## [1.1.2] - 2026-08-14
+
+**Documentation only.** `dist/` is byte-identical to `1.1.1`, verified by hashing every file in
+the published tarball against a local build. Inside the package only `README.md`, `CHANGELOG.md`
+and the `version` field of `package.json` differ.
+
+### Documentation
+
+- **The `1.1.1` apply-note understated the work for a consumer with a mutation gate.** It said
+  a derived backend has nothing to change, which is true for correctness and wrong as an
+  estimate. Under Stryker, a message string literal is a mutant: authoring messages for rules
+  that had none converts operator-facing prose into tested behavior, and a repo gating at
+  `break: 100` fails until an assertion pins each message. Reported by a consumer adopting
+  `1.1.1`, which added one assertion per message to keep its gate green.
+
+  The honest version of the note: **upgrading changes nothing** — a rule that carries no
+  message renders exactly as it did before, verified byte-for-byte on a real boot. **Writing
+  the messages the release makes worth writing is real work**: wherever mutation testing is a
+  gate, every message needs an assertion that covers it — one assertion on the rendered report
+  can cover several — and that is the work the release exists to enable.
+
+  Also worth knowing before writing them: a rule whose variable is _absent_ rendered
+  `missing required value` on `1.1.0`, not `invalid value`. For a conditionally-required
+  variable that is the more misleading of the two — nothing was forgotten, another variable
+  made it required — so the before/after is larger than the `invalid value` case suggests.
+
+- The mutation badge read **99.59%**; the score measured as the `v1.1.1` release gate is
+  **99.61%**. The denominator grew with the new code — 14 more killed mutants in
+  `env-validator.ts`, the only file the release changed executably, and the same single
+  counted survivor — so the badge, the README claim and `docs/mutation_testing_results.md`
+  now state the measured number, with a dated re-run entry recording it.
+
 ## [1.1.1] - 2026-08-14
 
 ### Fixed
@@ -231,4 +318,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.0.3]: https://github.com/bymaxone/nest-config/compare/v1.0.2...v1.0.3
 [1.1.0]: https://github.com/bymaxone/nest-config/compare/v1.0.3...v1.1.0
 [1.1.1]: https://github.com/bymaxone/nest-config/compare/v1.1.0...v1.1.1
-[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.1.1...HEAD
+[1.1.2]: https://github.com/bymaxone/nest-config/compare/v1.1.1...v1.1.2
+[1.1.3]: https://github.com/bymaxone/nest-config/compare/v1.1.2...v1.1.3
+[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.1.3...HEAD

package/README.md

@@ -14,7 +14,7 @@
   <a href="https://www.npmjs.com/package/@bymax-one/nest-config"><img src="https://img.shields.io/npm/dm/@bymax-one/nest-config?style=flat-square&colorA=000000&colorB=000000" alt="npm downloads" /></a>
   <a href="https://github.com/bymaxone/nest-config/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/bymaxone/nest-config/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI" alt="CI status" /></a>
   <a href="https://github.com/bymaxone/nest-config/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000" alt="coverage" /></a>
-  <a href="https://github.com/bymaxone/nest-config/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-99.59%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
+  <a href="https://github.com/bymaxone/nest-config/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-99.61%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/bymaxone/nest-config"><img src="https://api.scorecard.dev/projects/github.com/bymaxone/nest-config/badge?style=flat-square" alt="OpenSSF Scorecard" /></a>
   <a href="https://github.com/bymaxone/nest-config/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bymaxone/nest-config?style=flat-square&colorA=000000&colorB=000000" alt="license" /></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
@@ -327,6 +327,83 @@ export interface ConfigIssue {
 error's own `code`) and `ConfigIssueCode` (each issue's `code`); see the
 error catalog below for every value.
 
+### Reporting the failure
+
+`onValidationError` receives `ReadonlyArray<ConfigIssue>` — four string fields per
+issue, JSON-serializable, with no error to unwrap. Every description this package
+generates is value-free, so it can go straight into a log as structured data. The
+exception is the one described above: a `custom` message written by your own schema
+is printed as written, so if one of yours interpolates a value, reviewing it before
+it reaches a log is the schema author's job, not this package's.
+
+If you also log the thrown error from a bootstrap `catch`, how you pass it decides
+what survives. `code` and `issues` are the **only two own enumerable properties** of
+`BymaxConfigValidationError`; `name`, `message` and `stack` are non-enumerable, as
+on any `Error`. That splits the outcome three ways — all three measured:
+
+| Which representation reaches the sink                                                                   | The report (`message`) | `code` and `issues` |
+| ------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------- |
+| the error object, read by a serializer that extracts the standard fields **and** copies own enumerables | ✅                     | ✅                  |
+| `error.stack`                                                                                           | ✅ inside the string   | ❌                  |
+| `JSON.stringify(error)`, `{ ...error }`                                                                 | ❌                     | ✅                  |
+
+Recognizing an `Error` is not enough on its own: extracting `name`, `message` and
+`stack` is what preserves the report, and copying the own enumerables is a separate
+step that preserves `code` and `issues`. A serializer that does only the second is
+the third row — `code` and `issues` and no report at all — so if you build the log
+record by hand, add `message` explicitly.
+
+**Which representation the sink sees is decided by your logging call, and that call
+is library-specific.** These are measured, not assumed:
+
+```typescript
+console.error('configuration invalid', error) // report, code and issues
+pino.error({ err: error }, 'configuration invalid') // report, code and issues
+pino.error('configuration invalid', error) // the error is dropped entirely
+
+// @bymax-one/nest-logger 1.2.6-1.2.9: wrap it, explicitly (see the note below)
+nestLogger.error('BOOT_FAILED', new Error('bootstrap failed', { cause: error }))
+```
+
+Pino only applies error serialization when the error is the merging object or sits
+under `err`; passed as a trailing argument it is treated as an interpolation value,
+and nothing about the failure reaches the entry.
+
+> [!NOTE]
+> **`@bymax-one/nest-logger` 1.2.6 through 1.2.9 dropped this error when it was logged
+> directly.** Its redactor left `_redactionFailed: true` and no `err` field at all —
+> no report, no `code`, no `issues`. The trigger was the definition rather than any
+> freezing: this error defines `code` and `issues` as non-writable, non-configurable
+> own properties, and the redactor's clone inherited those descriptors, so rewriting
+> the object-valued one with a walked copy failed. A locked scalar was unaffected,
+> which is why `code` alone never reproduced it.
+>
+> Fixed in **1.3.0**, measured rather than taken on report: a real failure logged
+> directly now arrives with `type, message, stack, code, issues`, the full issue array
+> and the report intact, and this error is left untouched. Measured affected: 1.2.6, 1.2.7
+> and 1.2.9 — 1.2.8 was never published, and on 1.2.2 and earlier this call shape does not
+> attach the error at all, so the defect does not arise there in this form. On an affected
+> version, wrap it — a `catch` receives this error unchanged, since the
+> module rethrows the instance it caught, so wrapping is an explicit
+> `new Error(message, { cause: error })` rather than a side effect of catching. A
+> lockfile pinned below 1.3.0 does not pick the fix up from an ordinary install, so the
+> update has to be deliberate.
+
+Wrapping the error as the `cause` of an error you construct keeps all of it wherever the
+serializer walks the chain — measured against `@bymax-one/nest-logger` 1.2.7 and
+1.2.9, where a fifteen-issue report crosses the chain with `code`, every issue and
+the full multi-line `message` intact.
+
+Before any logger exists — which is where this failure usually lands, since a `catch`
+in `main.ts` runs before the logging module is registered — `console.error` is the
+reporter, and Node's inspector prints the stack and then appends the own enumerables.
+So `console.error(message, error)` shows the report, the `code` and the expanded
+`issues` list, while `console.error(message, error.stack)` shows the report alone.
+
+Losing the machine-readable half is easy to miss precisely because the report keeps
+arriving: `code` is what separates a configuration failure from any other boot
+failure, and `issues` is what an alert or a dashboard keys on per variable.
+
 ### Injection tokens
 
 `BYMAX_CONFIG` and `BYMAX_CONFIG_OPTIONS` are module-local `Symbol` tokens,
@@ -514,7 +591,7 @@ Configuration decides whether a process may start at all, so the suite is held t
 beyond "the tests pass".
 
 - ✅ **100% line coverage** — statements, branches, functions and lines, enforced as a gate
-- ✅ **99.59% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
+- ✅ **99.61% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
   `break: 95`; ten provable equivalents carry their reason inline, and the one survivor left
   is an equivalent no directive can reach, so it stays counted rather than silenced
   ([report](./docs/mutation_testing_results.md))

package/dist/internal/index.d.cts

@@ -167,6 +167,10 @@ interface ConfigIssue {
  * constraints, never their received values — except where a schema author's own
  * `custom` message says otherwise, as described on {@link ConfigIssue}.
  *
+ * `code` and `issues` are its only own enumerable properties, so a structured
+ * logger that copies own enumerables keeps both; passing `error.stack` instead of
+ * the error keeps neither.
+ *
  * @example
  * ```typescript
  * try {

package/dist/internal/index.d.ts

@@ -167,6 +167,10 @@ interface ConfigIssue {
  * constraints, never their received values — except where a schema author's own
  * `custom` message says otherwise, as described on {@link ConfigIssue}.
  *
+ * `code` and `issues` are its only own enumerable properties, so a structured
+ * logger that copies own enumerables keeps both; passing `error.stack` instead of
+ * the error keeps neither.
+ *
  * @example
  * ```typescript
  * try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-config",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Typed and validated environment configuration entry point for NestJS 11 applications, built on Zod v4.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",