@bymax-one/nest-config 1.2.3 → 1.2.5

package/CHANGELOG.md

@@ -11,6 +11,106 @@ as the GitHub Release body, so each released version needs a matching
 
 ## [Unreleased]
 
+## [1.2.5] - 2026-11-01
+
+### Fixed
+
+- **A test override that is not a plain object is one issue.** A namespace given `null` threw a raw
+  `TypeError`, an array produced one issue per index, a `Map` or a `Date` applied
+  nothing and said nothing, and a class instance had its own fields read as overrides. `createTestConfig` and `configTestingModule` now report each of them once,
+  by name, as "the override for `x` must be an object", in the same `BymaxConfigValidationError` as any
+  unmatched path. The overrides argument itself is held to the same rule and reported as "the overrides
+  must be an object"; `undefined` and `null` still mean no overrides.
+
+  #### Apply to a derived backend
+
+  Run the test suites. A test that expected a `TypeError` for a `null` namespace now receives a
+  `BymaxConfigValidationError`. A namespace override given as a class instance was applied field by
+  field; it is now refused, so pass a plain object. A `Map` or a `Date` as a namespace override was
+  ignored; it is now refused too.
+
+### Changed
+
+- **The shipped bundles no longer carry comments.** The build runs `scripts/strip-bundle-comments.mjs`
+  after `tsup`: every comment is removed from `index.mjs` and `index.cjs` except the legal,
+  bundler-annotation and region-marker ones the script keeps, and the script proves with the
+  TypeScript parser that it changed no code. The documentation people read
+  comes from the `.d.ts` files, which are untouched. The internal bundle goes from 22,079 to 16,652
+  bytes and the package from 68.3 to 65.5 kB. Nothing to apply in a derived backend.
+- **The internal bundle has a size budget.** `scripts/check-size.mjs` gates `dist/internal/index.mjs`,
+  which carries nearly all of the code, at 4.6 KiB brotli. Tooling only.
+
+## [1.2.4] - 2026-11-01
+
+### Fixed
+
+- **A `source` that is present but `undefined` fails the boot.** `BymaxConfigModule.forRoot({ schema,
+source: loadSource() })` used to validate `process.env` when the loader returned nothing, and boot
+  successfully on configuration the host never meant to use. Passing the key with the value `undefined` or
+  `null` now throws a `TypeError` ("source was provided but is undefined or null"); omitting the key still reads
+  `process.env`.
+
+  #### Apply to a derived backend
+
+  Search for a `source:` option that can be `undefined`. If the host relied on the fall-back to
+  `process.env`, leave the key out instead of passing `undefined`.
+
+- **A `meta({ env })` that cannot name a variable is an issue.** An `env` that is present but is not
+  a non-empty string (`''`, `undefined`, a number) used to be skipped, and the leaf read the variable
+  derived from its path. The aggregated validation report now lists it, naming the variable the leaf
+  would read and the kind of value found, on any layer of the leaf: an inner layer whose `env` is
+  unusable is reported even when an outer layer's usable one wins. The issue is its own line for
+  that leaf, before the line about its value. A leaf with no `env` at all is unchanged, and
+  `resolveSourceNames` still answers the derived name.
+
+  #### Apply to a derived backend
+
+  Search the schemas for `meta({ env: ... })` whose argument can be empty or undefined (for example
+  `meta({ env: process.env.X })`) and give it a real name or remove the call.
+
+- **A test override that matches no leaf throws.** `createTestConfig` and `configTestingModule` used to
+  drop an override for a path the schema does not declare (a misspelled leaf, an undeclared namespace,
+  a stale override after a rename) and answer with a config that lacked it. They now throw a
+  `BymaxConfigValidationError` listing every unmatched path, before any provider is built, even when
+  the override's value is `undefined`. The path is the name shown in the report, and its footer asks
+  for a fix in the test rather than a restart of the process. A namespace given something other than
+  an object is reported once, by name, instead of once per character.
+
+  #### Apply to a derived backend
+
+  Run the test suites: an override that used to be silently ignored now fails. Correct the path or
+  delete the override.
+
+### Documentation
+
+- A leaf that ends in `.catch(fallback)` replaces an invalid value with its fallback and reports no
+  issue; the README now says so.
+
+### Changed
+
+- **A release that changes the public declarations must say so.** `check:api`
+  (`scripts/check-api-surface.mjs`) compares the built declarations with the previous published
+  version and fails when they differ unless the released version's CHANGELOG section has an
+  "Apply to a derived backend" note. Tooling only: nothing to apply in a derived backend.
+- **The mutation gate is 100.** `thresholds.break` moves from 95 to 100, and `high` and `low` with it,
+  because a cold run on `main` now has no survivor. Tooling only: nothing to apply in
+  a derived backend.
+- **The camelCase-to-variable converter has no equivalent mutant.** The acronym boundary is now a
+  zero-width lookaround instead of a capturing group with a quantifier whose shrunken form no input
+  could tell apart. Every derived variable name is unchanged: a new spec compares the converter
+  with the previous two-expression form on every string up to seven characters over
+  `a`, `B`, `C`, `1` and `_`. Nothing to apply in a derived backend.
+
+### Tests
+
+- **The README Quick Start is executed, not only type-checked.** A new spec takes the schema, the
+  `BymaxConfigModule.forRoot` registration and the `FeatureProvider` from the README text,
+  compiles and runs them against a real Nest testing graph, and asserts the stated outcomes: a
+  complete environment boots and the provider returns `<database url>::3000`, and an environment
+  missing both required variables fails with one error naming both. A wrong argument shape or a
+  value that fails validation now fails a test instead of reaching a reader. No source or
+  published-surface change, so there is nothing to apply in a derived backend.
+
 ## [1.2.3] - 2026-10-31
 
 ### Fixed
@@ -484,4 +584,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.2.1]: https://github.com/bymaxone/nest-config/compare/v1.2.0...v1.2.1
 [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
+[1.2.4]: https://github.com/bymaxone/nest-config/compare/v1.2.3...v1.2.4
+[1.2.5]: https://github.com/bymaxone/nest-config/compare/v1.2.4...v1.2.5
+[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.2.5...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.71%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-100.00%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>
@@ -206,8 +206,10 @@ BymaxConfigValidationError: environment validation failed (3 issues)
 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.
+The report has one line per violation: 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. A `meta({ env })` that
+cannot name a variable adds its own line for that leaf, before the line about its value, because it
+is a different mistake: merging the two would hide the one that explains the other.
 
 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
@@ -265,6 +267,10 @@ including `'false'`, becomes `true`, so use `z.stringbool()` for a flag. And a v
 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 that ends in `.catch(fallback)` replaces an invalid value with its fallback and reports no
+issue, so a mistyped variable reaches the application as the fallback; leave `.catch()` off a
+leaf whose failure should stop the boot.
+
 A leaf can override its derived variable name through schema metadata when a
 legacy name must be preserved:
 
@@ -276,9 +282,12 @@ 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.
+and `z.string().default('x').meta({ env: 'LEGACY' })` both read `LEGACY`. When more than one layer sets it, the outermost usable one wins. An `env` that is present but
+is not a non-empty string (`''`, `undefined`, a number) cannot name a variable, so validation reports it
+as an issue instead of letting the leaf read the variable derived from its path, on any layer: an
+inner layer whose `env` is unusable is reported even when an outer layer's usable one wins. A leaf
+with no `env` at all is unaffected. `resolveSourceNames` skips an unusable `env` and answers the
+derived name.
 
 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
@@ -309,7 +318,7 @@ Write `.meta({ open: true })` last: methods that build a new object schema, such
 | 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.                                                                                                                                                         |
+| `source`            | `Record<string, string \| undefined>`             | no       | Defaults to `process.env` when the key is omitted; a key present with the value `undefined` or `null` throws at boot. 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. |
 
@@ -604,7 +613,8 @@ resolves its variables through, so the list cannot drift from what `forRoot` rea
 `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.
+`NAMESPACE_LEAF` in SCREAMING_SNAKE_CASE, with a camelCase key split into words, when it has no
+`env` at all.
 It reads the schema only, never a source record, so it works on a schema exported as a
 value.
 
@@ -816,9 +826,8 @@ 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.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
+- ✅ **100.00% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
+  `break: 100`; provable equivalents carry their reason inline and nothing else survives
   ([report](./docs/mutation_testing_results.md))
 - ✅ **The value-free guarantee is tested, not assumed** — a sentinel secret is placed in a
   source and the assertion is that it appears nowhere in the rendered report or in the thrown
@@ -827,7 +836,8 @@ beyond "the tests pass".
   proven is the guarantee this package makes for its own generated text
 - ✅ **Published-artifact gates** — `check:exports` resolves the types the way each module
   system does, `check:runtime` loads every subpath from the packed tarball in ESM and
-  CommonJS, and `check:published` compiles this README's snippets against `dist/`
+  CommonJS, `check:published` compiles this README's snippets against `dist/`, and `check:api`
+  requires an "Apply to a derived backend" CHANGELOG note when the built declarations change
 - ✅ **Every suppression carries its reason** — no coverage directives anywhere; each
   `// Stryker disable` in the production source names, after the `:` Stryker reads it from,
   why the mutant it silences is behaviour-preserving, and `check:mutants` proves those
@@ -837,7 +847,7 @@ beyond "the tests pass".
 ```bash
 pnpm test          # unit suite
 pnpm test:cov      # unit suite with the 100% coverage gate
-pnpm mutation      # Stryker mutation testing (break: 95)
+pnpm mutation      # Stryker mutation testing (break: 100)
 pnpm typecheck     # tsc strict check
 pnpm lint          # ESLint
 ```
@@ -901,7 +911,10 @@ const moduleRef = await Test.createTestingModule({
 
 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
+of `undefined` is ignored, so a defaulted leaf cannot be unset. An override whose path matches no leaf
+of the schema throws, listing every such path, even when its value is `undefined`; a namespace given
+something other than a plain object is reported once, by name, and so is an overrides argument that is
+not a plain object; passing `undefined` or `null` for the whole argument means no overrides. 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.

package/dist/internal/index.cjs

@@ -53,45 +53,40 @@ var MIN_VARIABLE_COLUMN = 20;
 var VARIABLE_GUTTER = 2;
 var REPORT_HEADER = "environment validation failed";
 var REPORT_FOOTER = "Fix the variables above and restart the process.";
+var OVERRIDE_FOOTER = "Fix the overrides above in the test.";
 function pluralizeIssues(count) {
   const noun = count === 1 ? "issue" : "issues";
   return `${count} ${noun}`;
 }
+function nameOf(issue) {
+  return issue.variable === "" ? issue.path : issue.variable;
+}
 function computeColumnWidth(issues) {
   let longest = MIN_VARIABLE_COLUMN;
   for (const issue of issues) {
-    longest = Math.max(longest, issue.variable.length);
+    longest = Math.max(longest, nameOf(issue).length);
   }
   return longest + VARIABLE_GUTTER;
 }
 function formatIssueLine(issue, columnWidth) {
-  return `${REPORT_INDENT}${issue.variable.padEnd(columnWidth)}${issue.message}`;
+  return `${REPORT_INDENT}${nameOf(issue).padEnd(columnWidth)}${issue.message}`;
 }
 function formatIssueReport(issues) {
   const columnWidth = computeColumnWidth(issues);
   const lines = issues.map((issue) => formatIssueLine(issue, columnWidth));
   const header = `${REPORT_HEADER} (${pluralizeIssues(issues.length)})`;
-  return [header, "", ...lines, "", REPORT_FOOTER].join("\n");
+  const aboutOverrides = issues.length > 0 && issues.every((issue) => issue.variable === "");
+  return [header, "", ...lines, "", aboutOverrides ? OVERRIDE_FOOTER : REPORT_FOOTER].join("\n");
 }
 
 // src/errors.ts
 var ConfigErrorCode = Object.freeze({
-  /** Top-level error code: one or more schema violations were collected. */
   VALIDATION: "BYMAX_CONFIG_VALIDATION",
-  /** Issue code: a required variable is absent from the source. */
   MISSING: "BYMAX_CONFIG_MISSING",
-  /** Issue code: a variable is present but violates its constraint. */
   INVALID: "BYMAX_CONFIG_INVALID",
-  /** Issue code: strict mode found a source variable matching no declared leaf. */
   UNKNOWN_KEY: "BYMAX_CONFIG_UNKNOWN_KEY"
 });
 var BymaxConfigValidationError = class _BymaxConfigValidationError extends Error {
-  /**
-   * Build the aggregated error from the collected issues.
-   *
-   * @param issues - Every collected violation; copied and frozen so neither the
-   * caller nor consumer code can mutate the reported list.
-   */
   constructor(issues) {
     const normalized = issues.map(
       (issue) => Object.freeze({
@@ -102,7 +97,6 @@ var BymaxConfigValidationError = class _BymaxConfigValidationError extends Error
       })
     );
     super(formatIssueReport(normalized));
-    /** The stable top-level error code. */
     this.code = ConfigErrorCode.VALIDATION;
     Object.defineProperty(this, "name", {
       value: "BymaxConfigValidationError",
@@ -119,7 +113,7 @@ var BymaxConfigValidationError = class _BymaxConfigValidationError extends Error
 
 // src/source-mapping.ts
 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();
+  return segment.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/(?<=[A-Z])(?=[A-Z][a-z])/g, "_").toUpperCase();
 }
 function readEnvOverride(leaf) {
   for (let node = leaf; node !== void 0; ) {
@@ -143,6 +137,33 @@ function resolveSourceNames(schema) {
     }))
   );
 }
+function describeUnusable(value) {
+  if (value === "") return "an empty string";
+  if (value === void 0) return "undefined";
+  if (value === null) return "null";
+  return `${typeof value === "object" ? "an" : "a"} ${typeof value}`;
+}
+function describeUnusableEnv(leaf) {
+  for (let node = leaf; node !== void 0; ) {
+    const meta = node.meta();
+    if (meta !== void 0 && "env" in meta) {
+      const value = meta.env;
+      if (typeof value !== "string" || value.length === 0) return describeUnusable(value);
+    }
+    node = node._zod.def.innerType ?? node._zod.def.in;
+  }
+  return void 0;
+}
+function findUnusableEnvOverrides(schema) {
+  const unusable = [];
+  for (const [namespace, namespaceSchema] of Object.entries(schema.shape)) {
+    for (const [leafKey, leafSchema] of Object.entries(namespaceSchema.shape)) {
+      const found = describeUnusableEnv(leafSchema);
+      if (found !== void 0) unusable.push({ path: `${namespace}.${leafKey}`, found });
+    }
+  }
+  return unusable;
+}
 function resolveNamespacePrefixes(schema) {
   return Object.entries(schema.shape).map(([namespace, namespaceSchema]) => ({
     namespace,
@@ -302,6 +323,18 @@ function assertDistinctVariables(bindings) {
   }
   if (issues.length > 0) throw new BymaxConfigValidationError(issues);
 }
+function unusableOverrideIssues(schema, bindings) {
+  const variables = new Map(bindings.map((binding) => [binding.path, binding.variable]));
+  return findUnusableEnvOverrides(schema).map(({ path, found }) => {
+    const variable = variables.get(path);
+    return {
+      path,
+      variable,
+      code: ConfigErrorCode.INVALID,
+      message: `meta({ env }) must be a non-empty string, found ${found}; the leaf would read ${variable}`
+    };
+  });
+}
 function validateEnv(schema, source, options) {
   const bindings = resolveSourceNames(schema);
   assertDistinctVariables(bindings);
@@ -311,12 +344,13 @@ function validateEnv(schema, source, options) {
   const result = schema.safeParse(candidate);
   const prefixes = resolveNamespacePrefixes(schema);
   const unknown = options?.strict === true ? detectUnknownKeys(prefixes, bindings, sourceMap) : [];
+  const overrides = unusableOverrideIssues(schema, bindings);
   if (result.success) {
-    if (unknown.length === 0) return result.data;
-    throw new BymaxConfigValidationError(unknown);
+    if (unknown.length === 0 && overrides.length === 0) return result.data;
+    throw new BymaxConfigValidationError([...overrides, ...unknown]);
   }
   const issues = translateIssues(result.error.issues, bindings, prefixes, sourceMap);
-  throw new BymaxConfigValidationError([...issues, ...unknown]);
+  throw new BymaxConfigValidationError([...overrides, ...issues, ...unknown]);
 }
 
 // src/config.providers.ts
@@ -334,6 +368,11 @@ async function reportIssues(hook, error) {
   }
 }
 function createValidatedConfig(options) {
+  if ("source" in options && (options.source === void 0 || options.source === null)) {
+    throw new TypeError(
+      "BymaxConfigModule: source was provided but is undefined or null; omit the key to validate process.env, or pass the source that failed to load"
+    );
+  }
   const source = options.source ?? process.env;
   return deepFreeze(validateEnv(options.schema, source, { strict: options.strict === true }));
 }
@@ -354,35 +393,8 @@ var bymaxConfigProvider = {
 };
 var _config, _leaves;
 exports.ConfigService = class ConfigService {
-  /**
-   * Bind the accessor to the frozen configuration object.
-   *
-   * Builds a flat `namespace.leaf` lookup once so `get`/`has` are constant-time
-   * and never rebuild a map per call. Iteration over entries (rather than dynamic
-   * bracket indexing) avoids introducing a non-literal property sink.
-   *
-   * @param config - The validated, deep-frozen config injected via {@link BYMAX_CONFIG}.
-   */
   constructor(config) {
-    /**
-     * The frozen configuration root.
-     *
-     * Held in an ECMAScript private field rather than a TypeScript `private`
-     * property: `private` is erased at runtime, leaving an enumerable own
-     * property that `JSON.stringify`, `Object.entries`, object spread and
-     * `util.inspect` all walk into. This object aggregates every secret the
-     * application declared, so any code that incidentally serializes the
-     * injected service — a logger that renders its arguments, an observability
-     * SDK capturing the scope of a thrown error, a stray `console.log` — would
-     * emit them in plaintext. A `#` field is unreachable to all of those.
-     */
     __privateAdd(this, _config);
-    /**
-     * Precomputed `namespace.leaf` to value lookup, built once at construction.
-     *
-     * An ECMAScript private field for the same reason as the config root: it
-     * holds the same values, flattened.
-     */
     __privateAdd(this, _leaves);
     __privateSet(this, _config, config);
     const leaves = /* @__PURE__ */ new Map();
@@ -393,86 +405,21 @@ exports.ConfigService = class ConfigService {
     }
     __privateSet(this, _leaves, leaves);
   }
-  /**
-   * Describe the service for serialization without disclosing any value.
-   *
-   * `JSON.stringify` on an instance would otherwise yield `{}`, which reads as
-   * a bug rather than as a deliberate omission. Returning the namespace names
-   * keeps the output useful for debugging while the values stay unreachable.
-   *
-   * @returns The declared namespace names, never their contents.
-   * @example
-   * ```typescript
-   * JSON.stringify(config); // {"service":"ConfigService","namespaces":["server","database"]}
-   * ```
-   */
   toJSON() {
     return {
       service: "ConfigService",
       namespaces: Object.keys(__privateGet(this, _config))
     };
   }
-  /**
-   * Read a leaf value by its `namespace.leaf` dot-path.
-   *
-   * The return type is inferred from the path, so `get('server.port')` is typed
-   * `number` with no cast. Never throws for a declared path: validation ran once
-   * at bootstrap. An optional leaf without a default may still resolve to
-   * `undefined` when its type includes it.
-   *
-   * @typeParam TPath - A declared path drawn from {@link Path}<TConfig>.
-   * @param path - The two-level dot-path to resolve.
-   * @returns The leaf value, typed as {@link PathValue}<TConfig, TPath>.
-   * @example
-   * ```typescript
-   * const port = config.get('server.port'); // number
-   * ```
-   */
   get(path) {
     return this.resolve(path);
   }
-  /**
-   * Return the whole validated configuration as its deep-frozen root.
-   *
-   * Yields the same frozen reference the module registered, fully typed for
-   * arbitrary depth, which is the escape hatch for nesting deeper than the
-   * two-level dot-path inference covers.
-   *
-   * @returns The frozen configuration root.
-   * @example
-   * ```typescript
-   * const everything = config.getAll(); // Readonly<AppConfig>
-   * ```
-   */
   getAll() {
     return __privateGet(this, _config);
   }
-  /**
-   * Report whether a declared path resolves to a defined value.
-   *
-   * Returns `false` when the leaf resolved to `undefined` (an optional leaf
-   * without a default), distinguishing "declared but unset" from "declared and
-   * set" without a truthiness pitfall on falsy values such as `0` or `''`.
-   *
-   * @param path - The two-level dot-path to check.
-   * @returns True when the resolved value is not `undefined`.
-   * @example
-   * ```typescript
-   * if (config.has('redis.url')) connectRedis(config.get('redis.url'));
-   * ```
-   */
   has(path) {
     return this.resolve(path) !== void 0;
   }
-  /**
-   * Resolve a two-level dot-path to its raw leaf value.
-   *
-   * Looks the path up in the precomputed `namespace.leaf` map, so an unset leaf
-   * (or, defensively, an unexpected path) yields `undefined` instead of throwing.
-   *
-   * @param path - The declared two-level dot-path.
-   * @returns The leaf value as `unknown`, or `undefined` when the leaf is unset.
-   */
   resolve(path) {
     return __privateGet(this, _leaves).get(String(path));
   }
@@ -489,35 +436,12 @@ function appendTo(list, ...items) {
   return list === void 0 ? [...items] : [...list, ...items];
 }
 exports.BymaxConfigModule = class BymaxConfigModule extends ConfigurableModuleClass {
-  /**
-   * Register the module synchronously from a static schema.
-   *
-   * @param options - The module options plus the optional `isGlobal` extra.
-   * @returns The dynamic module augmented with the frozen config provider.
-   */
   static forRoot(options) {
     return exports.BymaxConfigModule.withConfigProvider(super.forRoot(options));
   }
-  /**
-   * Register the module asynchronously, resolving options through a factory.
-   *
-   * @param options - The async options with `useFactory` and explicit `inject`.
-   * @returns The dynamic module augmented with the frozen config provider.
-   */
   static forRootAsync(options) {
     return exports.BymaxConfigModule.withConfigProvider(super.forRootAsync(options));
   }
-  /**
-   * Append the config provider and typed accessor to a generated definition.
-   *
-   * Registers the frozen {@link BYMAX_CONFIG} provider and the {@link ConfigService}
-   * accessor (which injects that token), then exports both so consumers can
-   * inject either the raw frozen object or the typed service.
-   *
-   * @param definition - The dynamic module produced by the builder base class.
-   * @returns A definition that provides and exports {@link BYMAX_CONFIG} and
-   * {@link ConfigService}.
-   */
   static withConfigProvider(definition) {
     return {
       ...definition,
@@ -541,3 +465,4 @@ exports.assertDistinctVariables = assertDistinctVariables;
 exports.createValidatedConfig = createValidatedConfig;
 exports.defineEnv = defineEnv;
 exports.resolveSourceNames = resolveSourceNames;
+exports.unusableOverrideIssues = unusableOverrideIssues;

package/dist/internal/index.d.cts

@@ -557,6 +557,8 @@ declare function defineEnv<TShape extends EnvShape>(shape: TShape): EnvSchema<TS
  * @param options - The resolved module options (schema, source, strict).
  * @returns The validated, deep-frozen configuration output.
  * @throws {BymaxConfigValidationError} When the source fails the schema.
+ * @throws {TypeError} When `source` is present with the value `undefined` or `null`, which would
+ * otherwise validate `process.env` in place of the source that failed to load.
  * @example
  * ```typescript
  * const config = createValidatedConfig({ schema: envSchema });
@@ -644,5 +646,17 @@ declare function resolveSourceNames<TShape extends EnvShape = EnvShape>(schema:
  * @throws {BymaxConfigValidationError} When any variable is bound by more than one leaf.
  */
 declare function assertDistinctVariables(bindings: ReadonlyArray<SourceBinding>): void;
+/**
+ * Describe every leaf whose `meta({ env })` is present but cannot name a variable.
+ *
+ * The leaf would silently read the variable derived from its path, so it is a mistake in the
+ * schema, reported beside the violations of the source. The message names the variable the
+ * leaf reads and the kind of value `env` held, never the value.
+ *
+ * @param schema - A schema produced by `defineEnv`.
+ * @param bindings - Every leaf binding of the schema, from `resolveSourceNames`.
+ * @returns One issue per affected leaf, in schema order.
+ */
+declare function unusableOverrideIssues<TShape extends EnvShape>(schema: EnvSchema<TShape>, bindings: ReadonlyArray<SourceBinding>): ConfigIssue[];
 
-export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, type BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, type ConfigIssue, type ConfigIssueCode, ConfigService, type ConfigValidationCode, type EnvLeaf, type EnvNamespace, type EnvOutput, type EnvSchema, type EnvShape, type Path, type PathValue, type SourceBinding, assertDistinctVariables, createValidatedConfig, defineEnv, resolveSourceNames };
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, type BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, type ConfigIssue, type ConfigIssueCode, ConfigService, type ConfigValidationCode, type EnvLeaf, type EnvNamespace, type EnvOutput, type EnvSchema, type EnvShape, type Path, type PathValue, type SourceBinding, assertDistinctVariables, createValidatedConfig, defineEnv, resolveSourceNames, unusableOverrideIssues };

package/dist/internal/index.d.ts

@@ -557,6 +557,8 @@ declare function defineEnv<TShape extends EnvShape>(shape: TShape): EnvSchema<TS
  * @param options - The resolved module options (schema, source, strict).
  * @returns The validated, deep-frozen configuration output.
  * @throws {BymaxConfigValidationError} When the source fails the schema.
+ * @throws {TypeError} When `source` is present with the value `undefined` or `null`, which would
+ * otherwise validate `process.env` in place of the source that failed to load.
  * @example
  * ```typescript
  * const config = createValidatedConfig({ schema: envSchema });
@@ -644,5 +646,17 @@ declare function resolveSourceNames<TShape extends EnvShape = EnvShape>(schema:
  * @throws {BymaxConfigValidationError} When any variable is bound by more than one leaf.
  */
 declare function assertDistinctVariables(bindings: ReadonlyArray<SourceBinding>): void;
+/**
+ * Describe every leaf whose `meta({ env })` is present but cannot name a variable.
+ *
+ * The leaf would silently read the variable derived from its path, so it is a mistake in the
+ * schema, reported beside the violations of the source. The message names the variable the
+ * leaf reads and the kind of value `env` held, never the value.
+ *
+ * @param schema - A schema produced by `defineEnv`.
+ * @param bindings - Every leaf binding of the schema, from `resolveSourceNames`.
+ * @returns One issue per affected leaf, in schema order.
+ */
+declare function unusableOverrideIssues<TShape extends EnvShape>(schema: EnvSchema<TShape>, bindings: ReadonlyArray<SourceBinding>): ConfigIssue[];
 
-export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, type BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, type ConfigIssue, type ConfigIssueCode, ConfigService, type ConfigValidationCode, type EnvLeaf, type EnvNamespace, type EnvOutput, type EnvSchema, type EnvShape, type Path, type PathValue, type SourceBinding, assertDistinctVariables, createValidatedConfig, defineEnv, resolveSourceNames };
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, type BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, type ConfigIssue, type ConfigIssueCode, ConfigService, type ConfigValidationCode, type EnvLeaf, type EnvNamespace, type EnvOutput, type EnvSchema, type EnvShape, type Path, type PathValue, type SourceBinding, assertDistinctVariables, createValidatedConfig, defineEnv, resolveSourceNames, unusableOverrideIssues };

package/dist/internal/index.mjs

@@ -51,45 +51,40 @@ var MIN_VARIABLE_COLUMN = 20;
 var VARIABLE_GUTTER = 2;
 var REPORT_HEADER = "environment validation failed";
 var REPORT_FOOTER = "Fix the variables above and restart the process.";
+var OVERRIDE_FOOTER = "Fix the overrides above in the test.";
 function pluralizeIssues(count) {
   const noun = count === 1 ? "issue" : "issues";
   return `${count} ${noun}`;
 }
+function nameOf(issue) {
+  return issue.variable === "" ? issue.path : issue.variable;
+}
 function computeColumnWidth(issues) {
   let longest = MIN_VARIABLE_COLUMN;
   for (const issue of issues) {
-    longest = Math.max(longest, issue.variable.length);
+    longest = Math.max(longest, nameOf(issue).length);
   }
   return longest + VARIABLE_GUTTER;
 }
 function formatIssueLine(issue, columnWidth) {
-  return `${REPORT_INDENT}${issue.variable.padEnd(columnWidth)}${issue.message}`;
+  return `${REPORT_INDENT}${nameOf(issue).padEnd(columnWidth)}${issue.message}`;
 }
 function formatIssueReport(issues) {
   const columnWidth = computeColumnWidth(issues);
   const lines = issues.map((issue) => formatIssueLine(issue, columnWidth));
   const header = `${REPORT_HEADER} (${pluralizeIssues(issues.length)})`;
-  return [header, "", ...lines, "", REPORT_FOOTER].join("\n");
+  const aboutOverrides = issues.length > 0 && issues.every((issue) => issue.variable === "");
+  return [header, "", ...lines, "", aboutOverrides ? OVERRIDE_FOOTER : REPORT_FOOTER].join("\n");
 }
 
 // src/errors.ts
 var ConfigErrorCode = Object.freeze({
-  /** Top-level error code: one or more schema violations were collected. */
   VALIDATION: "BYMAX_CONFIG_VALIDATION",
-  /** Issue code: a required variable is absent from the source. */
   MISSING: "BYMAX_CONFIG_MISSING",
-  /** Issue code: a variable is present but violates its constraint. */
   INVALID: "BYMAX_CONFIG_INVALID",
-  /** Issue code: strict mode found a source variable matching no declared leaf. */
   UNKNOWN_KEY: "BYMAX_CONFIG_UNKNOWN_KEY"
 });
 var BymaxConfigValidationError = class _BymaxConfigValidationError extends Error {
-  /**
-   * Build the aggregated error from the collected issues.
-   *
-   * @param issues - Every collected violation; copied and frozen so neither the
-   * caller nor consumer code can mutate the reported list.
-   */
   constructor(issues) {
     const normalized = issues.map(
       (issue) => Object.freeze({
@@ -100,7 +95,6 @@ var BymaxConfigValidationError = class _BymaxConfigValidationError extends Error
       })
     );
     super(formatIssueReport(normalized));
-    /** The stable top-level error code. */
     this.code = ConfigErrorCode.VALIDATION;
     Object.defineProperty(this, "name", {
       value: "BymaxConfigValidationError",
@@ -117,7 +111,7 @@ var BymaxConfigValidationError = class _BymaxConfigValidationError extends Error
 
 // src/source-mapping.ts
 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();
+  return segment.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/(?<=[A-Z])(?=[A-Z][a-z])/g, "_").toUpperCase();
 }
 function readEnvOverride(leaf) {
   for (let node = leaf; node !== void 0; ) {
@@ -141,6 +135,33 @@ function resolveSourceNames(schema) {
     }))
   );
 }
+function describeUnusable(value) {
+  if (value === "") return "an empty string";
+  if (value === void 0) return "undefined";
+  if (value === null) return "null";
+  return `${typeof value === "object" ? "an" : "a"} ${typeof value}`;
+}
+function describeUnusableEnv(leaf) {
+  for (let node = leaf; node !== void 0; ) {
+    const meta = node.meta();
+    if (meta !== void 0 && "env" in meta) {
+      const value = meta.env;
+      if (typeof value !== "string" || value.length === 0) return describeUnusable(value);
+    }
+    node = node._zod.def.innerType ?? node._zod.def.in;
+  }
+  return void 0;
+}
+function findUnusableEnvOverrides(schema) {
+  const unusable = [];
+  for (const [namespace, namespaceSchema] of Object.entries(schema.shape)) {
+    for (const [leafKey, leafSchema] of Object.entries(namespaceSchema.shape)) {
+      const found = describeUnusableEnv(leafSchema);
+      if (found !== void 0) unusable.push({ path: `${namespace}.${leafKey}`, found });
+    }
+  }
+  return unusable;
+}
 function resolveNamespacePrefixes(schema) {
   return Object.entries(schema.shape).map(([namespace, namespaceSchema]) => ({
     namespace,
@@ -300,6 +321,18 @@ function assertDistinctVariables(bindings) {
   }
   if (issues.length > 0) throw new BymaxConfigValidationError(issues);
 }
+function unusableOverrideIssues(schema, bindings) {
+  const variables = new Map(bindings.map((binding) => [binding.path, binding.variable]));
+  return findUnusableEnvOverrides(schema).map(({ path, found }) => {
+    const variable = variables.get(path);
+    return {
+      path,
+      variable,
+      code: ConfigErrorCode.INVALID,
+      message: `meta({ env }) must be a non-empty string, found ${found}; the leaf would read ${variable}`
+    };
+  });
+}
 function validateEnv(schema, source, options) {
   const bindings = resolveSourceNames(schema);
   assertDistinctVariables(bindings);
@@ -309,12 +342,13 @@ function validateEnv(schema, source, options) {
   const result = schema.safeParse(candidate);
   const prefixes = resolveNamespacePrefixes(schema);
   const unknown = options?.strict === true ? detectUnknownKeys(prefixes, bindings, sourceMap) : [];
+  const overrides = unusableOverrideIssues(schema, bindings);
   if (result.success) {
-    if (unknown.length === 0) return result.data;
-    throw new BymaxConfigValidationError(unknown);
+    if (unknown.length === 0 && overrides.length === 0) return result.data;
+    throw new BymaxConfigValidationError([...overrides, ...unknown]);
   }
   const issues = translateIssues(result.error.issues, bindings, prefixes, sourceMap);
-  throw new BymaxConfigValidationError([...issues, ...unknown]);
+  throw new BymaxConfigValidationError([...overrides, ...issues, ...unknown]);
 }
 
 // src/config.providers.ts
@@ -332,6 +366,11 @@ async function reportIssues(hook, error) {
   }
 }
 function createValidatedConfig(options) {
+  if ("source" in options && (options.source === void 0 || options.source === null)) {
+    throw new TypeError(
+      "BymaxConfigModule: source was provided but is undefined or null; omit the key to validate process.env, or pass the source that failed to load"
+    );
+  }
   const source = options.source ?? process.env;
   return deepFreeze(validateEnv(options.schema, source, { strict: options.strict === true }));
 }
@@ -352,35 +391,8 @@ var bymaxConfigProvider = {
 };
 var _config, _leaves;
 var ConfigService = class {
-  /**
-   * Bind the accessor to the frozen configuration object.
-   *
-   * Builds a flat `namespace.leaf` lookup once so `get`/`has` are constant-time
-   * and never rebuild a map per call. Iteration over entries (rather than dynamic
-   * bracket indexing) avoids introducing a non-literal property sink.
-   *
-   * @param config - The validated, deep-frozen config injected via {@link BYMAX_CONFIG}.
-   */
   constructor(config) {
-    /**
-     * The frozen configuration root.
-     *
-     * Held in an ECMAScript private field rather than a TypeScript `private`
-     * property: `private` is erased at runtime, leaving an enumerable own
-     * property that `JSON.stringify`, `Object.entries`, object spread and
-     * `util.inspect` all walk into. This object aggregates every secret the
-     * application declared, so any code that incidentally serializes the
-     * injected service — a logger that renders its arguments, an observability
-     * SDK capturing the scope of a thrown error, a stray `console.log` — would
-     * emit them in plaintext. A `#` field is unreachable to all of those.
-     */
     __privateAdd(this, _config);
-    /**
-     * Precomputed `namespace.leaf` to value lookup, built once at construction.
-     *
-     * An ECMAScript private field for the same reason as the config root: it
-     * holds the same values, flattened.
-     */
     __privateAdd(this, _leaves);
     __privateSet(this, _config, config);
     const leaves = /* @__PURE__ */ new Map();
@@ -391,86 +403,21 @@ var ConfigService = class {
     }
     __privateSet(this, _leaves, leaves);
   }
-  /**
-   * Describe the service for serialization without disclosing any value.
-   *
-   * `JSON.stringify` on an instance would otherwise yield `{}`, which reads as
-   * a bug rather than as a deliberate omission. Returning the namespace names
-   * keeps the output useful for debugging while the values stay unreachable.
-   *
-   * @returns The declared namespace names, never their contents.
-   * @example
-   * ```typescript
-   * JSON.stringify(config); // {"service":"ConfigService","namespaces":["server","database"]}
-   * ```
-   */
   toJSON() {
     return {
       service: "ConfigService",
       namespaces: Object.keys(__privateGet(this, _config))
     };
   }
-  /**
-   * Read a leaf value by its `namespace.leaf` dot-path.
-   *
-   * The return type is inferred from the path, so `get('server.port')` is typed
-   * `number` with no cast. Never throws for a declared path: validation ran once
-   * at bootstrap. An optional leaf without a default may still resolve to
-   * `undefined` when its type includes it.
-   *
-   * @typeParam TPath - A declared path drawn from {@link Path}<TConfig>.
-   * @param path - The two-level dot-path to resolve.
-   * @returns The leaf value, typed as {@link PathValue}<TConfig, TPath>.
-   * @example
-   * ```typescript
-   * const port = config.get('server.port'); // number
-   * ```
-   */
   get(path) {
     return this.resolve(path);
   }
-  /**
-   * Return the whole validated configuration as its deep-frozen root.
-   *
-   * Yields the same frozen reference the module registered, fully typed for
-   * arbitrary depth, which is the escape hatch for nesting deeper than the
-   * two-level dot-path inference covers.
-   *
-   * @returns The frozen configuration root.
-   * @example
-   * ```typescript
-   * const everything = config.getAll(); // Readonly<AppConfig>
-   * ```
-   */
   getAll() {
     return __privateGet(this, _config);
   }
-  /**
-   * Report whether a declared path resolves to a defined value.
-   *
-   * Returns `false` when the leaf resolved to `undefined` (an optional leaf
-   * without a default), distinguishing "declared but unset" from "declared and
-   * set" without a truthiness pitfall on falsy values such as `0` or `''`.
-   *
-   * @param path - The two-level dot-path to check.
-   * @returns True when the resolved value is not `undefined`.
-   * @example
-   * ```typescript
-   * if (config.has('redis.url')) connectRedis(config.get('redis.url'));
-   * ```
-   */
   has(path) {
     return this.resolve(path) !== void 0;
   }
-  /**
-   * Resolve a two-level dot-path to its raw leaf value.
-   *
-   * Looks the path up in the precomputed `namespace.leaf` map, so an unset leaf
-   * (or, defensively, an unexpected path) yields `undefined` instead of throwing.
-   *
-   * @param path - The declared two-level dot-path.
-   * @returns The leaf value as `unknown`, or `undefined` when the leaf is unset.
-   */
   resolve(path) {
     return __privateGet(this, _leaves).get(String(path));
   }
@@ -487,35 +434,12 @@ function appendTo(list, ...items) {
   return list === void 0 ? [...items] : [...list, ...items];
 }
 var BymaxConfigModule = class extends ConfigurableModuleClass {
-  /**
-   * Register the module synchronously from a static schema.
-   *
-   * @param options - The module options plus the optional `isGlobal` extra.
-   * @returns The dynamic module augmented with the frozen config provider.
-   */
   static forRoot(options) {
     return BymaxConfigModule.withConfigProvider(super.forRoot(options));
   }
-  /**
-   * Register the module asynchronously, resolving options through a factory.
-   *
-   * @param options - The async options with `useFactory` and explicit `inject`.
-   * @returns The dynamic module augmented with the frozen config provider.
-   */
   static forRootAsync(options) {
     return BymaxConfigModule.withConfigProvider(super.forRootAsync(options));
   }
-  /**
-   * Append the config provider and typed accessor to a generated definition.
-   *
-   * Registers the frozen {@link BYMAX_CONFIG} provider and the {@link ConfigService}
-   * accessor (which injects that token), then exports both so consumers can
-   * inject either the raw frozen object or the typed service.
-   *
-   * @param definition - The dynamic module produced by the builder base class.
-   * @returns A definition that provides and exports {@link BYMAX_CONFIG} and
-   * {@link ConfigService}.
-   */
   static withConfigProvider(definition) {
     return {
       ...definition,
@@ -531,4 +455,4 @@ function defineEnv(shape) {
   return z.object(shape);
 }
 
-export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigValidationError, ConfigErrorCode, ConfigService, assertDistinctVariables, createValidatedConfig, defineEnv, resolveSourceNames };
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigValidationError, ConfigErrorCode, ConfigService, assertDistinctVariables, createValidatedConfig, defineEnv, resolveSourceNames, unusableOverrideIssues };

package/dist/testing/index.cjs

@@ -167,19 +167,61 @@ function synthesizePlaceholderSource(schema) {
 }
 
 // src/testing/create-test-config.ts
-function flattenOverrides(overrides) {
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function unplacedIssue(path, code, message) {
+  return { path, variable: "", code, message };
+}
+function flattenOverrides(overrides, declared) {
   const flat = /* @__PURE__ */ new Map();
+  const unplaced = [];
+  if (overrides === void 0 || overrides === null) return { flat, unplaced };
+  if (!isPlainObject(overrides)) {
+    unplaced.push(
+      unplacedIssue("(overrides)", internal.ConfigErrorCode.INVALID, "the overrides must be an object")
+    );
+    return { flat, unplaced };
+  }
   for (const [namespace, leaves] of Object.entries(overrides)) {
+    if (!isPlainObject(leaves)) {
+      unplaced.push(
+        unplacedIssue(
+          namespace,
+          internal.ConfigErrorCode.INVALID,
+          `the override for \`${namespace}\` must be an object`
+        )
+      );
+      continue;
+    }
     for (const [leaf, value] of Object.entries(leaves)) {
-      flat.set(`${namespace}.${leaf}`, value);
+      const path = `${namespace}.${leaf}`;
+      if (declared.has(path)) {
+        flat.set(path, value);
+      } else {
+        unplaced.push(
+          unplacedIssue(
+            path,
+            internal.ConfigErrorCode.UNKNOWN_KEY,
+            "no leaf of the schema is at this path; the override was not applied"
+          )
+        );
+      }
     }
   }
-  return flat;
+  return { flat, unplaced };
 }
 function applyOverrides(schema, base, overrides, overridden) {
-  const flat = flattenOverrides(overrides ?? {});
+  const bindings = internal.resolveSourceNames(schema);
+  const { flat, unplaced } = flattenOverrides(
+    overrides,
+    new Set(bindings.map((binding) => binding.path))
+  );
+  if (unplaced.length > 0) throw new internal.BymaxConfigValidationError(unplaced);
   const entries = new Map(Object.entries(base));
-  for (const binding of internal.resolveSourceNames(schema)) {
+  for (const binding of bindings) {
     const value = flat.get(binding.path);
     if (value === void 0) continue;
     entries.set(binding.variable, String(value));
@@ -200,7 +242,10 @@ function explainUnsatisfiedLeaves(error, overridden) {
   );
 }
 function prepareTestConfig(schema, overrides) {
-  internal.assertDistinctVariables(internal.resolveSourceNames(schema));
+  const bindings = internal.resolveSourceNames(schema);
+  internal.assertDistinctVariables(bindings);
+  const unusable = internal.unusableOverrideIssues(schema, bindings);
+  if (unusable.length > 0) throw new internal.BymaxConfigValidationError(unusable);
   const overridden = /* @__PURE__ */ new Set();
   const source = applyOverrides(schema, synthesizePlaceholderSource(schema), overrides, overridden);
   try {

package/dist/testing/index.mjs

@@ -1,4 +1,4 @@
-import { BymaxConfigModule, assertDistinctVariables, resolveSourceNames, createValidatedConfig, BymaxConfigValidationError } from '@bymax-one/nest-config/internal';
+import { BymaxConfigModule, resolveSourceNames, assertDistinctVariables, unusableOverrideIssues, BymaxConfigValidationError, createValidatedConfig, ConfigErrorCode } from '@bymax-one/nest-config/internal';
 
 // src/testing/create-test-config.ts
 var FILLER_CHARACTER = "a";
@@ -165,19 +165,61 @@ function synthesizePlaceholderSource(schema) {
 }
 
 // src/testing/create-test-config.ts
-function flattenOverrides(overrides) {
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function unplacedIssue(path, code, message) {
+  return { path, variable: "", code, message };
+}
+function flattenOverrides(overrides, declared) {
   const flat = /* @__PURE__ */ new Map();
+  const unplaced = [];
+  if (overrides === void 0 || overrides === null) return { flat, unplaced };
+  if (!isPlainObject(overrides)) {
+    unplaced.push(
+      unplacedIssue("(overrides)", ConfigErrorCode.INVALID, "the overrides must be an object")
+    );
+    return { flat, unplaced };
+  }
   for (const [namespace, leaves] of Object.entries(overrides)) {
+    if (!isPlainObject(leaves)) {
+      unplaced.push(
+        unplacedIssue(
+          namespace,
+          ConfigErrorCode.INVALID,
+          `the override for \`${namespace}\` must be an object`
+        )
+      );
+      continue;
+    }
     for (const [leaf, value] of Object.entries(leaves)) {
-      flat.set(`${namespace}.${leaf}`, value);
+      const path = `${namespace}.${leaf}`;
+      if (declared.has(path)) {
+        flat.set(path, value);
+      } else {
+        unplaced.push(
+          unplacedIssue(
+            path,
+            ConfigErrorCode.UNKNOWN_KEY,
+            "no leaf of the schema is at this path; the override was not applied"
+          )
+        );
+      }
     }
   }
-  return flat;
+  return { flat, unplaced };
 }
 function applyOverrides(schema, base, overrides, overridden) {
-  const flat = flattenOverrides(overrides ?? {});
+  const bindings = resolveSourceNames(schema);
+  const { flat, unplaced } = flattenOverrides(
+    overrides,
+    new Set(bindings.map((binding) => binding.path))
+  );
+  if (unplaced.length > 0) throw new BymaxConfigValidationError(unplaced);
   const entries = new Map(Object.entries(base));
-  for (const binding of resolveSourceNames(schema)) {
+  for (const binding of bindings) {
     const value = flat.get(binding.path);
     if (value === void 0) continue;
     entries.set(binding.variable, String(value));
@@ -198,7 +240,10 @@ function explainUnsatisfiedLeaves(error, overridden) {
   );
 }
 function prepareTestConfig(schema, overrides) {
-  assertDistinctVariables(resolveSourceNames(schema));
+  const bindings = resolveSourceNames(schema);
+  assertDistinctVariables(bindings);
+  const unusable = unusableOverrideIssues(schema, bindings);
+  if (unusable.length > 0) throw new BymaxConfigValidationError(unusable);
   const overridden = /* @__PURE__ */ new Set();
   const source = applyOverrides(schema, synthesizePlaceholderSource(schema), overrides, overridden);
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-config",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Typed and validated environment configuration entry point for NestJS 11 applications, built on Zod v4.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -54,7 +54,8 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "pnpm clean && tsup",
+    "build": "pnpm clean && tsup && node scripts/strip-bundle-comments.mjs",
+    "check:api": "node scripts/check-api-surface.mjs",
     "check:exports": "attw --pack . --profile strict",
     "check:lint-graph": "node scripts/check-lint-graph-rules.mjs",
     "check:mutants": "node scripts/check-mutation-directives.mjs",