@bymax-one/nest-config 1.2.0 → 1.2.2

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({