@0disoft/universal-config-engine-node

@0disoft/universal-config-engine-node

Bounded Node.js source adapters for Universal Config Engine. The package provides JSON file, simple dotenv file, process environment, and argv sources while keeping filesystem and process APIs outside the core package.

Install

npm install @0disoft/universal-config-engine-core @0disoft/universal-config-engine-node

Node.js >=24 and ESM are required.

Process Environment Source

import { resolveConfig } from "@0disoft/universal-config-engine-core";
import { createProcessEnvSource } from "@0disoft/universal-config-engine-node";

const envSource = createProcessEnvSource({
  descriptor: {
    id: "env",
    kind: "process-env",
    priority: 20,
    displayName: "environment"
  },
  env: process.env,
  mappings: [
    {
      externalName: "APP_PORT",
      sourceKind: "process-env",
      targetPath: ["service", "port"],
      parseAs: "number"
    }
  ]
});

const result = resolveConfig({ sources: [envSource] });
console.log(result.config.service.port);

File Sources

loadJsonFileSource and loadDotenvFileSource enforce byte limits. Set allowedRootPath to bind file loading to a canonical directory; the loader verifies the opened file identity before reading it. The dotenv parser is intentionally simple and does not perform shell expansion.

JSON source locations also have an independent maxLocationBytes budget (default 4 MiB of compact UTF-8 location records). If exceeded, the loader preserves parsed config values, omits location metadata and returns a max_location_bytes_exceeded warning. This option does not replace file byte or structural depth/key limits and is not a total JavaScript heap limit.

Process-env and argv adapters use explicit mappings and bounded entry counts. Strict unmapped-input diagnostics are opt-in.

See the compatibility contract and public API contract.

License

MIT