@bymax-one/nest-config 1.2.1 → 1.2.3

package/CHANGELOG.md

@@ -11,6 +11,78 @@ as the GitHub Release body, so each released version needs a matching
 
 ## [Unreleased]
 
+## [1.2.3] - 2026-10-31
+
+### Fixed
+
+- **A schema in which two leaves read one variable is rejected.** `a.bC` and `aB.c` both
+  derive `A_B_C`, and `httpServer.port` and `HTTPServer.port` both derive
+  `HTTP_SERVER_PORT`; so does giving two leaves the same `meta({ env })`. Each pair used to
+  read one value silently, so setting the variable satisfied both leaves and neither could
+  tell. `forRoot`, `createValidatedConfig` and the testing helpers now throw a
+  `BymaxConfigValidationError` before the source is read, with one `BYMAX_CONFIG_INVALID`
+  issue per colliding leaf naming the other leaves and the shared variable. There is no
+  opt-out. `resolveSourceNames` still returns every binding. **Apply to a derived
+  backend:** a colliding schema now fails at boot. Give one leaf of each pair a distinct
+  `meta({ env })`, or read one leaf and derive the other value from it in the consumer.
+
+## [1.2.2] - 2026-10-31
+
+### Added
+
+- **`resolveSourceNames` and the `SourceBinding` type are exported from the package root.**
+  `resolveSourceNames(schema)` returns one `{ path, variable }` binding per leaf of a
+  `defineEnv` schema, in declaration order: the environment variable that leaf reads. It is the
+  function validation resolves its variables through, so the list equals what `forRoot` reads,
+  and a test can assert that every variable the schema declares appears in `.env.example`
+  without re-deriving the naming rules. Two distinct paths can derive one variable and both
+  bindings are returned, and declared is not required; the README section lists what the list
+  does not tell you. Both names were already importable from `./internal`, which promises
+  nothing; they are public now. **Apply to a derived backend:** nothing is required; import
+  `resolveSourceNames` from `@bymax-one/nest-config` rather than from `./internal`.
+
+### Fixed
+
+- **A rule on a namespace that names no leaf is reported, not dropped.** A `.check`, `.refine` or
+  `.superRefine` on a namespace whose issue sets no `path` made the validation fail with
+  `environment validation failed (0 issues)` and an empty report. It is reported against the
+  namespace now: the issue's `path` is the namespace key, the variable column shows its prefix
+  followed by `*` (`STORAGE_*`), and the author's message is kept; a rule on the whole schema
+  reports `(schema)`. Such a rule runs once the namespace's own leaves are valid.
+- **`meta({ env })` is found wherever it sits in the chain.** `z.string().meta({ env: 'L' }).default('x')`
+  silently read the derived name, because a wrapper builds a node that carries no metadata.
+  The override is read through them, the outermost usable one wins, and `resolveSourceNames` gives
+  the same answer as validation. **Apply to a derived backend:** a leaf that wrote `meta({ env })`
+  before a wrapper now reads that variable instead of the derived one; check that the variable is
+  set where the derived name was.
+- **An asynchronous `onValidationError` that rejects no longer leaves an unhandled rejection.** The
+  provider awaits the hook, so the boot fails after it finishes, with the original validation error;
+  the hook's error, thrown or rejected, is attached to it as a non-enumerable `cause`. A hook that
+  threw was swallowed with no trace before. The hook's type returns `unknown`, so every existing
+  hook still compiles; a hook that never settles now holds the boot, since there is no timeout.
+- **`createTestConfig` and `configTestingModule` synthesize more leaf types and say what to
+  override.** Leaf types that used to fail validation now get a placeholder or are left to the
+  schema. A leaf no placeholder can satisfy (a regex, a `.refine`)
+  fails with an issue that names it and says to override it, and `configTestingModule` raises
+  that when it is called instead of when the module compiles.
+
+### Documentation
+
+- **The README now states what the code does.** The sample failure report printed messages
+  the validator never produces and was misaligned; it is now the exact output for the inputs
+  it documents. The Tech Stack and mutation-score figures, and the `configTestingModule`
+  example, now match the code, and the library is no longer said to have property-based
+  tests (the value-free guarantee is held by sentinel-secret tests).
+
+- **Where "deep-frozen" stops is stated.** Plain objects and arrays are frozen; a `Date`, `Map`
+  or `Set` leaf is frozen as an object but keeps its mutators.
+
+### Tests
+
+- **A contract spec pins the README to the code.** `src/readme-contract.spec.ts` parses the
+  README and asserts its documented defaults, error catalog, peer table, mutation score and
+  first sample report against the code, so the next drift fails CI.
+
 ## [1.2.1] - 2026-10-30
 
 ### Security
@@ -410,4 +482,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.1.3]: https://github.com/bymaxone/nest-config/compare/v1.1.2...v1.1.3
 [1.2.0]: https://github.com/bymaxone/nest-config/compare/v1.1.3...v1.2.0
 [1.2.1]: https://github.com/bymaxone/nest-config/compare/v1.2.0...v1.2.1
-[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.2.1...HEAD
+[1.2.2]: https://github.com/bymaxone/nest-config/compare/v1.2.1...v1.2.2
+[1.2.3]: https://github.com/bymaxone/nest-config/compare/v1.2.2...v1.2.3
+[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.2.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.62%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.71%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>
@@ -75,8 +75,10 @@ minimal.
 
 ### 🔒 The Validated Object
 
-- ✅ **Immutable by construction** — deep-frozen before it enters the DI container;
-  configuration is a fact about the process, not a mutable bag
+- ✅ **Immutable by construction** — plain objects and arrays are deep-frozen before the
+  object enters the DI container; configuration is a fact about the process, not a mutable
+  bag (a `Date`, `Map` or `Set` leaf is frozen as an object but keeps its own mutators, see
+  [The validated object is frozen](#the-validated-object-is-frozen))
 - ✅ **Typed dot-path access** — `get('database.url')` is `string`, `get('server.port')` is
   `number`, with no casts and no `any` in the chain
 - ✅ **Injectable environment** — the raw source defaults to `process.env` but is a plain
@@ -101,7 +103,7 @@ minimal.
 
 | Subpath      | Contents                                                                                                                                                                   |
 | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.`          | `BymaxConfigModule`, `ConfigService`, `defineEnv`, the DI tokens, `BymaxConfigValidationError` and every option type                                                       |
+| `.`          | `BymaxConfigModule`, `ConfigService`, `defineEnv`, `resolveSourceNames`, the DI tokens, `BymaxConfigValidationError` and every option type                                 |
 | `./testing`  | `configTestingModule`, `createTestConfig` — a validated config for a test without booting the application's own                                                            |
 | `./internal` | The shared runtime both entry points build on. **Not public API**: it is in the `exports` map because it has to resolve at runtime, not because it is meant to be imported |
 
@@ -197,13 +199,16 @@ aggregated report, never one violation at a time:
 ```
 BymaxConfigValidationError: environment validation failed (3 issues)
 
-  DATABASE_URL          missing required value (expected: url)
-  AUTH_JWT_SECRET        too short (expected: string, minimum 32 characters)
-  SERVER_PORT            invalid value (expected: integer between 1 and 65535)
+  DATABASE_URL          missing required value
+  AUTH_JWT_SECRET       too short (expected: string, minimum 32 characters)
+  SERVER_PORT           out of range (expected: number <= 65535)
 
 Fix the variables above and restart the process.
 ```
 
+The report has one line per variable: when a leaf fails several rules, the line shows the first
+one Zod lists, and fixing it can reveal the next on the following start.
+
 In a message this package generates, raw values are never printed — not
 truncated, not masked, absent. That is a hard guarantee, verified by tests. The
 one exception is a message you write yourself, described next.
@@ -237,6 +242,13 @@ that exact string is reserved — a schema that authors it verbatim reports
 custom error map) the default no longer matches, so the localized default is
 reported as written instead.
 
+A rule on a namespace as a whole, such as a `.check` that compares two of its leaves, names no
+leaf unless its issue sets a `path`. Without one it is reported against the namespace: the
+`path` is the namespace key, the variable column shows its prefix followed by `*`
+(`STORAGE_*`), and the message is the one the rule wrote. A rule on the whole schema is reported
+with the variable column `(schema)` and an empty `path`. Zod does not run a namespace's own rule
+once one of that namespace's leaves has failed, so such a rule appears once the leaves are valid.
+
 ## 📖 API Reference
 
 ### `defineEnv(shape)`
@@ -248,6 +260,11 @@ rewriting, cloning, or wrapping them, so coercion and defaults stay explicit
 consumer choices. Leaves use `z.coerce.*` because the source arrives as
 strings (the shape of `process.env`).
 
+Two things follow from that. `z.coerce.boolean()` is `Boolean(value)`: any non-empty string,
+including `'false'`, becomes `true`, so use `z.stringbool()` for a flag. And a variable set to the
+empty string is present, not missing: `z.string()` accepts it and `z.coerce.number()` turns it into
+`0`, so add `.min(1)` or a bound where empty should fail.
+
 A leaf can override its derived variable name through schema metadata when a
 legacy name must be preserved:
 
@@ -258,6 +275,11 @@ database: z.object({
 })
 ```
 
+The override is found wherever `meta` sits in the chain: `z.string().meta({ env: 'LEGACY' }).default('x')`
+and `z.string().default('x').meta({ env: 'LEGACY' })` both read `LEGACY`. When more than one layer sets it, the outermost usable one wins, and an
+empty or non-string value is skipped. `resolveSourceNames` answers the same, because validation
+reads its variables through it.
+
 A namespace can declare itself **open**, which waives strict unknown-key
 detection for the rest of its prefix. Use it when the prefix is shared with
 another program that reads its own variables — see
@@ -272,6 +294,9 @@ otel: z.object({ enabled: z.stringbool().default(false) }).meta({ open: true })
 Only the literal `true` opens a namespace. Any other value, and any metadata
 without the key, leaves detection in force.
 
+Write `.meta({ open: true })` last: methods that build a new object schema, such as `.strict()`,
+`.extend()` or `.pick()`, drop the metadata and close the namespace again.
+
 ### `BymaxConfigModule`
 
 | Method                  | Signature                                                         |
@@ -281,12 +306,12 @@ without the key, leaves detection in force.
 
 `BymaxConfigModuleOptions`:
 
-| Field               | Type                                           | Required | Notes                                                                                                                                                                                                                            |
-| ------------------- | ---------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `schema`            | `EnvSchema`                                    | yes      | Produced by `defineEnv`.                                                                                                                                                                                                         |
-| `source`            | `Record<string, string \| undefined>`          | no       | Defaults to `process.env` in the provider factory. Injectable for tests.                                                                                                                                                         |
-| `onValidationError` | `(issues: ReadonlyArray<ConfigIssue>) => void` | no       | Observability hook invoked before the fail-fast throw. Cannot suppress the failure.                                                                                                                                              |
-| `strict`            | `boolean`                                      | no       | When true, source variables matching a namespace prefix but no declared leaf raise `BYMAX_CONFIG_UNKNOWN_KEY`. Defaults to `false`. Read [Strict mode and shared prefixes](#strict-mode-and-shared-prefixes) before enabling it. |
+| Field               | Type                                              | Required | Notes                                                                                                                                                                                                                            |
+| ------------------- | ------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema`            | `EnvSchema`                                       | yes      | Produced by `defineEnv`.                                                                                                                                                                                                         |
+| `source`            | `Record<string, string \| undefined>`             | no       | Defaults to `process.env` in the provider factory. Injectable for tests.                                                                                                                                                         |
+| `onValidationError` | `(issues: ReadonlyArray<ConfigIssue>) => unknown` | no       | Observability hook invoked before the fail-fast throw; a promise it returns is awaited. Cannot suppress the failure.                                                                                                             |
+| `strict`            | `boolean`                                         | no       | When true, source variables matching a namespace prefix but no declared leaf raise `BYMAX_CONFIG_UNKNOWN_KEY`. Defaults to `false`. Read [Strict mode and shared prefixes](#strict-mode-and-shared-prefixes) before enabling it. |
 
 `forRootAsync` resolves the source through another provider, for example a
 secrets-manager client composed with `process.env`:
@@ -304,6 +329,21 @@ BymaxConfigModule.forRootAsync({
 })
 ```
 
+`forRootAsync` takes Nest's configurable-module options: `useFactory` with
+`inject` and `imports`, shown above; `useClass`, a class whose `create()` returns the options; and
+`useExisting`, which reuses a provider that is already registered (import its module through
+`imports`):
+
+```typescript
+class ConfigOptionsFactory {
+  public create(): { schema: typeof envSchema; source: Record<string, string | undefined> } {
+    return { schema: envSchema, source: { ...process.env } }
+  }
+}
+
+BymaxConfigModule.forRootAsync({ useClass: ConfigOptionsFactory })
+```
+
 `isGlobal` defaults to `true` and can be set to `false` through the standard
 extras when an application intentionally scopes configuration to a submodule.
 
@@ -417,6 +457,10 @@ Because validation completed at bootstrap, `get` never throws for a declared
 path: every leaf either passed validation, received its default, or the
 process did not start.
 
+The class is named `ConfigService`, as the one in `@nestjs/config` is; a backend that imports both
+aliases one of them: `import { ConfigService as BymaxConfigService } from '@bymax-one/nest-config'`.
+`has` is `value !== undefined`, so an absent optional leaf is `false` and a `null` is `true`.
+
 ### `BymaxConfigValidationError` and `ConfigIssue`
 
 ```typescript
@@ -446,6 +490,13 @@ exception is the one described above: a `custom` message written by your own sch
 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.
 
+The hook may be asynchronous: a promise it returns is awaited before the boot fails, so a
+report on its way to a log sink is not cut off by the process exiting. There is no timeout, so
+a hook that never settles holds the boot. If the hook throws or rejects, the boot still fails
+with the original validation error, unchanged in class, `code`, `issues` and `message`, and the
+hook's error is attached to it as `error.cause` (non-enumerable, so `code` and `issues` stay
+the only own enumerable properties).
+
 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
@@ -516,9 +567,10 @@ 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,
-exported for advanced factory-style wiring that needs the raw frozen config
-or the resolved options directly instead of going through `ConfigService`:
+`BYMAX_CONFIG` is a `Symbol` token for the raw frozen config, exported by the module for advanced
+factory-style wiring that does not go through `ConfigService`. `BYMAX_CONFIG_OPTIONS` is the token of
+the module's own options: it is provided inside the module only, so a provider in another module
+cannot inject it, and the options it holds include the raw `source` record. Do not build on it.
 
 ```typescript
 import { Inject, Injectable } from '@nestjs/common'
@@ -536,18 +588,73 @@ export class RawConfigConsumer {
 `EnvSchema`, `EnvShape`, `EnvOutput`, `EnvLeaf`, and `EnvNamespace` type the
 two-level schema shape produced by `defineEnv`; `Path<T>` and `PathValue<T, P>`
 are the template-literal utilities behind `ConfigService.get`'s compile-time
-dot-path inference, limited to the two-level namespace convention. All five
+dot-path inference, limited to the two-level namespace convention. All of them
 are exported for advanced generic code (custom decorators, typed wrappers)
 that needs to reference the schema shape directly.
 
+### `resolveSourceNames(schema)`
+
+Lists the variable every leaf of a schema reads. It is the function validation itself
+resolves its variables through, so the list cannot drift from what `forRoot` reads.
+
+| Parameter | Type                         | Returns                    |
+| --------- | ---------------------------- | -------------------------- |
+| `schema`  | `EnvSchema` from `defineEnv` | `readonly SourceBinding[]` |
+
+`SourceBinding` is `{ path: string; variable: string }`: the leaf's dot path and the
+environment variable it reads. The list has one entry per declared leaf, in declaration
+order. A leaf reads its `meta({ env })` override when that is a non-empty string, and
+otherwise `NAMESPACE_LEAF` in SCREAMING_SNAKE_CASE, with a camelCase key split into words.
+It reads the schema only, never a source record, so it works on a schema exported as a
+value.
+
+```typescript
+// For the Quick Start schema:
+resolveSourceNames(envSchema).map((binding) => binding.variable)
+// ['SERVER_PORT', 'SERVER_ENV', 'DATABASE_URL', 'REDIS_URL', 'LOG_LEVEL']
+```
+
+A test that keeps `.env.example` honest is the usual use:
+
+```typescript
+import { readFileSync } from 'node:fs'
+import { resolveSourceNames } from '@bymax-one/nest-config'
+import { envSchema } from './config/env.schema'
+
+it('documents every variable the schema reads in .env.example', () => {
+  const example = readFileSync('.env.example', 'utf8')
+  const documented = new Set(
+    example.split('\n').map((line) => /^#?\s*([A-Z][A-Z0-9_]*)=/.exec(line)?.[1])
+  )
+  const missing = resolveSourceNames(envSchema).filter(({ variable }) => !documented.has(variable))
+  expect(missing).toEqual([])
+})
+```
+
+#### What it does not tell you
+
+- **Declared is not required.** A leaf with a default, or an optional leaf, is listed like
+  any other. Whether it belongs in a template file is your policy; the list says only that
+  the schema reads it.
+- **Two paths can read one variable.** Names are derived from the keys, so `a.bC` and
+  `aB.c` both derive `A_B_C`, and `httpServer.port` and `HTTPServer.port` both derive
+  `HTTP_SERVER_PORT`. Every binding is returned and none is dropped, so a tool can see the
+  collision; validation rejects such a schema (see the error catalog). Giving two leaves
+  the same `meta({ env })` is the same collision, and there is no opt-out.
+- **An open namespace changes nothing.** `meta({ open: true })` only waives strict
+  unknown-key detection, so the list is the same whether a namespace is open or closed. It
+  does not help to find variables in `.env.example` that no leaf reads.
+- **Two-level schemas only.** Deeper nesting is outside this contract, as it
+  is for `Path` and `PathValue`.
+
 ## 🚨 Error Catalog
 
-| Code                       | Meaning                                                |
-| -------------------------- | ------------------------------------------------------ |
-| `BYMAX_CONFIG_VALIDATION`  | One or more schema violations (top-level error code).  |
-| `BYMAX_CONFIG_MISSING`     | Required variable absent from the source (issue code). |
-| `BYMAX_CONFIG_INVALID`     | Present but failed its constraint (issue code).        |
-| `BYMAX_CONFIG_UNKNOWN_KEY` | Strict mode: source variable matches no declared leaf. |
+| Code                       | Meaning                                                   |
+| -------------------------- | --------------------------------------------------------- |
+| `BYMAX_CONFIG_VALIDATION`  | One or more schema violations (top-level error code).     |
+| `BYMAX_CONFIG_MISSING`     | Required variable absent from the source (issue code).    |
+| `BYMAX_CONFIG_INVALID`     | Failed its constraint, or shares a variable (issue code). |
+| `BYMAX_CONFIG_UNKNOWN_KEY` | Strict mode: source variable matches no declared leaf.    |
 
 ## 🏗️ Architecture
 
@@ -621,7 +728,7 @@ guaranteed to be printed, logged, and pasted into an issue. That shapes the whol
 Every message this library generates states the _expected_ constraint — the type, the
 allowed enum options taken from the schema, the bound — and never the received value.
 `env-validator` and `report-formatter` each say so in their own contracts, and
-property-based tests hold them to it. The messages you write yourself are the exception,
+sentinel-secret tests hold them to it. The messages you write yourself are the exception,
 covered below.
 
 ### The service does not serialize its configuration
@@ -643,8 +750,16 @@ does not serve one request.
 
 ### The validated object is frozen
 
-It is deep-frozen before it enters the container, so nothing in the running process
-rewrites configuration under a component that already read it.
+Plain objects and arrays are deep-frozen before the object enters the container, so nothing
+in the running process rewrites those values under a component that already read them.
+
+A `Date`, a `Map` or a `Set` leaf is frozen as an object but is **not** made immutable:
+`setTime`, `Map.prototype.set` and `Set.prototype.add` still work, because the state they
+change lives in internal slots that `Object.freeze` cannot reach, and the entries of a `Map` or
+`Set` are not visited. Wrapping them in a read-only proxy was measured and rejected: it fails
+`util.types.isDate`, reports `[object Object]` to `Object.prototype.toString`, cannot be given to
+`structuredClone`, and does not satisfy `assert.deepStrictEqual` against a real `Date`. Prefer a
+string or number leaf, or a `.transform` to a plain value, where immutability matters.
 
 ### Nothing is read from anywhere but the source you name
 
@@ -669,7 +784,7 @@ report.
 | Error messages | Expected constraint only — type, schema-declared enum options, bounds; never the received value. A `custom` message from your own schema is the exception: it prints as written |
 | Failure mode   | Refuse to start; the whole schema is validated before the context finishes building                                                                                             |
 | Aggregation    | Every failure reported at once, so a fix cycle is one restart rather than one per variable                                                                                      |
-| Immutability   | The validated result is frozen before it is provided                                                                                                                            |
+| Immutability   | Plain objects and arrays in the validated result are frozen before it is provided; a `Date`, `Map` or `Set` keeps its mutators                                                  |
 | Service state  | The root lives in a private field; serializing the injected service yields namespace names only                                                                                 |
 | Sources        | `process.env` only — no file, no network, no remote provider                                                                                                                    |
 | Type surface   | Dot paths checked against the schema at compile time; a typo is a build error, not a runtime `undefined`                                                                        |
@@ -686,11 +801,11 @@ report.
 
 - **Runtime:** Node.js 24+
 - **Framework:** NestJS 11 (`ConfigurableModuleBuilder`, `@Global()`, `Symbol()` tokens)
-- **Validation:** Zod `^4` (peer) — the schema language, the coercion and the error source
+- **Validation:** Zod `^4.6.6` (peer) — the schema language, the coercion and the error source
 - **Build:** tsup — ESM + CJS per subpath, with `.d.ts` _and_ `.d.cts` declarations,
   and one shared `./internal` bundle so the module and its testing entry point hold
   a single class identity
-- **Tests:** Jest, including property-based tests over the report formatter + Stryker (mutation)
+- **Tests:** Jest, including sentinel-secret tests over the validator and the report formatter, + Stryker (mutation)
 - **TypeScript:** 5.x strict (`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`), zero `any`
 
 ---
@@ -701,7 +816,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.61% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
+- ✅ **99.71% 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))
@@ -736,6 +851,30 @@ values elsewhere), applies selective overrides, then runs the exact
 production pipeline (validate, freeze), so a test exercises the same code
 path a running application does.
 
+```typescript
+// Leaves createTestConfig fills without an override:
+defineEnv({
+  text: z.object({ a: z.string().min(8), b: z.email(), c: z.url(), d: z.uuid() }),
+  time: z.object({
+    at: z.iso.datetime(),
+    on: z.iso.date(),
+    clock: z.iso.time(),
+    when: z.coerce.date()
+  }),
+  scalar: z.object({
+    n: z.coerce.number().int().min(1),
+    flag: z.stringbool(),
+    kind: z.enum(['a', 'b']),
+    fixed: z.literal('x')
+  })
+})
+```
+
+A leaf no placeholder can be known to satisfy, such as a
+`z.string().regex(...)` or a `.refine(...)` rule, makes the helper throw a
+`BymaxConfigValidationError` whose issue says `no placeholder satisfies this leaf` and names it
+(`pass an override for region.code`); give that leaf an override and the helper builds.
+
 ```typescript
 import { createTestConfig } from '@bymax-one/nest-config/testing'
 import { envSchema } from './config/env.schema'
@@ -755,11 +894,18 @@ import { envSchema } from './config/env.schema'
 import { FeatureProvider } from './feature.provider'
 
 const moduleRef = await Test.createTestingModule({
-  imports: [configTestingModule(envSchema, { server: { port: 0 } })],
+  imports: [configTestingModule(envSchema, { server: { port: 8080 } })],
   providers: [FeatureProvider]
 }).compile()
 ```
 
+Overrides mirror the `namespace.leaf` shape with every key optional and typed from the schema. Each value is converted with `String(value)` before validation, so give
+a leaf what its environment variable would hold; an object becomes `'[object Object]'`, and an override
+of `undefined` is ignored, so a defaulted leaf cannot be unset. Neither helper takes `strict`, a
+custom `source`, a hook or `isGlobal`: `configTestingModule` registers the module globally, and a
+failure case (a missing variable, a strict violation) is built with
+`BymaxConfigModule.forRoot({ schema, source, strict: true })` and a source you write.
+
 Placeholder synthesis never fabricates values that could accidentally pass a
 secret-strength constraint; length and format constraints are honored. The
 subpath has no Jest dependency and works with any runner, though the family

package/dist/index.cjs

@@ -32,3 +32,7 @@ Object.defineProperty(exports, "defineEnv", {
   enumerable: true,
   get: function () { return internal.defineEnv; }
 });
+Object.defineProperty(exports, "resolveSourceNames", {
+  enumerable: true,
+  get: function () { return internal.resolveSourceNames; }
+});

package/dist/index.d.cts

@@ -1 +1 @@
-export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, ConfigIssue, ConfigIssueCode, ConfigService, ConfigValidationCode, EnvLeaf, EnvNamespace, EnvOutput, EnvSchema, EnvShape, Path, PathValue, defineEnv } from '@bymax-one/nest-config/internal';
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, ConfigIssue, ConfigIssueCode, ConfigService, ConfigValidationCode, EnvLeaf, EnvNamespace, EnvOutput, EnvSchema, EnvShape, Path, PathValue, SourceBinding, defineEnv, resolveSourceNames } from '@bymax-one/nest-config/internal';

package/dist/index.d.ts

@@ -1 +1 @@
-export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, ConfigIssue, ConfigIssueCode, ConfigService, ConfigValidationCode, EnvLeaf, EnvNamespace, EnvOutput, EnvSchema, EnvShape, Path, PathValue, defineEnv } from '@bymax-one/nest-config/internal';
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, ConfigIssue, ConfigIssueCode, ConfigService, ConfigValidationCode, EnvLeaf, EnvNamespace, EnvOutput, EnvSchema, EnvShape, Path, PathValue, SourceBinding, defineEnv, resolveSourceNames } from '@bymax-one/nest-config/internal';

package/dist/index.mjs

@@ -1 +1 @@
-export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigValidationError, ConfigErrorCode, ConfigService, defineEnv } from '@bymax-one/nest-config/internal';
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigValidationError, ConfigErrorCode, ConfigService, defineEnv, resolveSourceNames } from '@bymax-one/nest-config/internal';

package/dist/internal/index.cjs

@@ -122,8 +122,12 @@ function toScreamingSnake(segment) {
   return segment.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").toUpperCase();
 }
 function readEnvOverride(leaf) {
-  const override = leaf.meta()?.env;
-  return typeof override === "string" && override.length > 0 ? override : void 0;
+  for (let node = leaf; node !== void 0; ) {
+    const override = node.meta()?.env;
+    if (typeof override === "string" && override.length > 0) return override;
+    node = node._zod.def.innerType ?? node._zod.def.in;
+  }
+  return void 0;
 }
 function readOpenFlag(namespace) {
   return namespace.meta()?.open === true;
@@ -210,13 +214,28 @@ function toConfigIssue(binding, issue, source) {
     message: authored ?? (isMissing ? MISSING_MESSAGE : describeConstraint(issue))
   };
 }
-function translateIssues(zodIssues, bindings, source) {
+function toNamespaceIssue(path, variable, issue) {
+  return {
+    path,
+    variable,
+    code: ConfigErrorCode.INVALID,
+    message: authoredMessage(issue) ?? describeConstraint(issue)
+  };
+}
+function translateIssues(zodIssues, bindings, prefixes, source) {
+  const leafPaths = new Set(bindings.map((binding) => binding.path));
+  const namespaces = new Set(prefixes.map((entry) => entry.namespace));
   const issueByPath = /* @__PURE__ */ new Map();
+  const issueByNamespace = /* @__PURE__ */ new Map();
   for (const issue of zodIssues) {
     const path = issue.path.slice(0, 2).join(".");
-    if (!issueByPath.has(path)) {
-      issueByPath.set(path, issue);
+    if (leafPaths.has(path)) {
+      if (!issueByPath.has(path)) issueByPath.set(path, issue);
+      continue;
     }
+    const namespace = issue.path.length > 0 && namespaces.has(String(issue.path[0]));
+    const key = namespace ? String(issue.path[0]) : "";
+    if (!issueByNamespace.has(key)) issueByNamespace.set(key, issue);
   }
   const result = [];
   for (const binding of bindings) {
@@ -224,6 +243,13 @@ function translateIssues(zodIssues, bindings, source) {
     if (issue === void 0) continue;
     result.push(toConfigIssue(binding, issue, source));
   }
+  for (const entry of prefixes) {
+    const issue = issueByNamespace.get(entry.namespace);
+    if (issue === void 0) continue;
+    result.push(toNamespaceIssue(entry.namespace, `${entry.prefix}*`, issue));
+  }
+  const wholeSchema = issueByNamespace.get("");
+  if (wholeSchema !== void 0) result.push(toNamespaceIssue("", "(schema)", wholeSchema));
   return result;
 }
 function longestMatchingPrefix(prefixes, key) {
@@ -256,43 +282,74 @@ function detectUnknownKeys(prefixes, bindings, source) {
     (left, right) => Number(left.variable > right.variable) - Number(left.variable < right.variable)
   );
 }
+function assertDistinctVariables(bindings) {
+  const byVariable = /* @__PURE__ */ new Map();
+  for (const { path, variable } of bindings) {
+    byVariable.set(variable, [...byVariable.get(variable) ?? [], path]);
+  }
+  const issues = [];
+  for (const [variable, paths] of byVariable) {
+    if (paths.length < 2) continue;
+    for (const path of paths) {
+      const others = paths.filter((other) => other !== path).join(", ");
+      issues.push({
+        path,
+        variable,
+        code: ConfigErrorCode.INVALID,
+        message: `shares this variable with ${others}; rename one with meta({ env })`
+      });
+    }
+  }
+  if (issues.length > 0) throw new BymaxConfigValidationError(issues);
+}
 function validateEnv(schema, source, options) {
   const bindings = resolveSourceNames(schema);
+  assertDistinctVariables(bindings);
   const sourceMap = new Map(Object.entries(source));
   const namespaces = Object.keys(schema.shape);
   const candidate = buildCandidate(namespaces, collectPresentLeaves(bindings, sourceMap));
   const result = schema.safeParse(candidate);
-  const unknown = options?.strict === true ? detectUnknownKeys(resolveNamespacePrefixes(schema), bindings, sourceMap) : [];
+  const prefixes = resolveNamespacePrefixes(schema);
+  const unknown = options?.strict === true ? detectUnknownKeys(prefixes, bindings, sourceMap) : [];
   if (result.success) {
     if (unknown.length === 0) return result.data;
     throw new BymaxConfigValidationError(unknown);
   }
-  const issues = translateIssues(result.error.issues, bindings, sourceMap);
+  const issues = translateIssues(result.error.issues, bindings, prefixes, sourceMap);
   throw new BymaxConfigValidationError([...issues, ...unknown]);
 }
 
 // src/config.providers.ts
-function reportIssues(hook, issues) {
+async function reportIssues(hook, error) {
   if (hook === void 0) return;
   try {
-    hook(issues);
-  } catch {
+    await hook(error.issues);
+  } catch (hookError) {
+    Object.defineProperty(error, "cause", {
+      value: hookError,
+      enumerable: false,
+      writable: false,
+      configurable: false
+    });
   }
 }
 function createValidatedConfig(options) {
   const source = options.source ?? process.env;
+  return deepFreeze(validateEnv(options.schema, source, { strict: options.strict === true }));
+}
+async function provideValidatedConfig(options) {
   try {
-    return deepFreeze(validateEnv(options.schema, source, { strict: options.strict === true }));
+    return createValidatedConfig(options);
   } catch (error) {
     if (error instanceof BymaxConfigValidationError) {
-      reportIssues(options.onValidationError, error.issues);
+      await reportIssues(options.onValidationError, error);
     }
     throw error;
   }
 }
 var bymaxConfigProvider = {
   provide: BYMAX_CONFIG,
-  useFactory: createValidatedConfig,
+  useFactory: provideValidatedConfig,
   inject: [BYMAX_CONFIG_OPTIONS]
 };
 var _config, _leaves;
@@ -480,6 +537,7 @@ exports.BYMAX_CONFIG = BYMAX_CONFIG;
 exports.BYMAX_CONFIG_OPTIONS = BYMAX_CONFIG_OPTIONS;
 exports.BymaxConfigValidationError = BymaxConfigValidationError;
 exports.ConfigErrorCode = ConfigErrorCode;
+exports.assertDistinctVariables = assertDistinctVariables;
 exports.createValidatedConfig = createValidatedConfig;
 exports.defineEnv = defineEnv;
 exports.resolveSourceNames = resolveSourceNames;