@bymax-one/nest-config 1.2.1 → 1.2.3

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, 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.
  * @param schema - A schema produced by `defineEnv`.
  * @returns The ordered list of leaf-to-variable bindings, typed `readonly`.
@@ -606,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

@@ -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, 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.
  * @param schema - A schema produced by `defineEnv`.
  * @returns The ordered list of leaf-to-variable bindings, typed `readonly`.
@@ -606,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

@@ -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) {
@@ -254,43 +280,74 @@ function detectUnknownKeys(prefixes, bindings, source) {
     (left, right) => Number(left.variable > right.variable) - Number(left.variable < right.variable)
   );
 }
+function assertDistinctVariables(bindings) {
+  const byVariable = /* @__PURE__ */ new Map();
+  for (const { path, variable } of bindings) {
+    byVariable.set(variable, [...byVariable.get(variable) ?? [], path]);
+  }
+  const issues = [];
+  for (const [variable, paths] of byVariable) {
+    if (paths.length < 2) continue;
+    for (const path of paths) {
+      const others = paths.filter((other) => other !== path).join(", ");
+      issues.push({
+        path,
+        variable,
+        code: ConfigErrorCode.INVALID,
+        message: `shares this variable with ${others}; rename one with meta({ env })`
+      });
+    }
+  }
+  if (issues.length > 0) throw new BymaxConfigValidationError(issues);
+}
 function validateEnv(schema, source, options) {
   const bindings = resolveSourceNames(schema);
+  assertDistinctVariables(bindings);
   const sourceMap = new Map(Object.entries(source));
   const namespaces = Object.keys(schema.shape);
   const candidate = buildCandidate(namespaces, collectPresentLeaves(bindings, sourceMap));
   const result = schema.safeParse(candidate);
-  const unknown = options?.strict === true ? detectUnknownKeys(resolveNamespacePrefixes(schema), bindings, sourceMap) : [];
+  const prefixes = resolveNamespacePrefixes(schema);
+  const unknown = options?.strict === true ? detectUnknownKeys(prefixes, bindings, sourceMap) : [];
   if (result.success) {
     if (unknown.length === 0) return result.data;
     throw new BymaxConfigValidationError(unknown);
   }
-  const issues = translateIssues(result.error.issues, bindings, sourceMap);
+  const issues = translateIssues(result.error.issues, bindings, prefixes, sourceMap);
   throw new BymaxConfigValidationError([...issues, ...unknown]);
 }
 
 // src/config.providers.ts
-function reportIssues(hook, issues) {
+async function reportIssues(hook, error) {
   if (hook === void 0) return;
   try {
-    hook(issues);
-  } catch {
+    await hook(error.issues);
+  } catch (hookError) {
+    Object.defineProperty(error, "cause", {
+      value: hookError,
+      enumerable: false,
+      writable: false,
+      configurable: false
+    });
   }
 }
 function createValidatedConfig(options) {
   const source = options.source ?? process.env;
+  return deepFreeze(validateEnv(options.schema, source, { strict: options.strict === true }));
+}
+async function provideValidatedConfig(options) {
   try {
-    return deepFreeze(validateEnv(options.schema, source, { strict: options.strict === true }));
+    return createValidatedConfig(options);
   } catch (error) {
     if (error instanceof BymaxConfigValidationError) {
-      reportIssues(options.onValidationError, error.issues);
+      await reportIssues(options.onValidationError, error);
     }
     throw error;
   }
 }
 var bymaxConfigProvider = {
   provide: BYMAX_CONFIG,
-  useFactory: createValidatedConfig,
+  useFactory: provideValidatedConfig,
   inject: [BYMAX_CONFIG_OPTIONS]
 };
 var _config, _leaves;
@@ -474,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

@@ -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,44 @@ 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) {
+  internal.assertDistinctVariables(internal.resolveSourceNames(schema));
+  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({