@bymax-one/nest-config 1.2.2 → 1.2.3

package/CHANGELOG.md

@@ -11,6 +11,21 @@ as the GitHub Release body, so each released version needs a matching
 
 ## [Unreleased]
 
+## [1.2.3] - 2026-10-31
+
+### Fixed
+
+- **A schema in which two leaves read one variable is rejected.** `a.bC` and `aB.c` both
+  derive `A_B_C`, and `httpServer.port` and `HTTPServer.port` both derive
+  `HTTP_SERVER_PORT`; so does giving two leaves the same `meta({ env })`. Each pair used to
+  read one value silently, so setting the variable satisfied both leaves and neither could
+  tell. `forRoot`, `createValidatedConfig` and the testing helpers now throw a
+  `BymaxConfigValidationError` before the source is read, with one `BYMAX_CONFIG_INVALID`
+  issue per colliding leaf naming the other leaves and the shared variable. There is no
+  opt-out. `resolveSourceNames` still returns every binding. **Apply to a derived
+  backend:** a colliding schema now fails at boot. Give one leaf of each pair a distinct
+  `meta({ env })`, or read one leaf and derive the other value from it in the consumer.
+
 ## [1.2.2] - 2026-10-31
 
 ### Added
@@ -468,4 +483,5 @@ have regressed from. They are kept because the reasoning is worth having.
 [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
 [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
+[1.2.3]: https://github.com/bymaxone/nest-config/compare/v1.2.2...v1.2.3
+[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.2.3...HEAD

package/README.md

@@ -14,7 +14,7 @@
   <a href="https://www.npmjs.com/package/@bymax-one/nest-config"><img src="https://img.shields.io/npm/dm/@bymax-one/nest-config?style=flat-square&colorA=000000&colorB=000000" alt="npm downloads" /></a>
   <a href="https://github.com/bymaxone/nest-config/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/bymaxone/nest-config/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI" alt="CI status" /></a>
   <a href="https://github.com/bymaxone/nest-config/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000" alt="coverage" /></a>
-  <a href="https://github.com/bymaxone/nest-config/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-99.69%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
+  <a href="https://github.com/bymaxone/nest-config/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-99.71%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/bymaxone/nest-config"><img src="https://api.scorecard.dev/projects/github.com/bymaxone/nest-config/badge?style=flat-square" alt="OpenSSF Scorecard" /></a>
   <a href="https://github.com/bymaxone/nest-config/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bymaxone/nest-config?style=flat-square&colorA=000000&colorB=000000" alt="license" /></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
@@ -638,8 +638,9 @@ it('documents every variable the schema reads in .env.example', () => {
   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.
+  `HTTP_SERVER_PORT`. Every binding is returned and none is dropped, so a tool can see the
+  collision; validation rejects such a schema (see the error catalog). Giving two leaves
+  the same `meta({ env })` is the same collision, and there is no opt-out.
 - **An open namespace changes nothing.** `meta({ open: true })` only waives strict
   unknown-key detection, so the list is the same whether a namespace is open or closed. It
   does not help to find variables in `.env.example` that no leaf reads.
@@ -648,12 +649,12 @@ it('documents every variable the schema reads in .env.example', () => {
 
 ## 🚨 Error Catalog
 
-| Code                       | Meaning                                                |
-| -------------------------- | ------------------------------------------------------ |
-| `BYMAX_CONFIG_VALIDATION`  | One or more schema violations (top-level error code).  |
-| `BYMAX_CONFIG_MISSING`     | Required variable absent from the source (issue code). |
-| `BYMAX_CONFIG_INVALID`     | Present but failed its constraint (issue code).        |
-| `BYMAX_CONFIG_UNKNOWN_KEY` | Strict mode: source variable matches no declared leaf. |
+| Code                       | Meaning                                                   |
+| -------------------------- | --------------------------------------------------------- |
+| `BYMAX_CONFIG_VALIDATION`  | One or more schema violations (top-level error code).     |
+| `BYMAX_CONFIG_MISSING`     | Required variable absent from the source (issue code).    |
+| `BYMAX_CONFIG_INVALID`     | Failed its constraint, or shares a variable (issue code). |
+| `BYMAX_CONFIG_UNKNOWN_KEY` | Strict mode: source variable matches no declared leaf.    |
 
 ## 🏗️ Architecture
 
@@ -815,7 +816,7 @@ Configuration decides whether a process may start at all, so the suite is held t
 beyond "the tests pass".
 
 - ✅ **100% line coverage** — statements, branches, functions and lines, enforced as a gate
-- ✅ **99.69% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
+- ✅ **99.71% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
   `break: 95`; ten provable equivalents carry their reason inline, and the one survivor left
   is an equivalent no directive can reach, so it stays counted rather than silenced
   ([report](./docs/mutation_testing_results.md))

package/dist/internal/index.cjs

@@ -282,8 +282,29 @@ function detectUnknownKeys(prefixes, bindings, source) {
     (left, right) => Number(left.variable > right.variable) - Number(left.variable < right.variable)
   );
 }
+function assertDistinctVariables(bindings) {
+  const byVariable = /* @__PURE__ */ new Map();
+  for (const { path, variable } of bindings) {
+    byVariable.set(variable, [...byVariable.get(variable) ?? [], path]);
+  }
+  const issues = [];
+  for (const [variable, paths] of byVariable) {
+    if (paths.length < 2) continue;
+    for (const path of paths) {
+      const others = paths.filter((other) => other !== path).join(", ");
+      issues.push({
+        path,
+        variable,
+        code: ConfigErrorCode.INVALID,
+        message: `shares this variable with ${others}; rename one with meta({ env })`
+      });
+    }
+  }
+  if (issues.length > 0) throw new BymaxConfigValidationError(issues);
+}
 function validateEnv(schema, source, options) {
   const bindings = resolveSourceNames(schema);
+  assertDistinctVariables(bindings);
   const sourceMap = new Map(Object.entries(source));
   const namespaces = Object.keys(schema.shape);
   const candidate = buildCandidate(namespaces, collectPresentLeaves(bindings, sourceMap));
@@ -516,6 +537,7 @@ exports.BYMAX_CONFIG = BYMAX_CONFIG;
 exports.BYMAX_CONFIG_OPTIONS = BYMAX_CONFIG_OPTIONS;
 exports.BymaxConfigValidationError = BymaxConfigValidationError;
 exports.ConfigErrorCode = ConfigErrorCode;
+exports.assertDistinctVariables = assertDistinctVariables;
 exports.createValidatedConfig = createValidatedConfig;
 exports.defineEnv = defineEnv;
 exports.resolveSourceNames = resolveSourceNames;

package/dist/internal/index.d.cts

@@ -604,7 +604,7 @@ interface SourceBinding {
  * 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
+ * and none is dropped, though validation rejects a schema that holds such a pair. 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.
@@ -619,4 +619,30 @@ interface SourceBinding {
  */
 declare function resolveSourceNames<TShape extends EnvShape = EnvShape>(schema: EnvSchema<TShape>): readonly SourceBinding[];
 
-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, createValidatedConfig, defineEnv, resolveSourceNames };
+/**
+ * @fileoverview Single-pass environment validator. Maps a flat source record
+ * onto the nested schema through the resolved source-name bindings, runs exactly
+ * one Zod parse, and either returns the typed parsed output or throws a
+ * BymaxConfigValidationError aggregating every violation. Zod issues are
+ * translated into value-free ConfigIssue descriptions that state only the
+ * expected constraint, never the received value. The one exception is the
+ * message a schema author attaches to a `custom` issue (`.check`, `.refine`,
+ * `.superRefine`), which is reported as written: it is schema text, not input,
+ * and it is the only place a conditional or cross-field rule can explain itself.
+ * @layer Service
+ */
+
+/**
+ * Reject a schema in which two leaves read one source variable.
+ *
+ * Two leaves that derive, or are told through `meta({ env })`, the same variable would
+ * each read the one value and neither could report on its own, so the schema is wrong
+ * before any source is looked at. One issue is produced per colliding leaf, in order of
+ * first appearance, each naming the other leaves that share its variable.
+ *
+ * @param bindings - Every leaf binding of a schema, from `resolveSourceNames`.
+ * @throws {BymaxConfigValidationError} When any variable is bound by more than one leaf.
+ */
+declare function assertDistinctVariables(bindings: ReadonlyArray<SourceBinding>): void;
+
+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 };

package/dist/internal/index.d.ts

@@ -604,7 +604,7 @@ interface SourceBinding {
  * 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
+ * and none is dropped, though validation rejects a schema that holds such a pair. 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.
@@ -619,4 +619,30 @@ interface SourceBinding {
  */
 declare function resolveSourceNames<TShape extends EnvShape = EnvShape>(schema: EnvSchema<TShape>): readonly SourceBinding[];
 
-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, createValidatedConfig, defineEnv, resolveSourceNames };
+/**
+ * @fileoverview Single-pass environment validator. Maps a flat source record
+ * onto the nested schema through the resolved source-name bindings, runs exactly
+ * one Zod parse, and either returns the typed parsed output or throws a
+ * BymaxConfigValidationError aggregating every violation. Zod issues are
+ * translated into value-free ConfigIssue descriptions that state only the
+ * expected constraint, never the received value. The one exception is the
+ * message a schema author attaches to a `custom` issue (`.check`, `.refine`,
+ * `.superRefine`), which is reported as written: it is schema text, not input,
+ * and it is the only place a conditional or cross-field rule can explain itself.
+ * @layer Service
+ */
+
+/**
+ * Reject a schema in which two leaves read one source variable.
+ *
+ * Two leaves that derive, or are told through `meta({ env })`, the same variable would
+ * each read the one value and neither could report on its own, so the schema is wrong
+ * before any source is looked at. One issue is produced per colliding leaf, in order of
+ * first appearance, each naming the other leaves that share its variable.
+ *
+ * @param bindings - Every leaf binding of a schema, from `resolveSourceNames`.
+ * @throws {BymaxConfigValidationError} When any variable is bound by more than one leaf.
+ */
+declare function assertDistinctVariables(bindings: ReadonlyArray<SourceBinding>): void;
+
+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 };

package/dist/internal/index.mjs

@@ -280,8 +280,29 @@ function detectUnknownKeys(prefixes, bindings, source) {
     (left, right) => Number(left.variable > right.variable) - Number(left.variable < right.variable)
   );
 }
+function assertDistinctVariables(bindings) {
+  const byVariable = /* @__PURE__ */ new Map();
+  for (const { path, variable } of bindings) {
+    byVariable.set(variable, [...byVariable.get(variable) ?? [], path]);
+  }
+  const issues = [];
+  for (const [variable, paths] of byVariable) {
+    if (paths.length < 2) continue;
+    for (const path of paths) {
+      const others = paths.filter((other) => other !== path).join(", ");
+      issues.push({
+        path,
+        variable,
+        code: ConfigErrorCode.INVALID,
+        message: `shares this variable with ${others}; rename one with meta({ env })`
+      });
+    }
+  }
+  if (issues.length > 0) throw new BymaxConfigValidationError(issues);
+}
 function validateEnv(schema, source, options) {
   const bindings = resolveSourceNames(schema);
+  assertDistinctVariables(bindings);
   const sourceMap = new Map(Object.entries(source));
   const namespaces = Object.keys(schema.shape);
   const candidate = buildCandidate(namespaces, collectPresentLeaves(bindings, sourceMap));
@@ -510,4 +531,4 @@ function defineEnv(shape) {
   return z.object(shape);
 }
 
-export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigValidationError, ConfigErrorCode, ConfigService, createValidatedConfig, defineEnv, resolveSourceNames };
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigValidationError, ConfigErrorCode, ConfigService, assertDistinctVariables, createValidatedConfig, defineEnv, resolveSourceNames };

package/dist/testing/index.cjs

@@ -200,6 +200,7 @@ function explainUnsatisfiedLeaves(error, overridden) {
   );
 }
 function prepareTestConfig(schema, overrides) {
+  internal.assertDistinctVariables(internal.resolveSourceNames(schema));
   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, createValidatedConfig, BymaxConfigValidationError, resolveSourceNames } from '@bymax-one/nest-config/internal';
+import { BymaxConfigModule, assertDistinctVariables, resolveSourceNames, createValidatedConfig, BymaxConfigValidationError } from '@bymax-one/nest-config/internal';
 
 // src/testing/create-test-config.ts
 var FILLER_CHARACTER = "a";
@@ -198,6 +198,7 @@ function explainUnsatisfiedLeaves(error, overridden) {
   );
 }
 function prepareTestConfig(schema, overrides) {
+  assertDistinctVariables(resolveSourceNames(schema));
   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.2",
+  "version": "1.2.3",
   "description": "Typed and validated environment configuration entry point for NestJS 11 applications, built on Zod v4.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",