`\n\nThe typed, injectable accessor over the frozen configuration object.\n\n| Method | Signature | Notes |\n| ----------- | ------------------------------------------------------------- | ------------------------------------------------ |\n| `get(path)` | `>(path: P) => PathValue` | Dot-path access, type inferred from the schema. |\n| `getAll()` | `() => Readonly` | The deep-frozen root object. |\n| `has(path)` | `(path: Path) => boolean` | True when the resolved value is not `undefined`. |\n\nBecause validation completed at bootstrap, `get` never throws for a declared\npath: every leaf either passed validation, received its default, or the\nprocess did not start.\n\n### `BymaxConfigValidationError` and `ConfigIssue`\n\n```typescript\nexport class BymaxConfigValidationError extends Error {\n public readonly code: ConfigValidationCode // 'BYMAX_CONFIG_VALIDATION'\n public readonly issues: ReadonlyArray\n}\n\nexport interface ConfigIssue {\n readonly path: string // e.g. \"database.url\"\n readonly variable: string // e.g. \"DATABASE_URL\"\n readonly code: ConfigIssueCode\n readonly message: string // constraint description, or your own `custom` message\n}\n```\n\n`ConfigErrorCode` is the frozen catalog backing `ConfigValidationCode` (the\nerror's own `code`) and `ConfigIssueCode` (each issue's `code`); see the\nerror catalog below for every value.\n\n### Reporting the failure\n\n`onValidationError` receives `ReadonlyArray` — four string fields per\nissue, JSON-serializable, with no error to unwrap. Every description this package\ngenerates is value-free, so it can go straight into a log as structured data. The\nexception is the one described above: a `custom` message written by your own schema\nis printed as written, so if one of yours interpolates a value, reviewing it before\nit reaches a log is the schema author's job, not this package's.\n\nIf you also log the thrown error from a bootstrap `catch`, how you pass it decides\nwhat survives. `code` and `issues` are the **only two own enumerable properties** of\n`BymaxConfigValidationError`; `name`, `message` and `stack` are non-enumerable, as\non any `Error`. That splits the outcome three ways — all three measured:\n\n| Which representation reaches the sink | The report (`message`) | `code` and `issues` |\n| ------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------- |\n| the error object, read by a serializer that extracts the standard fields **and** copies own enumerables | ✅ | ✅ |\n| `error.stack` | ✅ inside the string | ❌ |\n| `JSON.stringify(error)`, `{ ...error }` | ❌ | ✅ |\n\nRecognizing an `Error` is not enough on its own: extracting `name`, `message` and\n`stack` is what preserves the report, and copying the own enumerables is a separate\nstep that preserves `code` and `issues`. A serializer that does only the second is\nthe third row — `code` and `issues` and no report at all — so if you build the log\nrecord by hand, add `message` explicitly.\n\n**Which representation the sink sees is decided by your logging call, and that call\nis library-specific.** These are measured, not assumed:\n\n```typescript\nconsole.error('configuration invalid', error) // report, code and issues\npino.error({ err: error }, 'configuration invalid') // report, code and issues\npino.error('configuration invalid', error) // the error is dropped entirely\n\n// @bymax-one/nest-logger 1.2.6-1.2.9: wrap it, explicitly (see the note below)\nnestLogger.error('BOOT_FAILED', new Error('bootstrap failed', { cause: error }))\n```\n\nPino only applies error serialization when the error is the merging object or sits\nunder `err`; passed as a trailing argument it is treated as an interpolation value,\nand nothing about the failure reaches the entry.\n\n> [!NOTE]\n> **`@bymax-one/nest-logger` 1.2.6 through 1.2.9 dropped this error when it was logged\n> directly.** Its redactor left `_redactionFailed: true` and no `err` field at all —\n> no report, no `code`, no `issues`. The trigger was the definition rather than any\n> freezing: this error defines `code` and `issues` as non-writable, non-configurable\n> own properties, and the redactor's clone inherited those descriptors, so rewriting\n> the object-valued one with a walked copy failed. A locked scalar was unaffected,\n> which is why `code` alone never reproduced it.\n>\n> Fixed in **1.3.0**, measured rather than taken on report: a real failure logged\n> directly now arrives with `type, message, stack, code, issues`, the full issue array\n> and the report intact, and this error is left untouched. Measured affected: 1.2.6, 1.2.7\n> and 1.2.9 — 1.2.8 was never published, and on 1.2.2 and earlier this call shape does not\n> attach the error at all, so the defect does not arise there in this form. On an affected\n> version, wrap it — a `catch` receives this error unchanged, since the\n> module rethrows the instance it caught, so wrapping is an explicit\n> `new Error(message, { cause: error })` rather than a side effect of catching. A\n> lockfile pinned below 1.3.0 does not pick the fix up from an ordinary install, so the\n> update has to be deliberate.\n\nWrapping the error as the `cause` of an error you construct keeps all of it wherever the\nserializer walks the chain — measured against `@bymax-one/nest-logger` 1.2.7 and\n1.2.9, where a fifteen-issue report crosses the chain with `code`, every issue and\nthe full multi-line `message` intact.\n\nBefore any logger exists — which is where this failure usually lands, since a `catch`\nin `main.ts` runs before the logging module is registered — `console.error` is the\nreporter, and Node's inspector prints the stack and then appends the own enumerables.\nSo `console.error(message, error)` shows the report, the `code` and the expanded\n`issues` list, while `console.error(message, error.stack)` shows the report alone.\n\nLosing the machine-readable half is easy to miss precisely because the report keeps\narriving: `code` is what separates a configuration failure from any other boot\nfailure, and `issues` is what an alert or a dashboard keys on per variable.\n\n### Injection tokens\n\n`BYMAX_CONFIG` and `BYMAX_CONFIG_OPTIONS` are module-local `Symbol` tokens,\nexported for advanced factory-style wiring that needs the raw frozen config\nor the resolved options directly instead of going through `ConfigService`:\n\n```typescript\nimport { Inject, Injectable } from '@nestjs/common'\nimport { BYMAX_CONFIG } from '@bymax-one/nest-config'\nimport type { AppConfig } from './config/env.schema'\n\n@Injectable()\nexport class RawConfigConsumer {\n public constructor(@Inject(BYMAX_CONFIG) private readonly config: Readonly) {}\n}\n```\n\n### Type utilities\n\n`EnvSchema`, `EnvShape`, `EnvOutput`, `EnvLeaf`, and `EnvNamespace` type the\ntwo-level schema shape produced by `defineEnv`; `Path` and `PathValue`\nare the template-literal utilities behind `ConfigService.get`'s compile-time\ndot-path inference, limited to the two-level namespace convention. All five\nare exported for advanced generic code (custom decorators, typed wrappers)\nthat needs to reference the schema shape directly.\n\n## 🚨 Error Catalog\n\n| Code | Meaning |\n| -------------------------- | ------------------------------------------------------ |\n| `BYMAX_CONFIG_VALIDATION` | One or more schema violations (top-level error code). |\n| `BYMAX_CONFIG_MISSING` | Required variable absent from the source (issue code). |\n| `BYMAX_CONFIG_INVALID` | Present but failed its constraint (issue code). |\n| `BYMAX_CONFIG_UNKNOWN_KEY` | Strict mode: source variable matches no declared leaf. |\n\n## 🏗️ Architecture\n\n```\n process.env\n (or the record you inject)\n │\n ▼\n ┌───────────────────────────────────────┐\n │ defineEnv │\n │ namespaces at the top, Zod v4 leaves │\n └───────────────────┬───────────────────┘\n │\n ▼\n ┌───────────────────────────────────────┐\n │ createValidatedConfig │\n │ runs ONCE, at bootstrap, and │\n │ collects EVERY failure first │\n └─────────┬─────────────────┬───────────┘\n │ │\n all valid any invalid\n │ │\n ▼ ▼\n deep-frozen BymaxConfigValidationError\n BYMAX_CONFIG one aggregated boot-time report\n │ │\n ▼ ▼\n ConfigService the process does not start\n get('db.host') typed │\n from the schema itself no request is ever served\n │ with a missing secret\n ▼\n ┌─────────────────────────────┐\n │ ./testing │\n │ same pipeline, explicit │\n │ source — a test cannot │\n │ pass because a variable │\n │ happened to be set │\n └─────────────────────────────┘\n```\n\nValidation happens at bootstrap and nowhere else. There is no lazy read, no cache to\ninvalidate, and no path where a request-time lookup can discover that an environment\nvariable was missing — by then the process would already have refused to start.\n\n`./testing` builds the same validated object from an explicit record, so a test that\nneeds configuration does not need the application's real environment, and cannot\naccidentally pass because a variable happened to be set on the machine.\n\n### Design Principles\n\n| Principle | Description |\n| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 💥 **Refuse to start** | A misconfigured process is stopped before it serves a request, rather than discovering the gap at the first call that needs the value |\n| 🤐 **Value-free by contract** | `errors.ts`, `env-validator.ts` and `report-formatter.ts` each state it for themselves: a generated message carries the expected constraint and the schema's own options, never the received value |\n| 📋 **Report everything at once** | Validation collects every failure before throwing, so fixing an environment is one cycle instead of one per variable |\n| 🧊 **Frozen after validation** | Nothing in the running process rewrites configuration under a component that already read it |\n| 🔤 **The schema is the type** | Dot paths are checked against the schema at compile time, so a typo is a build error rather than a runtime `undefined` |\n| ⚙️ **Configuration over convention** | Everything goes through `forRoot`/`forRootAsync`. No file discovery, no magic paths, no hidden precedence rules |\n| 🧩 **One class identity** | The module and `./testing` import the shared runtime by package specifier, so `ConfigService` is one injection token in ESM and CommonJS alike |\n\n---\n\n## 🔐 Security Model\n\nConfiguration is where the secrets are, and a validation report is the one artifact\nguaranteed to be printed, logged, and pasted into an issue. That shapes the whole contract.\n\n### Errors are value-free by contract\n\nEvery message this library generates states the _expected_ constraint — the type, the\nallowed enum options taken from the schema, the bound — and never the received value.\n`env-validator` and `report-formatter` each say so in their own contracts, and\nproperty-based tests hold them to it. The messages you write yourself are the exception,\ncovered below.\n\n### The service does not serialize its configuration\n\n`ConfigService` keeps the validated root in an ECMAScript private field, so\n`JSON.stringify`, `Object.entries`, object spread and `util.inspect` cannot reach the\nvalues. Those are the paths taken by code that renders an injected provider it was handed\nincidentally — a logger formatting its arguments, an error reporter capturing the scope of\na throw. `toJSON` returns the declared namespace names, so the omission reads as deliberate\nrather than as an empty object. Reading on purpose is unaffected: `get`, `has` and the\n`getAll` escape hatch return the real values.\n\n### Failing fast is the security property\n\nA service that starts with a missing `JWT_SECRET` and discovers it at the first login is a\nservice that has already accepted traffic it cannot authenticate. The whole schema is\nvalidated before the application context finishes building, so a misconfigured deployment\ndoes not serve one request.\n\n### The validated object is frozen\n\nIt is deep-frozen before it enters the container, so nothing in the running process\nrewrites configuration under a component that already read it.\n\n### Nothing is read from anywhere but the source you name\n\n`process.env` by default, or the injectable record you provide. No file, no network, no\nremote provider — there is no path by which configuration arrives from somewhere you did\nnot choose.\n\n### Your own messages are yours\n\nValue-free applies to this library's reports. A `custom` issue from your own `.check`,\n`.refine` or `.superRefine` is printed as written — it is schema text, and it is the only\nplace a conditional or cross-field rule can state itself. That also means the message is\nyours to keep value-free: if it interpolates the received value, that value reaches the\nreport.\n\n---\n\n## 🛡️ Security Table\n\n| Layer | Implementation |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Error messages | Expected constraint only — type, schema-declared enum options, bounds; never the received value. A `custom` message from your own schema is the exception: it prints as written |\n| Failure mode | Refuse to start; the whole schema is validated before the context finishes building |\n| Aggregation | Every failure reported at once, so a fix cycle is one restart rather than one per variable |\n| Immutability | The validated result is frozen before it is provided |\n| Service state | The root lives in a private field; serializing the injected service yields namespace names only |\n| Sources | `process.env` only — no file, no network, no remote provider |\n| Type surface | Dot paths checked against the schema at compile time; a typo is a build error, not a runtime `undefined` |\n| Supply chain | `dependencies: {}`; third-party Actions pinned by commit SHA (org-internal reusables by tag); CodeQL and OpenSSF Scorecard |\n\n> [!IMPORTANT]\n> **Value-free applies to this library's own reports.** A `custom` message from your\n> schema's `.check`, `.refine` or `.superRefine` is printed as written — including a\n> value, if you interpolate one into it.\n\n---\n\n## 🧱 Tech Stack\n\n- **Runtime:** Node.js 24+\n- **Framework:** NestJS 11 (`ConfigurableModuleBuilder`, `@Global()`, `Symbol()` tokens)\n- **Validation:** Zod `^4` (peer) — the schema language, the coercion and the error source\n- **Build:** tsup — ESM + CJS per subpath, with `.d.ts` _and_ `.d.cts` declarations,\n and one shared `./internal` bundle so the module and its testing entry point hold\n a single class identity\n- **Tests:** Jest, including property-based tests over the report formatter + Stryker (mutation)\n- **TypeScript:** 5.x strict (`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`), zero `any`\n\n---\n\n## 🧪 Testing & Quality\n\nConfiguration decides whether a process may start at all, so the suite is held to a bar\nbeyond \"the tests pass\".\n\n- ✅ **100% line coverage** — statements, branches, functions and lines, enforced as a gate\n- ✅ **99.61% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at\n `break: 95`; ten provable equivalents carry their reason inline, and the one survivor left\n is an equivalent no directive can reach, so it stays counted rather than silenced\n ([report](./docs/mutation_testing_results.md))\n- ✅ **The value-free guarantee is tested, not assumed** — a sentinel secret is placed in a\n source and the assertion is that it appears nowhere in the rendered report or in the thrown\n error, because a guarantee about what is _absent_ is the one thing an ordinary assertion\n about output does not cover; the schema under test writes no `custom` message, so what is\n proven is the guarantee this package makes for its own generated text\n- ✅ **Published-artifact gates** — `check:exports` resolves the types the way each module\n system does, `check:runtime` loads every subpath from the packed tarball in ESM and\n CommonJS, and `check:published` compiles this README's snippets against `dist/`\n- ✅ **Every suppression carries its reason** — no coverage directives anywhere; each\n `// Stryker disable` in the production source names, after the `:` Stryker reads it from,\n why the mutant it silences is behaviour-preserving, and `check:mutants` proves those\n reasons parse so they reach the mutation report rather than the `Ignored using a comment`\n fallback\n\n```bash\npnpm test # unit suite\npnpm test:cov # unit suite with the 100% coverage gate\npnpm mutation # Stryker mutation testing (break: 95)\npnpm typecheck # tsc strict check\npnpm lint # ESLint\n```\n\n### Testing helpers\n\n`@bymax-one/nest-config/testing` removes every excuse for touching\n`process.env` in tests. `createTestConfig` synthesizes a complete valid\nsource from the schema (defaults where declared, deterministic placeholder\nvalues elsewhere), applies selective overrides, then runs the exact\nproduction pipeline (validate, freeze), so a test exercises the same code\npath a running application does.\n\n```typescript\nimport { createTestConfig } from '@bymax-one/nest-config/testing'\nimport { envSchema } from './config/env.schema'\n\nconst config = createTestConfig(envSchema, {\n database: { url: 'postgres://localhost:5432/test' }\n})\n```\n\n`configTestingModule` registers the production `BymaxConfigModule` with a\nsynthesized source, ready to drop into a Nest `TestingModule` graph:\n\n```typescript\nimport { Test } from '@nestjs/testing'\nimport { configTestingModule } from '@bymax-one/nest-config/testing'\nimport { envSchema } from './config/env.schema'\nimport { FeatureProvider } from './feature.provider'\n\nconst moduleRef = await Test.createTestingModule({\n imports: [configTestingModule(envSchema, { server: { port: 0 } })],\n providers: [FeatureProvider]\n}).compile()\n```\n\nPlaceholder synthesis never fabricates values that could accidentally pass a\nsecret-strength constraint; length and format constraints are honored. The\nsubpath has no Jest dependency and works with any runner, though the family\nstandard is Jest.\n\n## 🚫 Known Limitations\n\n1. **Two-level namespace convention.** The path-inference utilities\n (`Path`, `PathValue`) target `namespace.leaf` schemas. Deeper\n nesting validates correctly but is not covered by `get()` path inference;\n `getAll()` remains fully typed for arbitrary depth.\n2. **String-shaped sources only.** The source record is\n `Record` by design, the shape of a process\n environment. Structured sources must be serialized into that shape before\n validation.\n3. **No `.env` file loading.** Process environment population is the\n platform's job: Node's native `--env-file`, container orchestrators, or CI\n secrets. Bundling a loader would add a dependency and a second\n source-of-truth.\n4. **No multi-source precedence.** One source record per module\n registration. Precedence between layers (defaults, env, secrets) is the\n caller's composition (`{ ...a, ...b }`), kept explicit on purpose.\n5. **An open namespace cannot detect a typo in its own prefix.** A foreign\n variable and a misspelled local one are indistinguishable by name, so\n `meta({ open: true })` accepts both. See\n [Strict mode and shared prefixes](#strict-mode-and-shared-prefixes).\n\n## 🤝 Contributing\n\nPull requests are welcome. Please open an issue first for significant changes.\n\n- Read [`docs/technical_specification.md`](./docs/technical_specification.md) for architecture decisions.\n- Run the full gate listed in [`CONTRIBUTING.md`](./CONTRIBUTING.md) before opening a PR.\n- Conventional Commits are enforced by `commitlint.config.cjs`.\n\n---\n\n## 🔒 Security Policy\n\nIf you discover a security vulnerability, please **do not** open a public\nissue. Instead, email us at **support@bymax.one** with `[security]\n@bymax-one/nest-config` in the subject. We take security seriously and will\nrespond promptly. See [`SECURITY.md`](./SECURITY.md) for the full policy.\n\n---\n\n## 📄 License\n\n[MIT](./LICENSE) © [Bymax One](https://github.com/bymaxone)\n\n---\n\n\n Built with ❤️ by Bymax One\n
\n","readmeFilename":"README.md"}
![\"@bymax-one/nest-config\"](\"https://img.shields.io/badge/%40bymax--one-nest--config-000000?style=for-the-badge&logo=nestjs&logoColor=E0234E\"){kind=icon}
\n![\"npm](\"https://img.shields.io/npm/v/@bymax-one/nest-config?style=flat-square&colorA=000000&colorB=000000\")
![\"npm](\"https://img.shields.io/npm/dm/@bymax-one/nest-config?style=flat-square&colorA=000000&colorB=000000\")
![\"CI](\"https://img.shields.io/github/actions/workflow/status/bymaxone/nest-config/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI\")
![\"coverage\"](\"https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
![\"mutation](\"https://img.shields.io/badge/mutation-99.62%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
![\"license\"](\"https://img.shields.io/github/license/bymaxone/nest-config?style=flat-square&colorA=000000&colorB=000000\")
![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white\"){kind=icon}
![\"Node.js\"](\"https://img.shields.io/badge/Node.js-24%2B-339933?style=flat-square&logo=node.js&logoColor=white\"){kind=icon}