@bymax-one/nest-config 1.0.0

package/dist/internal/index.mjs

@@ -0,0 +1,415 @@
+import { ConfigurableModuleBuilder, Injectable, Inject, Module } from '@nestjs/common';
+import { z } from 'zod';
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/config.tokens.ts
+var BYMAX_CONFIG_OPTIONS = /* @__PURE__ */ Symbol("BYMAX_CONFIG_OPTIONS");
+var BYMAX_CONFIG = /* @__PURE__ */ Symbol("BYMAX_CONFIG");
+
+// src/config.module-definition.ts
+var { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = new ConfigurableModuleBuilder({
+  optionsInjectionToken: BYMAX_CONFIG_OPTIONS
+}).setClassMethodName("forRoot").setExtras({ isGlobal: true }, (definition, extras) => ({
+  ...definition,
+  global: extras.isGlobal
+})).build();
+
+// src/deep-freeze.ts
+function isFreezable(value) {
+  return typeof value === "object" && value !== null;
+}
+function deepFreeze(value) {
+  if (!isFreezable(value) || Object.isFrozen(value)) {
+    return value;
+  }
+  Object.freeze(value);
+  for (const nested of Object.values(value)) {
+    deepFreeze(nested);
+  }
+  return value;
+}
+
+// src/report-formatter.ts
+var REPORT_INDENT = "  ";
+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.";
+function pluralizeIssues(count) {
+  const noun = count === 1 ? "issue" : "issues";
+  return `${count} ${noun}`;
+}
+function computeColumnWidth(issues) {
+  let longest = MIN_VARIABLE_COLUMN;
+  for (const issue of issues) {
+    longest = Math.max(longest, issue.variable.length);
+  }
+  return longest + VARIABLE_GUTTER;
+}
+function formatIssueLine(issue, columnWidth) {
+  return `${REPORT_INDENT}${issue.variable.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");
+}
+
+// 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 a list of value-free 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({
+        path: issue.path,
+        variable: issue.variable,
+        code: issue.code,
+        message: issue.message
+      })
+    );
+    super(formatIssueReport(normalized));
+    /** The stable top-level error code. */
+    this.code = ConfigErrorCode.VALIDATION;
+    Object.defineProperty(this, "name", {
+      value: "BymaxConfigValidationError",
+      enumerable: false,
+      writable: false,
+      configurable: false
+    });
+    this.issues = Object.freeze(normalized);
+    Object.setPrototypeOf(this, _BymaxConfigValidationError.prototype);
+    Object.defineProperty(this, "code", { writable: false, configurable: false });
+    Object.defineProperty(this, "issues", { writable: false, configurable: false });
+  }
+};
+
+// 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();
+}
+function readEnvOverride(leaf) {
+  const override = leaf.meta()?.env;
+  return typeof override === "string" && override.length > 0 ? override : void 0;
+}
+function deriveVariable(namespace, leafKey) {
+  return `${toScreamingSnake(namespace)}_${toScreamingSnake(leafKey)}`;
+}
+function resolveSourceNames(schema) {
+  return Object.entries(schema.shape).flatMap(
+    ([namespace, namespaceSchema]) => Object.entries(namespaceSchema.shape).map(([leafKey, leafSchema]) => ({
+      path: `${namespace}.${leafKey}`,
+      variable: readEnvOverride(leafSchema) ?? deriveVariable(namespace, leafKey)
+    }))
+  );
+}
+function resolveNamespacePrefixes(schema) {
+  return Object.keys(schema.shape).map((namespace) => ({
+    namespace,
+    prefix: `${toScreamingSnake(namespace)}_`
+  }));
+}
+
+// src/env-validator.ts
+var UNKNOWN_KEY_MESSAGE = "unknown variable not declared in the schema";
+var MISSING_MESSAGE = "missing required value";
+function collectPresentLeaves(bindings, source) {
+  const present = [];
+  for (const binding of bindings) {
+    const value = source.get(binding.variable);
+    if (value === void 0) continue;
+    const separator = binding.path.indexOf(".");
+    present.push({
+      namespace: binding.path.slice(0, separator),
+      leaf: binding.path.slice(separator + 1),
+      value
+    });
+  }
+  return present;
+}
+function buildCandidate(namespaces, present) {
+  return Object.fromEntries(
+    namespaces.map((namespace) => [
+      namespace,
+      Object.fromEntries(
+        present.filter((leaf) => leaf.namespace === namespace).map((leaf) => [leaf.leaf, leaf.value])
+      )
+    ])
+  );
+}
+function formatEnumValues(values) {
+  return values.map(String).join(", ");
+}
+function describeConstraint(issue) {
+  switch (issue.code) {
+    case "invalid_type":
+      return `invalid value (expected: ${issue.expected})`;
+    case "invalid_format":
+      return `invalid format (expected: ${issue.format})`;
+    case "invalid_value":
+      return `invalid value (expected one of: ${formatEnumValues(issue.values)})`;
+    case "too_small":
+      return issue.origin === "string" ? `too short (expected: string, minimum ${issue.minimum} characters)` : `out of range (expected: ${issue.origin} >= ${issue.minimum})`;
+    case "too_big":
+      return issue.origin === "string" ? `too long (expected: string, maximum ${issue.maximum} characters)` : `out of range (expected: ${issue.origin} <= ${issue.maximum})`;
+    default:
+      return "invalid value";
+  }
+}
+function toConfigIssue(binding, issue, source) {
+  const isMissing = source.get(binding.variable) === void 0;
+  return {
+    path: binding.path,
+    variable: binding.variable,
+    code: isMissing ? ConfigErrorCode.MISSING : ConfigErrorCode.INVALID,
+    message: isMissing ? MISSING_MESSAGE : describeConstraint(issue)
+  };
+}
+function translateIssues(zodIssues, bindings, source) {
+  const issueByPath = /* @__PURE__ */ new Map();
+  for (const issue of zodIssues) {
+    const path = issue.path.slice(0, 2).join(".");
+    if (!issueByPath.has(path)) {
+      issueByPath.set(path, issue);
+    }
+  }
+  const result = [];
+  for (const binding of bindings) {
+    const issue = issueByPath.get(binding.path);
+    if (issue === void 0) continue;
+    result.push(toConfigIssue(binding, issue, source));
+  }
+  return result;
+}
+function longestMatchingPrefix(prefixes, key) {
+  let match;
+  for (const entry of prefixes) {
+    if (!key.startsWith(entry.prefix)) continue;
+    if (match === void 0 || entry.prefix.length > match.prefix.length) {
+      match = entry;
+    }
+  }
+  return match;
+}
+function detectUnknownKeys(prefixes, bindings, source) {
+  const declared = new Set(bindings.map((binding) => binding.variable));
+  const issues = [];
+  for (const key of source.keys()) {
+    if (declared.has(key)) continue;
+    if (source.get(key) === void 0) continue;
+    const match = longestMatchingPrefix(prefixes, key);
+    if (match === void 0) continue;
+    issues.push({
+      path: match.namespace,
+      variable: key,
+      code: ConfigErrorCode.UNKNOWN_KEY,
+      message: UNKNOWN_KEY_MESSAGE
+    });
+  }
+  return issues.sort(
+    (left, right) => Number(left.variable > right.variable) - Number(left.variable < right.variable)
+  );
+}
+function validateEnv(schema, source, options) {
+  const bindings = resolveSourceNames(schema);
+  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) : [];
+  if (result.success) {
+    if (unknown.length === 0) return result.data;
+    throw new BymaxConfigValidationError(unknown);
+  }
+  const issues = translateIssues(result.error.issues, bindings, sourceMap);
+  throw new BymaxConfigValidationError([...issues, ...unknown]);
+}
+
+// src/config.providers.ts
+function reportIssues(hook, issues) {
+  if (hook === void 0) return;
+  try {
+    hook(issues);
+  } catch {
+  }
+}
+function createValidatedConfig(options) {
+  const source = options.source ?? process.env;
+  try {
+    return deepFreeze(validateEnv(options.schema, source, { strict: options.strict === true }));
+  } catch (error) {
+    if (error instanceof BymaxConfigValidationError) {
+      reportIssues(options.onValidationError, error.issues);
+    }
+    throw error;
+  }
+}
+var bymaxConfigProvider = {
+  provide: BYMAX_CONFIG,
+  useFactory: createValidatedConfig,
+  inject: [BYMAX_CONFIG_OPTIONS]
+};
+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) {
+    this.config = config;
+    const leaves = /* @__PURE__ */ new Map();
+    for (const [namespace, value] of Object.entries(config)) {
+      for (const [leaf, leafValue] of Object.entries(value)) {
+        leaves.set(`${namespace}.${leaf}`, leafValue);
+      }
+    }
+    this.leaves = leaves;
+  }
+  /**
+   * 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 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 this.leaves.get(String(path));
+  }
+};
+ConfigService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(BYMAX_CONFIG))
+], ConfigService);
+
+// src/config.module.ts
+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,
+      providers: appendTo(definition.providers, bymaxConfigProvider, ConfigService),
+      exports: appendTo(definition.exports, BYMAX_CONFIG, ConfigService)
+    };
+  }
+};
+BymaxConfigModule = __decorateClass([
+  Module({})
+], BymaxConfigModule);
+function defineEnv(shape) {
+  return z.object(shape);
+}
+
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigValidationError, ConfigErrorCode, ConfigService, createValidatedConfig, defineEnv, resolveSourceNames };

package/dist/testing/index.cjs

@@ -0,0 +1,171 @@
+'use strict';
+
+var internal = require('@bymax-one/nest-config/internal');
+
+// src/testing/create-test-config.ts
+var FILLER_CHARACTER = "a";
+var PLACEHOLDER_URL = "https://placeholder.local";
+var PLACEHOLDER_EMAIL_DOMAIN = "@placeholder.local";
+var DEFAULT_NUMBER = 1;
+var DEFAULT_STRING_LENGTH = 1;
+var PLACEHOLDER_BOOLEAN = "true";
+function readDef(leaf) {
+  return leaf._zod.def;
+}
+function checksOf(def) {
+  return def.checks ?? [];
+}
+function readStringLengths(def) {
+  let min = 0;
+  let max = Number.POSITIVE_INFINITY;
+  let exact;
+  for (const wrapper of checksOf(def)) {
+    const check = wrapper._zod.def;
+    if (check.check === "min_length") min = check.minimum;
+    if (check.check === "max_length") max = check.maximum;
+    if (check.check === "length_equals") exact = check.length;
+  }
+  return exact === void 0 ? { min, max } : { min, max, exact };
+}
+var URL_PREFIX = "http://";
+var EMAIL_SUFFIX = "@a.lo";
+function clampLength(preferred, min, max) {
+  return Math.min(Math.max(preferred, min), max);
+}
+function urlOfLength(target) {
+  const hostFill = Math.max(target - URL_PREFIX.length, 1);
+  return `${URL_PREFIX}${FILLER_CHARACTER.repeat(hostFill)}`;
+}
+function emailOfLength(target) {
+  const localFill = Math.max(target - EMAIL_SUFFIX.length, 1);
+  return `${FILLER_CHARACTER.repeat(localFill)}${EMAIL_SUFFIX}`;
+}
+function synthesizeUrl(lengths) {
+  if (lengths.exact === void 0 && PLACEHOLDER_URL.length >= lengths.min && PLACEHOLDER_URL.length <= lengths.max) {
+    return PLACEHOLDER_URL;
+  }
+  return urlOfLength(lengths.exact ?? clampLength(PLACEHOLDER_URL.length, lengths.min, lengths.max));
+}
+function synthesizeEmail(lengths) {
+  const canonical = `${FILLER_CHARACTER}${PLACEHOLDER_EMAIL_DOMAIN}`;
+  if (lengths.exact === void 0 && canonical.length >= lengths.min && canonical.length <= lengths.max) {
+    return canonical;
+  }
+  return emailOfLength(lengths.exact ?? clampLength(canonical.length, lengths.min, lengths.max));
+}
+function synthesizePlainString(lengths) {
+  if (lengths.exact !== void 0) return FILLER_CHARACTER.repeat(lengths.exact);
+  const target = Math.max(lengths.min, DEFAULT_STRING_LENGTH);
+  const bounded = target > lengths.max ? lengths.max : target;
+  return FILLER_CHARACTER.repeat(bounded);
+}
+function synthesizeString(def) {
+  const lengths = readStringLengths(def);
+  if (def.format === "url") return synthesizeUrl(lengths);
+  if (def.format === "email") return synthesizeEmail(lengths);
+  return synthesizePlainString(lengths);
+}
+function selectNumber(bounds) {
+  const { lower, upper, integer } = bounds;
+  if (lower !== void 0 && upper !== void 0) {
+    if (integer) {
+      const lo = bounds.lowerExclusive ? Math.floor(lower) + 1 : Math.ceil(lower);
+      const hi = bounds.upperExclusive ? Math.ceil(upper) - 1 : Math.floor(upper);
+      return Math.floor((lo + hi) / 2);
+    }
+    return (lower + upper) / 2;
+  }
+  if (lower !== void 0) return bounds.lowerExclusive ? lower + (integer ? 1 : 0.5) : lower;
+  if (upper !== void 0) return bounds.upperExclusive ? upper - (integer ? 1 : 0.5) : upper;
+  return DEFAULT_NUMBER;
+}
+function synthesizeNumber(def) {
+  const bounds = { lowerExclusive: false, upperExclusive: false, integer: false };
+  for (const wrapper of checksOf(def)) {
+    const check = wrapper._zod.def;
+    if (check.check === "greater_than") {
+      bounds.lower = check.value;
+      bounds.lowerExclusive = check.inclusive !== true;
+    }
+    if (check.check === "less_than") {
+      bounds.upper = check.value;
+      bounds.upperExclusive = check.inclusive !== true;
+    }
+    if (check.check === "number_format") bounds.integer = true;
+  }
+  return String(selectNumber(bounds));
+}
+function synthesizeEnum(def) {
+  const [first] = Object.values(def.entries);
+  return String(first);
+}
+function synthesizeLeaf(leaf) {
+  const def = readDef(leaf);
+  switch (def.type) {
+    case "default":
+    case "optional":
+      return void 0;
+    case "nullable":
+      return synthesizeLeaf(def.innerType);
+    case "string":
+      return synthesizeString(def);
+    case "number":
+      return synthesizeNumber(def);
+    case "boolean":
+      return PLACEHOLDER_BOOLEAN;
+    case "enum":
+      return synthesizeEnum(def);
+    default:
+      return FILLER_CHARACTER;
+  }
+}
+function synthesizePlaceholderSource(schema) {
+  const valueByPath = /* @__PURE__ */ new Map();
+  for (const [namespace, namespaceSchema] of Object.entries(schema.shape)) {
+    for (const [leafKey, leafSchema] of Object.entries(namespaceSchema.shape)) {
+      const value = synthesizeLeaf(leafSchema);
+      if (value !== void 0) valueByPath.set(`${namespace}.${leafKey}`, value);
+    }
+  }
+  const source = /* @__PURE__ */ Object.create(null);
+  for (const binding of internal.resolveSourceNames(schema)) {
+    const value = valueByPath.get(binding.path);
+    if (value !== void 0) source[binding.variable] = value;
+  }
+  return source;
+}
+
+// src/testing/create-test-config.ts
+function flattenOverrides(overrides) {
+  const flat = /* @__PURE__ */ new Map();
+  for (const [namespace, leaves] of Object.entries(overrides)) {
+    for (const [leaf, value] of Object.entries(leaves)) {
+      flat.set(`${namespace}.${leaf}`, value);
+    }
+  }
+  return flat;
+}
+function applyOverrides(schema, base, overrides) {
+  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));
+  }
+  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 createTestConfig(schema, overrides) {
+  return internal.createValidatedConfig({ schema, source: buildTestSource(schema, overrides) });
+}
+function configTestingModule(schema, overrides) {
+  const source = buildTestSource(schema, overrides);
+  return internal.BymaxConfigModule.forRoot({ schema, source });
+}
+
+exports.configTestingModule = configTestingModule;
+exports.createTestConfig = createTestConfig;

package/dist/testing/index.d.cts

@@ -0,0 +1,88 @@
+import { EnvShape, EnvOutput, EnvSchema } from '@bymax-one/nest-config/internal';
+import { DynamicModule } from '@nestjs/common';
+
+/**
+ * @fileoverview createTestConfig: the public test-config builder of the testing
+ * subpath. It synthesizes a complete valid source from a `defineEnv` schema,
+ * overlays selective nested partial overrides onto the targeted leaves through
+ * the shared source mapping, then runs the exact production pipeline (validate,
+ * deep-freeze) so a test exercises the same code path a running app does. An
+ * override that violates a declared constraint fails through the production
+ * validation error, and the returned configuration is deeply immutable. No
+ * `process.env` is ever read.
+ * @layer Utility
+ */
+
+/**
+ * Selective nested partial overrides for a synthesized test configuration.
+ *
+ * Mirrors the two-level `namespace.leaf` shape of the inferred configuration,
+ * with every namespace and leaf optional, so a test pins only the values it
+ * cares about and lets synthesis and schema defaults resolve the rest.
+ *
+ * @typeParam TShape - The two-level schema shape.
+ */
+type ConfigOverrides<TShape extends EnvShape> = {
+    readonly [Namespace in keyof EnvOutput<TShape>]?: {
+        readonly [Leaf in keyof EnvOutput<TShape>[Namespace]]?: EnvOutput<TShape>[Namespace][Leaf];
+    };
+};
+/**
+ * Build a validated, frozen test configuration from a schema and overrides.
+ *
+ * Synthesizes a complete constraint-compliant source, applies the selective
+ * overrides, and runs the production validation and deep-freeze pipeline, so the
+ * returned object is exactly what a running application would receive. A test
+ * never touches `process.env`, yet an override that breaks a declared constraint
+ * still throws the production {@link BymaxConfigValidationError}.
+ *
+ * @typeParam TShape - The two-level schema shape.
+ * @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.
+ * @example
+ * ```typescript
+ * const config = createTestConfig(envSchema, {
+ *   database: { url: 'postgres://localhost:5432/test' },
+ * });
+ * config.database.url; // typed, validated, frozen
+ * ```
+ */
+declare function createTestConfig<TShape extends EnvShape>(schema: EnvSchema<TShape>, overrides?: ConfigOverrides<TShape>): Readonly<EnvOutput<TShape>>;
+
+/**
+ * @fileoverview configTestingModule: a thin testing wrapper that registers the
+ * production BymaxConfigModule with a fully synthesized (and optionally
+ * overridden) source. It delegates to `BymaxConfigModule.forRoot`, so a Nest
+ * `TestingModule` graph exercises the exact production registration path, the
+ * same validation, freezing, and provider wiring an application boots with,
+ * without touching `process.env`. This is the module-shaped counterpart to
+ * `createTestConfig`.
+ * @layer Module
+ */
+
+/**
+ * Build an importable testing module preconfigured with a synthesized source.
+ *
+ * Synthesizes a complete valid source for the schema, applies the selective
+ * overrides, and registers the production {@link BymaxConfigModule} with it, so
+ * the returned module provides and exports the frozen `BYMAX_CONFIG` and the
+ * typed `ConfigService` exactly as in production. Import it into a Nest
+ * `TestingModule` to inject configuration without a process environment.
+ *
+ * @typeParam TShape - The two-level schema shape.
+ * @param schema - A schema produced by `defineEnv`.
+ * @param overrides - Optional selective nested partial overrides.
+ * @returns A dynamic module registered through the production `forRoot` path.
+ * @example
+ * ```typescript
+ * const moduleRef = await Test.createTestingModule({
+ *   imports: [configTestingModule(envSchema, { server: { port: 0 } })],
+ *   providers: [InvoiceService],
+ * }).compile();
+ * ```
+ */
+declare function configTestingModule<TShape extends EnvShape>(schema: EnvSchema<TShape>, overrides?: ConfigOverrides<TShape>): DynamicModule;
+
+export { configTestingModule, createTestConfig };