Config Normalizer

A utility that combines base defaults, environment overrides, and user overrides into a shaped configuration object while keeping only the requested top-level keys.

Capabilities

Deep defaults with override order

• With base defaults { service: { host: "localhost", port: 3000 }, security: { cors: false } }, environment overrides { service: { port: 8080, host: undefined } }, and user overrides { security: { cors: true } }, the result is { service: { host: "localhost", port: 8080 }, security: { cors: true } } and the base defaults remain unmodified. @test

Allowlist shaping

• Given base defaults { service: { port: 3000, ssl: false }, debug: false }, overrides { service: { ssl: true }, debug: true, extras: { verbose: true } }, and allowKeys: ["service"], the final result is { service: { port: 3000, ssl: true } } (all other top-level keys are dropped while keeping deep defaults). @test

Key renaming

• With base defaults { retries: 2, timeout: 1000 }, user overrides { retryCount: 5 }, and renameMap: { "retryCount": "retries" }, the result is { retries: 5, timeout: 1000 } while ignoring unknown keys. @test

Processing rules

• Work on a clone of the base defaults so the input objects are never mutated.
• Apply the rename map to override inputs before merging so alternate keys populate their canonical counterparts (map entries are incomingKey -> canonicalKey).
• Merge environment overrides over the cloned defaults and then merge user overrides over that result.
• Values set to undefined in overrides do not overwrite existing data; other falsey values (like null or 0) do.
• If an allowlist is provided, drop any top-level keys that are not included after merging is complete.

Implementation

@generates

API

export interface NormalizeOptions {
  allowKeys?: string[];
  renameMap?: Record<string, string>;
}

export function normalizeConfig(
  baseDefaults: Record<string, any>,
  envConfig?: Record<string, any> | undefined,
  userConfig?: Record<string, any> | undefined,
  options?: NormalizeOptions | undefined
): Record<string, any>;

Dependencies { .dependencies }

lodash { .dependency }

Utility helpers for deep merging, defaulting, and object reshaping.