@bymax-one/nest-config 1.2.4 → 1.2.5

package/CHANGELOG.md

@@ -11,6 +11,35 @@ as the GitHub Release body, so each released version needs a matching
 
 ## [Unreleased]
 
+## [1.2.5] - 2026-11-01
+
+### Fixed
+
+- **A test override that is not a plain object is one issue.** A namespace given `null` threw a raw
+  `TypeError`, an array produced one issue per index, a `Map` or a `Date` applied
+  nothing and said nothing, and a class instance had its own fields read as overrides. `createTestConfig` and `configTestingModule` now report each of them once,
+  by name, as "the override for `x` must be an object", in the same `BymaxConfigValidationError` as any
+  unmatched path. The overrides argument itself is held to the same rule and reported as "the overrides
+  must be an object"; `undefined` and `null` still mean no overrides.
+
+  #### Apply to a derived backend
+
+  Run the test suites. A test that expected a `TypeError` for a `null` namespace now receives a
+  `BymaxConfigValidationError`. A namespace override given as a class instance was applied field by
+  field; it is now refused, so pass a plain object. A `Map` or a `Date` as a namespace override was
+  ignored; it is now refused too.
+
+### Changed
+
+- **The shipped bundles no longer carry comments.** The build runs `scripts/strip-bundle-comments.mjs`
+  after `tsup`: every comment is removed from `index.mjs` and `index.cjs` except the legal,
+  bundler-annotation and region-marker ones the script keeps, and the script proves with the
+  TypeScript parser that it changed no code. The documentation people read
+  comes from the `.d.ts` files, which are untouched. The internal bundle goes from 22,079 to 16,652
+  bytes and the package from 68.3 to 65.5 kB. Nothing to apply in a derived backend.
+- **The internal bundle has a size budget.** `scripts/check-size.mjs` gates `dist/internal/index.mjs`,
+  which carries nearly all of the code, at 4.6 KiB brotli. Tooling only.
+
 ## [1.2.4] - 2026-11-01
 
 ### Fixed
@@ -556,4 +585,5 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.2.2]: https://github.com/bymaxone/nest-config/compare/v1.2.1...v1.2.2
 [1.2.3]: https://github.com/bymaxone/nest-config/compare/v1.2.2...v1.2.3
 [1.2.4]: https://github.com/bymaxone/nest-config/compare/v1.2.3...v1.2.4
-[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.2.4...HEAD
+[1.2.5]: https://github.com/bymaxone/nest-config/compare/v1.2.4...v1.2.5
+[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.2.5...HEAD

package/README.md

@@ -913,7 +913,8 @@ Overrides mirror the `namespace.leaf` shape with every key optional and typed fr
 a leaf what its environment variable would hold; an object becomes `'[object Object]'`, and an override
 of `undefined` is ignored, so a defaulted leaf cannot be unset. An override whose path matches no leaf
 of the schema throws, listing every such path, even when its value is `undefined`; a namespace given
-something other than an object is reported once, by name. Neither helper takes `strict`, a
+something other than a plain object is reported once, by name, and so is an overrides argument that is
+not a plain object; passing `undefined` or `null` for the whole argument means no overrides. Neither helper takes `strict`, a
 custom `source`, a hook or `isGlobal`: `configTestingModule` registers the module globally, and a
 failure case (a missing variable, a strict violation) is built with
 `BymaxConfigModule.forRoot({ schema, source, strict: true })` and a source you write.

package/dist/internal/index.cjs

@@ -81,22 +81,12 @@ function formatIssueReport(issues) {
 
 // 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 the collected 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({
@@ -107,7 +97,6 @@ var BymaxConfigValidationError = class _BymaxConfigValidationError extends Error
       })
     );
     super(formatIssueReport(normalized));
-    /** The stable top-level error code. */
     this.code = ConfigErrorCode.VALIDATION;
     Object.defineProperty(this, "name", {
       value: "BymaxConfigValidationError",
@@ -404,35 +393,8 @@ var bymaxConfigProvider = {
 };
 var _config, _leaves;
 exports.ConfigService = class ConfigService {
-  /**
-   * 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) {
-    /**
-     * The frozen configuration root.
-     *
-     * Held in an ECMAScript private field rather than a TypeScript `private`
-     * property: `private` is erased at runtime, leaving an enumerable own
-     * property that `JSON.stringify`, `Object.entries`, object spread and
-     * `util.inspect` all walk into. This object aggregates every secret the
-     * application declared, so any code that incidentally serializes the
-     * injected service — a logger that renders its arguments, an observability
-     * SDK capturing the scope of a thrown error, a stray `console.log` — would
-     * emit them in plaintext. A `#` field is unreachable to all of those.
-     */
     __privateAdd(this, _config);
-    /**
-     * Precomputed `namespace.leaf` to value lookup, built once at construction.
-     *
-     * An ECMAScript private field for the same reason as the config root: it
-     * holds the same values, flattened.
-     */
     __privateAdd(this, _leaves);
     __privateSet(this, _config, config);
     const leaves = /* @__PURE__ */ new Map();
@@ -443,86 +405,21 @@ exports.ConfigService = class ConfigService {
     }
     __privateSet(this, _leaves, leaves);
   }
-  /**
-   * Describe the service for serialization without disclosing any value.
-   *
-   * `JSON.stringify` on an instance would otherwise yield `{}`, which reads as
-   * a bug rather than as a deliberate omission. Returning the namespace names
-   * keeps the output useful for debugging while the values stay unreachable.
-   *
-   * @returns The declared namespace names, never their contents.
-   * @example
-   * ```typescript
-   * JSON.stringify(config); // {"service":"ConfigService","namespaces":["server","database"]}
-   * ```
-   */
   toJSON() {
     return {
       service: "ConfigService",
       namespaces: Object.keys(__privateGet(this, _config))
     };
   }
-  /**
-   * 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 __privateGet(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 __privateGet(this, _leaves).get(String(path));
   }
@@ -539,35 +436,12 @@ function appendTo(list, ...items) {
   return list === void 0 ? [...items] : [...list, ...items];
 }
 exports.BymaxConfigModule = class BymaxConfigModule 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 exports.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 exports.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,

package/dist/internal/index.mjs

@@ -79,22 +79,12 @@ function formatIssueReport(issues) {
 
 // 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 the collected 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({
@@ -105,7 +95,6 @@ var BymaxConfigValidationError = class _BymaxConfigValidationError extends Error
       })
     );
     super(formatIssueReport(normalized));
-    /** The stable top-level error code. */
     this.code = ConfigErrorCode.VALIDATION;
     Object.defineProperty(this, "name", {
       value: "BymaxConfigValidationError",
@@ -402,35 +391,8 @@ var bymaxConfigProvider = {
 };
 var _config, _leaves;
 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) {
-    /**
-     * The frozen configuration root.
-     *
-     * Held in an ECMAScript private field rather than a TypeScript `private`
-     * property: `private` is erased at runtime, leaving an enumerable own
-     * property that `JSON.stringify`, `Object.entries`, object spread and
-     * `util.inspect` all walk into. This object aggregates every secret the
-     * application declared, so any code that incidentally serializes the
-     * injected service — a logger that renders its arguments, an observability
-     * SDK capturing the scope of a thrown error, a stray `console.log` — would
-     * emit them in plaintext. A `#` field is unreachable to all of those.
-     */
     __privateAdd(this, _config);
-    /**
-     * Precomputed `namespace.leaf` to value lookup, built once at construction.
-     *
-     * An ECMAScript private field for the same reason as the config root: it
-     * holds the same values, flattened.
-     */
     __privateAdd(this, _leaves);
     __privateSet(this, _config, config);
     const leaves = /* @__PURE__ */ new Map();
@@ -441,86 +403,21 @@ var ConfigService = class {
     }
     __privateSet(this, _leaves, leaves);
   }
-  /**
-   * Describe the service for serialization without disclosing any value.
-   *
-   * `JSON.stringify` on an instance would otherwise yield `{}`, which reads as
-   * a bug rather than as a deliberate omission. Returning the namespace names
-   * keeps the output useful for debugging while the values stay unreachable.
-   *
-   * @returns The declared namespace names, never their contents.
-   * @example
-   * ```typescript
-   * JSON.stringify(config); // {"service":"ConfigService","namespaces":["server","database"]}
-   * ```
-   */
   toJSON() {
     return {
       service: "ConfigService",
       namespaces: Object.keys(__privateGet(this, _config))
     };
   }
-  /**
-   * 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 __privateGet(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 __privateGet(this, _leaves).get(String(path));
   }
@@ -537,35 +434,12 @@ 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,

package/dist/testing/index.cjs

@@ -167,14 +167,26 @@ function synthesizePlaceholderSource(schema) {
 }
 
 // src/testing/create-test-config.ts
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
 function unplacedIssue(path, code, message) {
   return { path, variable: "", code, message };
 }
 function flattenOverrides(overrides, declared) {
   const flat = /* @__PURE__ */ new Map();
   const unplaced = [];
+  if (overrides === void 0 || overrides === null) return { flat, unplaced };
+  if (!isPlainObject(overrides)) {
+    unplaced.push(
+      unplacedIssue("(overrides)", internal.ConfigErrorCode.INVALID, "the overrides must be an object")
+    );
+    return { flat, unplaced };
+  }
   for (const [namespace, leaves] of Object.entries(overrides)) {
-    if (typeof leaves !== "object") {
+    if (!isPlainObject(leaves)) {
       unplaced.push(
         unplacedIssue(
           namespace,
@@ -204,7 +216,7 @@ function flattenOverrides(overrides, declared) {
 function applyOverrides(schema, base, overrides, overridden) {
   const bindings = internal.resolveSourceNames(schema);
   const { flat, unplaced } = flattenOverrides(
-    overrides ?? {},
+    overrides,
     new Set(bindings.map((binding) => binding.path))
   );
   if (unplaced.length > 0) throw new internal.BymaxConfigValidationError(unplaced);

package/dist/testing/index.mjs

@@ -165,14 +165,26 @@ function synthesizePlaceholderSource(schema) {
 }
 
 // src/testing/create-test-config.ts
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
 function unplacedIssue(path, code, message) {
   return { path, variable: "", code, message };
 }
 function flattenOverrides(overrides, declared) {
   const flat = /* @__PURE__ */ new Map();
   const unplaced = [];
+  if (overrides === void 0 || overrides === null) return { flat, unplaced };
+  if (!isPlainObject(overrides)) {
+    unplaced.push(
+      unplacedIssue("(overrides)", ConfigErrorCode.INVALID, "the overrides must be an object")
+    );
+    return { flat, unplaced };
+  }
   for (const [namespace, leaves] of Object.entries(overrides)) {
-    if (typeof leaves !== "object") {
+    if (!isPlainObject(leaves)) {
       unplaced.push(
         unplacedIssue(
           namespace,
@@ -202,7 +214,7 @@ function flattenOverrides(overrides, declared) {
 function applyOverrides(schema, base, overrides, overridden) {
   const bindings = resolveSourceNames(schema);
   const { flat, unplaced } = flattenOverrides(
-    overrides ?? {},
+    overrides,
     new Set(bindings.map((binding) => binding.path))
   );
   if (unplaced.length > 0) throw new BymaxConfigValidationError(unplaced);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-config",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "description": "Typed and validated environment configuration entry point for NestJS 11 applications, built on Zod v4.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -54,7 +54,7 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "pnpm clean && tsup",
+    "build": "pnpm clean && tsup && node scripts/strip-bundle-comments.mjs",
     "check:api": "node scripts/check-api-surface.mjs",
     "check:exports": "attw --pack . --profile strict",
     "check:lint-graph": "node scripts/check-lint-graph-rules.mjs",