@bymax-one/nest-config 1.0.0

package/dist/internal/index.cjs

@@ -0,0 +1,423 @@
+'use strict';
+
+var common = require('@nestjs/common');
+var zod = require('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 common.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]
+};
+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) {
+    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));
+  }
+};
+exports.ConfigService = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(BYMAX_CONFIG))
+], exports.ConfigService);
+
+// src/config.module.ts
+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,
+      providers: appendTo(definition.providers, bymaxConfigProvider, exports.ConfigService),
+      exports: appendTo(definition.exports, BYMAX_CONFIG, exports.ConfigService)
+    };
+  }
+};
+exports.BymaxConfigModule = __decorateClass([
+  common.Module({})
+], exports.BymaxConfigModule);
+function defineEnv(shape) {
+  return zod.z.object(shape);
+}
+
+exports.BYMAX_CONFIG = BYMAX_CONFIG;
+exports.BYMAX_CONFIG_OPTIONS = BYMAX_CONFIG_OPTIONS;
+exports.BymaxConfigValidationError = BymaxConfigValidationError;
+exports.ConfigErrorCode = ConfigErrorCode;
+exports.createValidatedConfig = createValidatedConfig;
+exports.defineEnv = defineEnv;
+exports.resolveSourceNames = resolveSourceNames;