@bymax-one/nest-config 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -11,6 +11,63 @@ as the GitHub Release body, so each released version needs a matching
 
 ## [Unreleased]
 
+## [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 +467,5 @@ 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
+[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.2.2...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.69%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,10 +588,64 @@ 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; validation reads the
+  shared variable for both leaves.
+- **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                                                |
@@ -621,7 +727,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 +749,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 +783,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 +800,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 +815,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.69% 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 +850,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 +893,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) {
@@ -262,37 +288,47 @@ function validateEnv(schema, source, options) {
   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;

package/dist/internal/index.d.cts

@@ -230,13 +230,16 @@ interface BymaxConfigModuleOptions<TSchema extends EnvSchema = EnvSchema> {
     readonly source?: Record<string, string | undefined>;
     /**
      * Observability hook invoked once with the structured issue list immediately
-     * before the validation error is thrown. The issues are value-free on the
-     * terms stated by {@link ConfigIssue}: generated descriptions never carry a
-     * received value, while a schema author's own `custom` message is passed
-     * through as written. It is observability only and cannot suppress the
-     * failure: the error still propagates even when the hook itself throws.
+     * before the validation error is thrown. Its return value is ignored unless it is a
+     * promise, which the module waits for before the boot fails; there is no timeout, so a
+     * hook that never settles holds the boot. The issues are value-free on the terms stated by
+     * {@link ConfigIssue}: generated descriptions never carry a received value, while a
+     * schema author's own `custom` message is passed through as written. It is
+     * observability only and cannot suppress the failure: the validation error still
+     * propagates when the hook throws or rejects, and the hook's error is attached to it
+     * as its non-enumerable `cause`.
      */
-    readonly onValidationError?: (issues: ReadonlyArray<ConfigIssue>) => void;
+    readonly onValidationError?: (issues: ReadonlyArray<ConfigIssue>) => unknown;
     /**
      * When true, source variables that match a declared namespace prefix but no
      * declared leaf produce `BYMAX_CONFIG_UNKNOWN_KEY` issues. Defaults to false.
@@ -534,24 +537,24 @@ declare function defineEnv<TShape extends EnvShape>(shape: TShape): EnvSchema<TS
  * @fileoverview The BYMAX_CONFIG provider factory: the fail-fast heart of the
  * module. It resolves the source (defaulting to `process.env`, using a custom
  * source verbatim), runs the single-pass validator, and on success returns the
- * deep-frozen typed config. On failure it invokes the observability hook
- * exactly once before rethrowing the aggregated error; the hook is
+ * deep-frozen typed config. On failure the factory runs the observability hook
+ * and waits for it, then rethrows the aggregated error; the hook is
  * observability only and can never suppress or replace the failure, so a
  * misconfigured process is stopped before any consumer provider is constructed.
+ * A failing hook is recorded as the `cause` of that same error.
  * @layer Provider
  */
 
 /**
- * Validate the source against the schema, freeze the result, or fail fast.
+ * Validate the source against the schema, freeze the result, or throw.
  *
  * Resolves the source to the supplied record or `process.env`, runs exactly one
- * validation pass, and returns the deep-frozen typed output. On a validation
- * failure the hook runs once with the issues and the aggregated error is
- * rethrown unchanged, aborting module resolution before any consumer provider
- * is instantiated.
+ * validation pass, and returns the deep-frozen typed output. A validation failure is
+ * thrown as the aggregated error; the observability hook belongs to the provider factory,
+ * which can wait for it, and this synchronous function never calls it.
  *
  * @typeParam TShape - The two-level schema shape.
- * @param options - The resolved module options (schema, source, hook, strict).
+ * @param options - The resolved module options (schema, source, strict).
  * @returns The validated, deep-frozen configuration output.
  * @throws {BymaxConfigValidationError} When the source fails the schema.
  * @example
@@ -560,7 +563,7 @@ declare function defineEnv<TShape extends EnvShape>(shape: TShape): EnvSchema<TS
  * config.server.port; // typed, validated, frozen
  * ```
  */
-declare function createValidatedConfig<TShape extends EnvShape>(options: Omit<BymaxConfigModuleOptions, 'schema'> & {
+declare function createValidatedConfig<TShape extends EnvShape>(options: Omit<BymaxConfigModuleOptions, 'schema' | 'onValidationError'> & {
     readonly schema: EnvSchema<TShape>;
 }): Readonly<EnvOutput<TShape>>;
 
@@ -571,13 +574,15 @@ declare function createValidatedConfig<TShape extends EnvShape>(options: Omit<By
  * unless the leaf declares a `meta({ env })` override, which wins. It also
  * resolves the shared prefix of each namespace and whether that namespace
  * declared `meta({ open: true })`, the two facts strict unknown-key detection
- * runs on. This is an internal module consumed by the validator; it is not part
- * of the public API.
+ * runs on. The validator and the package root share this one module:
+ * `resolveSourceNames` and `SourceBinding` are exported from the package root,
+ * while the namespace-prefix helpers stay internal.
  * @layer Utility
  */
 
 /**
  * The resolved binding between one config leaf and its source variable name.
+ * Part of the public API, as the element type of `resolveSourceNames`.
  */
 interface SourceBinding {
     /** Nested config path, e.g. `database.url`. */
@@ -594,6 +599,14 @@ interface SourceBinding {
  * is total: every declared leaf maps to exactly one variable, in declaration
  * order.
  *
+ * This is the list the validator reads, not a copy of its rules: validation
+ * resolves its bindings through this same function. It reads the schema only,
+ * never a source record. Declared is not required: a leaf with a default or an
+ * optional leaf is listed like any other. Two distinct paths can resolve to one
+ * variable (`a.bC` and `aB.c` both derive `A_B_C`); both bindings are returned
+ * and none is dropped. An open namespace changes nothing here, since opening
+ * only waives strict unknown-key detection.
+ *
  * @typeParam TShape - The two-level shape the schema was composed from.
  * @param schema - A schema produced by `defineEnv`.
  * @returns The ordered list of leaf-to-variable bindings, typed `readonly`.

package/dist/internal/index.d.ts

@@ -230,13 +230,16 @@ interface BymaxConfigModuleOptions<TSchema extends EnvSchema = EnvSchema> {
     readonly source?: Record<string, string | undefined>;
     /**
      * Observability hook invoked once with the structured issue list immediately
-     * before the validation error is thrown. The issues are value-free on the
-     * terms stated by {@link ConfigIssue}: generated descriptions never carry a
-     * received value, while a schema author's own `custom` message is passed
-     * through as written. It is observability only and cannot suppress the
-     * failure: the error still propagates even when the hook itself throws.
+     * before the validation error is thrown. Its return value is ignored unless it is a
+     * promise, which the module waits for before the boot fails; there is no timeout, so a
+     * hook that never settles holds the boot. The issues are value-free on the terms stated by
+     * {@link ConfigIssue}: generated descriptions never carry a received value, while a
+     * schema author's own `custom` message is passed through as written. It is
+     * observability only and cannot suppress the failure: the validation error still
+     * propagates when the hook throws or rejects, and the hook's error is attached to it
+     * as its non-enumerable `cause`.
      */
-    readonly onValidationError?: (issues: ReadonlyArray<ConfigIssue>) => void;
+    readonly onValidationError?: (issues: ReadonlyArray<ConfigIssue>) => unknown;
     /**
      * When true, source variables that match a declared namespace prefix but no
      * declared leaf produce `BYMAX_CONFIG_UNKNOWN_KEY` issues. Defaults to false.
@@ -534,24 +537,24 @@ declare function defineEnv<TShape extends EnvShape>(shape: TShape): EnvSchema<TS
  * @fileoverview The BYMAX_CONFIG provider factory: the fail-fast heart of the
  * module. It resolves the source (defaulting to `process.env`, using a custom
  * source verbatim), runs the single-pass validator, and on success returns the
- * deep-frozen typed config. On failure it invokes the observability hook
- * exactly once before rethrowing the aggregated error; the hook is
+ * deep-frozen typed config. On failure the factory runs the observability hook
+ * and waits for it, then rethrows the aggregated error; the hook is
  * observability only and can never suppress or replace the failure, so a
  * misconfigured process is stopped before any consumer provider is constructed.
+ * A failing hook is recorded as the `cause` of that same error.
  * @layer Provider
  */
 
 /**
- * Validate the source against the schema, freeze the result, or fail fast.
+ * Validate the source against the schema, freeze the result, or throw.
  *
  * Resolves the source to the supplied record or `process.env`, runs exactly one
- * validation pass, and returns the deep-frozen typed output. On a validation
- * failure the hook runs once with the issues and the aggregated error is
- * rethrown unchanged, aborting module resolution before any consumer provider
- * is instantiated.
+ * validation pass, and returns the deep-frozen typed output. A validation failure is
+ * thrown as the aggregated error; the observability hook belongs to the provider factory,
+ * which can wait for it, and this synchronous function never calls it.
  *
  * @typeParam TShape - The two-level schema shape.
- * @param options - The resolved module options (schema, source, hook, strict).
+ * @param options - The resolved module options (schema, source, strict).
  * @returns The validated, deep-frozen configuration output.
  * @throws {BymaxConfigValidationError} When the source fails the schema.
  * @example
@@ -560,7 +563,7 @@ declare function defineEnv<TShape extends EnvShape>(shape: TShape): EnvSchema<TS
  * config.server.port; // typed, validated, frozen
  * ```
  */
-declare function createValidatedConfig<TShape extends EnvShape>(options: Omit<BymaxConfigModuleOptions, 'schema'> & {
+declare function createValidatedConfig<TShape extends EnvShape>(options: Omit<BymaxConfigModuleOptions, 'schema' | 'onValidationError'> & {
     readonly schema: EnvSchema<TShape>;
 }): Readonly<EnvOutput<TShape>>;
 
@@ -571,13 +574,15 @@ declare function createValidatedConfig<TShape extends EnvShape>(options: Omit<By
  * unless the leaf declares a `meta({ env })` override, which wins. It also
  * resolves the shared prefix of each namespace and whether that namespace
  * declared `meta({ open: true })`, the two facts strict unknown-key detection
- * runs on. This is an internal module consumed by the validator; it is not part
- * of the public API.
+ * runs on. The validator and the package root share this one module:
+ * `resolveSourceNames` and `SourceBinding` are exported from the package root,
+ * while the namespace-prefix helpers stay internal.
  * @layer Utility
  */
 
 /**
  * The resolved binding between one config leaf and its source variable name.
+ * Part of the public API, as the element type of `resolveSourceNames`.
  */
 interface SourceBinding {
     /** Nested config path, e.g. `database.url`. */
@@ -594,6 +599,14 @@ interface SourceBinding {
  * is total: every declared leaf maps to exactly one variable, in declaration
  * order.
  *
+ * This is the list the validator reads, not a copy of its rules: validation
+ * resolves its bindings through this same function. It reads the schema only,
+ * never a source record. Declared is not required: a leaf with a default or an
+ * optional leaf is listed like any other. Two distinct paths can resolve to one
+ * variable (`a.bC` and `aB.c` both derive `A_B_C`); both bindings are returned
+ * and none is dropped. An open namespace changes nothing here, since opening
+ * only waives strict unknown-key detection.
+ *
  * @typeParam TShape - The two-level shape the schema was composed from.
  * @param schema - A schema produced by `defineEnv`.
  * @returns The ordered list of leaf-to-variable bindings, typed `readonly`.

package/dist/internal/index.mjs

@@ -120,8 +120,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;
@@ -208,13 +212,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) {
@@ -222,6 +241,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) {
@@ -260,37 +286,47 @@ function validateEnv(schema, source, options) {
   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;

package/dist/testing/index.cjs

@@ -9,6 +9,10 @@ var PLACEHOLDER_EMAIL_DOMAIN = "@placeholder.local";
 var DEFAULT_NUMBER = 1;
 var DEFAULT_STRING_LENGTH = 1;
 var PLACEHOLDER_BOOLEAN = "true";
+var PLACEHOLDER_UUID = "00000000-0000-4000-8000-000000000000";
+var PLACEHOLDER_DATETIME = "2000-01-01T00:00:00.000Z";
+var PLACEHOLDER_DATE = "2000-01-01";
+var PLACEHOLDER_TIME = "00:00:00";
 function readDef(leaf) {
   return leaf._zod.def;
 }
@@ -59,11 +63,23 @@ function synthesizePlainString(lengths) {
   const bounded = target > lengths.max ? lengths.max : target;
   return FILLER_CHARACTER.repeat(bounded);
 }
+function formatOf(def) {
+  const declared = checksOf(def).map((wrapper) => wrapper._zod.def).find((check) => check.check === "string_format");
+  return def.format ?? declared?.format;
+}
+var FIXED_FORMATS = /* @__PURE__ */ new Map([
+  ["uuid", PLACEHOLDER_UUID],
+  ["datetime", PLACEHOLDER_DATETIME],
+  ["date", PLACEHOLDER_DATE],
+  ["time", PLACEHOLDER_TIME]
+]);
 function synthesizeString(def) {
   const lengths = readStringLengths(def);
-  if (def.format === "url") return synthesizeUrl(lengths);
-  if (def.format === "email") return synthesizeEmail(lengths);
-  return synthesizePlainString(lengths);
+  const format = formatOf(def);
+  if (format === "url") return synthesizeUrl(lengths);
+  if (format === "email") return synthesizeEmail(lengths);
+  const fixed = format === void 0 ? void 0 : FIXED_FORMATS.get(format);
+  return fixed ?? synthesizePlainString(lengths);
 }
 function selectNumber(bounds) {
   const { lower, upper, integer } = bounds;
@@ -99,20 +115,35 @@ function synthesizeEnum(def) {
   const [first] = Object.values(def.entries);
   return String(first);
 }
+function withoutOptional(leaf) {
+  const def = readDef(leaf);
+  return def.type === "optional" ? withoutOptional(def.innerType) : leaf;
+}
 function synthesizeLeaf(leaf) {
   const def = readDef(leaf);
   switch (def.type) {
     case "default":
+    case "prefault":
+    case "catch":
     case "optional":
       return void 0;
     case "nullable":
+    case "readonly":
       return synthesizeLeaf(def.innerType);
+    case "nonoptional":
+      return synthesizeLeaf(withoutOptional(def.innerType));
+    case "pipe":
+      return readDef(def.out).type === "boolean" && readDef(def.in).type === "string" ? PLACEHOLDER_BOOLEAN : synthesizeLeaf(def.in);
     case "string":
       return synthesizeString(def);
     case "number":
       return synthesizeNumber(def);
     case "boolean":
       return PLACEHOLDER_BOOLEAN;
+    case "date":
+      return PLACEHOLDER_DATETIME;
+    case "literal":
+      return String(def.values[0]);
     case "enum":
       return synthesizeEnum(def);
     default:
@@ -145,25 +176,43 @@ function flattenOverrides(overrides) {
   }
   return flat;
 }
-function applyOverrides(schema, base, overrides) {
+function applyOverrides(schema, base, overrides, overridden) {
   const flat = flattenOverrides(overrides ?? {});
   const entries = new Map(Object.entries(base));
   for (const binding of internal.resolveSourceNames(schema)) {
     const value = flat.get(binding.path);
-    if (value !== void 0) entries.set(binding.variable, String(value));
+    if (value === void 0) continue;
+    entries.set(binding.variable, String(value));
+    overridden.add(binding.variable);
   }
   const source = /* @__PURE__ */ Object.create(null);
   for (const [variable, value] of entries) source[variable] = value;
   return source;
 }
-function buildTestSource(schema, overrides) {
-  return applyOverrides(schema, synthesizePlaceholderSource(schema), overrides);
+function explainUnsatisfiedLeaves(error, overridden) {
+  return new internal.BymaxConfigValidationError(
+    error.issues.map(
+      (issue) => !issue.path.includes(".") || overridden.has(issue.variable) ? issue : {
+        ...issue,
+        message: `no placeholder satisfies this leaf (${issue.message}); pass an override for ${issue.path}`
+      }
+    )
+  );
+}
+function prepareTestConfig(schema, overrides) {
+  const overridden = /* @__PURE__ */ new Set();
+  const source = applyOverrides(schema, synthesizePlaceholderSource(schema), overrides, overridden);
+  try {
+    return { source, config: internal.createValidatedConfig({ schema, source }) };
+  } catch (error) {
+    throw error instanceof internal.BymaxConfigValidationError ? explainUnsatisfiedLeaves(error, overridden) : error;
+  }
 }
 function createTestConfig(schema, overrides) {
-  return internal.createValidatedConfig({ schema, source: buildTestSource(schema, overrides) });
+  return prepareTestConfig(schema, overrides).config;
 }
 function configTestingModule(schema, overrides) {
-  const source = buildTestSource(schema, overrides);
+  const { source } = prepareTestConfig(schema, overrides);
   return internal.BymaxConfigModule.forRoot({ schema, source });
 }
 

package/dist/testing/index.d.cts

@@ -40,7 +40,8 @@ type ConfigOverrides<TShape extends EnvShape> = {
  * @param schema - A schema produced by `defineEnv`.
  * @param overrides - Optional selective nested partial overrides.
  * @returns The validated, deep-frozen configuration typed by the schema.
- * @throws {BymaxConfigValidationError} When an override violates a constraint.
+ * @throws {BymaxConfigValidationError} When an override violates a constraint, or when no
+ * placeholder satisfies a leaf: that issue says so and names the leaf to override.
  * @example
  * ```typescript
  * const config = createTestConfig(envSchema, {
@@ -75,6 +76,8 @@ declare function createTestConfig<TShape extends EnvShape>(schema: EnvSchema<TSh
  * @param schema - A schema produced by `defineEnv`.
  * @param overrides - Optional selective nested partial overrides.
  * @returns A dynamic module registered through the production `forRoot` path.
+ * @throws {BymaxConfigValidationError} When an override violates a constraint, or when no
+ * placeholder satisfies a leaf; the module is not built, and the issue names the leaf to override.
  * @example
  * ```typescript
  * const moduleRef = await Test.createTestingModule({

package/dist/testing/index.d.ts

@@ -40,7 +40,8 @@ type ConfigOverrides<TShape extends EnvShape> = {
  * @param schema - A schema produced by `defineEnv`.
  * @param overrides - Optional selective nested partial overrides.
  * @returns The validated, deep-frozen configuration typed by the schema.
- * @throws {BymaxConfigValidationError} When an override violates a constraint.
+ * @throws {BymaxConfigValidationError} When an override violates a constraint, or when no
+ * placeholder satisfies a leaf: that issue says so and names the leaf to override.
  * @example
  * ```typescript
  * const config = createTestConfig(envSchema, {
@@ -75,6 +76,8 @@ declare function createTestConfig<TShape extends EnvShape>(schema: EnvSchema<TSh
  * @param schema - A schema produced by `defineEnv`.
  * @param overrides - Optional selective nested partial overrides.
  * @returns A dynamic module registered through the production `forRoot` path.
+ * @throws {BymaxConfigValidationError} When an override violates a constraint, or when no
+ * placeholder satisfies a leaf; the module is not built, and the issue names the leaf to override.
  * @example
  * ```typescript
  * const moduleRef = await Test.createTestingModule({

package/dist/testing/index.mjs

@@ -1,4 +1,4 @@
-import { createValidatedConfig, BymaxConfigModule, resolveSourceNames } from '@bymax-one/nest-config/internal';
+import { BymaxConfigModule, createValidatedConfig, BymaxConfigValidationError, resolveSourceNames } from '@bymax-one/nest-config/internal';
 
 // src/testing/create-test-config.ts
 var FILLER_CHARACTER = "a";
@@ -7,6 +7,10 @@ var PLACEHOLDER_EMAIL_DOMAIN = "@placeholder.local";
 var DEFAULT_NUMBER = 1;
 var DEFAULT_STRING_LENGTH = 1;
 var PLACEHOLDER_BOOLEAN = "true";
+var PLACEHOLDER_UUID = "00000000-0000-4000-8000-000000000000";
+var PLACEHOLDER_DATETIME = "2000-01-01T00:00:00.000Z";
+var PLACEHOLDER_DATE = "2000-01-01";
+var PLACEHOLDER_TIME = "00:00:00";
 function readDef(leaf) {
   return leaf._zod.def;
 }
@@ -57,11 +61,23 @@ function synthesizePlainString(lengths) {
   const bounded = target > lengths.max ? lengths.max : target;
   return FILLER_CHARACTER.repeat(bounded);
 }
+function formatOf(def) {
+  const declared = checksOf(def).map((wrapper) => wrapper._zod.def).find((check) => check.check === "string_format");
+  return def.format ?? declared?.format;
+}
+var FIXED_FORMATS = /* @__PURE__ */ new Map([
+  ["uuid", PLACEHOLDER_UUID],
+  ["datetime", PLACEHOLDER_DATETIME],
+  ["date", PLACEHOLDER_DATE],
+  ["time", PLACEHOLDER_TIME]
+]);
 function synthesizeString(def) {
   const lengths = readStringLengths(def);
-  if (def.format === "url") return synthesizeUrl(lengths);
-  if (def.format === "email") return synthesizeEmail(lengths);
-  return synthesizePlainString(lengths);
+  const format = formatOf(def);
+  if (format === "url") return synthesizeUrl(lengths);
+  if (format === "email") return synthesizeEmail(lengths);
+  const fixed = format === void 0 ? void 0 : FIXED_FORMATS.get(format);
+  return fixed ?? synthesizePlainString(lengths);
 }
 function selectNumber(bounds) {
   const { lower, upper, integer } = bounds;
@@ -97,20 +113,35 @@ function synthesizeEnum(def) {
   const [first] = Object.values(def.entries);
   return String(first);
 }
+function withoutOptional(leaf) {
+  const def = readDef(leaf);
+  return def.type === "optional" ? withoutOptional(def.innerType) : leaf;
+}
 function synthesizeLeaf(leaf) {
   const def = readDef(leaf);
   switch (def.type) {
     case "default":
+    case "prefault":
+    case "catch":
     case "optional":
       return void 0;
     case "nullable":
+    case "readonly":
       return synthesizeLeaf(def.innerType);
+    case "nonoptional":
+      return synthesizeLeaf(withoutOptional(def.innerType));
+    case "pipe":
+      return readDef(def.out).type === "boolean" && readDef(def.in).type === "string" ? PLACEHOLDER_BOOLEAN : synthesizeLeaf(def.in);
     case "string":
       return synthesizeString(def);
     case "number":
       return synthesizeNumber(def);
     case "boolean":
       return PLACEHOLDER_BOOLEAN;
+    case "date":
+      return PLACEHOLDER_DATETIME;
+    case "literal":
+      return String(def.values[0]);
     case "enum":
       return synthesizeEnum(def);
     default:
@@ -143,25 +174,43 @@ function flattenOverrides(overrides) {
   }
   return flat;
 }
-function applyOverrides(schema, base, overrides) {
+function applyOverrides(schema, base, overrides, overridden) {
   const flat = flattenOverrides(overrides ?? {});
   const entries = new Map(Object.entries(base));
   for (const binding of resolveSourceNames(schema)) {
     const value = flat.get(binding.path);
-    if (value !== void 0) entries.set(binding.variable, String(value));
+    if (value === void 0) continue;
+    entries.set(binding.variable, String(value));
+    overridden.add(binding.variable);
   }
   const source = /* @__PURE__ */ Object.create(null);
   for (const [variable, value] of entries) source[variable] = value;
   return source;
 }
-function buildTestSource(schema, overrides) {
-  return applyOverrides(schema, synthesizePlaceholderSource(schema), overrides);
+function explainUnsatisfiedLeaves(error, overridden) {
+  return new BymaxConfigValidationError(
+    error.issues.map(
+      (issue) => !issue.path.includes(".") || overridden.has(issue.variable) ? issue : {
+        ...issue,
+        message: `no placeholder satisfies this leaf (${issue.message}); pass an override for ${issue.path}`
+      }
+    )
+  );
+}
+function prepareTestConfig(schema, overrides) {
+  const overridden = /* @__PURE__ */ new Set();
+  const source = applyOverrides(schema, synthesizePlaceholderSource(schema), overrides, overridden);
+  try {
+    return { source, config: createValidatedConfig({ schema, source }) };
+  } catch (error) {
+    throw error instanceof BymaxConfigValidationError ? explainUnsatisfiedLeaves(error, overridden) : error;
+  }
 }
 function createTestConfig(schema, overrides) {
-  return createValidatedConfig({ schema, source: buildTestSource(schema, overrides) });
+  return prepareTestConfig(schema, overrides).config;
 }
 function configTestingModule(schema, overrides) {
-  const source = buildTestSource(schema, overrides);
+  const { source } = prepareTestConfig(schema, overrides);
   return BymaxConfigModule.forRoot({ schema, source });
 }
 

package/package.json

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