@bymax-one/nest-config 1.0.0

package/dist/testing/index.d.ts

@@ -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 };

package/dist/testing/index.mjs

@@ -0,0 +1,168 @@
+import { createValidatedConfig, BymaxConfigModule, resolveSourceNames } from '@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 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 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 createValidatedConfig({ schema, source: buildTestSource(schema, overrides) });
+}
+function configTestingModule(schema, overrides) {
+  const source = buildTestSource(schema, overrides);
+  return BymaxConfigModule.forRoot({ schema, source });
+}
+
+export { configTestingModule, createTestConfig };

package/package.json

@@ -0,0 +1,161 @@
+{
+  "name": "@bymax-one/nest-config",
+  "version": "1.0.0",
+  "description": "Typed and validated environment configuration entry point for NestJS 11 applications, built on Zod v4.",
+  "author": "Bymax One <support@bymax.one>",
+  "license": "MIT",
+  "homepage": "https://github.com/bymaxone/nest-config#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bymaxone/nest-config.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bymaxone/nest-config/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./testing": {
+      "import": {
+        "types": "./dist/testing/index.d.ts",
+        "default": "./dist/testing/index.mjs"
+      },
+      "require": {
+        "types": "./dist/testing/index.d.cts",
+        "default": "./dist/testing/index.cjs"
+      }
+    },
+    "./internal": {
+      "import": {
+        "types": "./dist/internal/index.d.ts",
+        "default": "./dist/internal/index.mjs"
+      },
+      "require": {
+        "types": "./dist/internal/index.d.cts",
+        "default": "./dist/internal/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,mjs,cjs}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.16",
+    "@nestjs/core": "^11.1.18",
+    "reflect-metadata": "^0.2.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@commitlint/cli": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
+    "@eslint/js": "^9.39.4",
+    "@nestjs/common": "^11.1.20",
+    "@nestjs/core": "^11.1.20",
+    "@nestjs/platform-express": "^11.1.20",
+    "@nestjs/testing": "^11.1.20",
+    "@stryker-mutator/core": "^9",
+    "@stryker-mutator/jest-runner": "^9",
+    "@stryker-mutator/typescript-checker": "^9",
+    "@types/express": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25",
+    "@typescript-eslint/eslint-plugin": "^8.59.3",
+    "@typescript-eslint/parser": "^8.59.3",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-security": "^4.0.0",
+    "globals": "^17.6.0",
+    "husky": "^9.1.7",
+    "jest": "^30.4.2",
+    "lint-staged": "^17.0.7",
+    "prettier": "^3.8.3",
+    "reflect-metadata": "^0.2.2",
+    "ts-jest": "^29.4.9",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "zod": "^4.0.0"
+  },
+  "keywords": [
+    "nestjs",
+    "config",
+    "environment",
+    "env",
+    "zod",
+    "validation",
+    "typed-config",
+    "dependency-injection",
+    "fail-fast",
+    "configuration"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "typesVersions": {
+    "*": {
+      "testing": [
+        "./dist/testing/index.d.cts"
+      ],
+      "internal": [
+        "./dist/internal/index.d.cts"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "pnpm clean && tsup",
+    "check:exports": "attw --pack . --profile strict",
+    "check:published": "node scripts/check-published-surface.mjs",
+    "check:runtime": "node scripts/check-consumer-runtime.mjs",
+    "clean": "node -e \"const fs=require('node:fs');for(const d of ['dist','coverage'])fs.rmSync(d,{recursive:true,force:true})\"",
+    "dogfood": "node scripts/dogfood-smoke-test.mjs",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "mutation": "stryker run",
+    "mutation:dry-run": "stryker run --dryRunOnly",
+    "mutation:incremental": "stryker run --incremental",
+    "release": "npm publish --provenance --access public",
+    "size": "node scripts/check-size.mjs",
+    "test": "jest",
+    "test:cov": "jest --coverage",
+    "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
+    "test:e2e": "jest --config jest.e2e.config.ts",
+    "test:watch": "jest --watch",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.build.json"
+  }
+}