@meltstudio/config-loader 3.7.0 → 4.0.3

package/README.md

@@ -2,7 +2,7 @@
 
 A type-safe configuration loader for Node.js. Define your schema once, load from YAML, JSON, or TOML files, `.env` files, environment variables, and CLI arguments — and get a fully typed result with zero manual type annotations.
 
-> **Upgrading from v1?** v1.x is deprecated and no longer maintained. Install the latest version with `npm install @meltstudio/config-loader@latest` or `yarn add @meltstudio/config-loader@latest`.
+> **Upgrading from v1?** v1.x is deprecated and no longer maintained. Install the latest version with `npm install @meltstudio/config-loader@latest`.
 
 **[Full documentation](https://meltstudio.github.io/config-loader/)**
 
@@ -62,12 +62,47 @@ const config = c
 npm install @meltstudio/config-loader
 ```
 
+```bash
+pnpm add @meltstudio/config-loader
+```
+
 ```bash
 yarn add @meltstudio/config-loader
 ```
 
 Requires Node.js >= 20.
 
+## Watch Mode
+
+Automatically reload config when files change. Watchers use `.unref()` so they don't prevent the process from exiting.
+
+```typescript
+const watcher = c
+  .schema({
+    port: c.number({ env: "PORT", defaultValue: 3000 }),
+    host: c.string({ defaultValue: "localhost" }),
+  })
+  .watch(
+    { env: true, args: false, files: "./config.yaml" },
+    {
+      onChange: (newConfig, oldConfig, changes) => {
+        for (const change of changes) {
+          console.log(
+            `${change.path}: ${String(change.oldValue)} → ${String(change.newValue)}`,
+          );
+        }
+      },
+      onError: (err) => console.error("Reload failed:", err.message),
+    },
+  );
+
+// Access current config anytime
+console.log(watcher.config.port);
+
+// Stop watching
+watcher.close();
+```
+
 ## Documentation
 
 See the **[full documentation](https://meltstudio.github.io/config-loader/)** for:
@@ -84,8 +119,8 @@ The [`example/`](./example) directory contains runnable examples:
 - **[Advanced](./example/advanced)** — TOML config, `.env` files, `oneOf` constraints, `sensitive` fields, validation, `printConfig()`, `maskSecrets()`, error handling
 
 ```bash
-yarn example:basic
-yarn example:advanced
+pnpm example:basic
+pnpm example:advanced
 ```
 
 ## Documentation for AI Agents

package/dist/index.d.mts

@@ -0,0 +1,409 @@
+declare class ArrayValueContainer {
+    readonly val: ArrayValue;
+    readonly item: OptionTypes;
+    constructor(item: OptionTypes, val: ArrayValue);
+}
+
+interface EnvFileEntry {
+    value: string;
+    line: number;
+    column: number;
+}
+interface EnvFileResult {
+    entries: Map<string, EnvFileEntry>;
+    filePath: string;
+}
+
+/** A single configuration validation error with optional location metadata. */
+interface ConfigErrorEntry {
+    /** Human-readable error description. */
+    message: string;
+    /** Dot-separated path to the offending config key (e.g. `"db.port"`). */
+    path?: string;
+    /** The source where the error originated (e.g. file path, `"env"`, `"cli"`). */
+    source?: string;
+    /** Classification of the error. */
+    kind?: "required" | "type_conversion" | "invalid_path" | "invalid_state" | "file_validation" | "null_value" | "strict" | "validation";
+    /** Line number in the config file where the error occurred, if applicable. */
+    line?: number;
+    /** Column number in the config file where the error occurred, if applicable. */
+    column?: number;
+}
+/** Thrown when configuration loading fails validation. Contains structured error entries and warnings. */
+declare class ConfigLoadError extends Error {
+    /** All validation errors that caused the load to fail. */
+    readonly errors: ConfigErrorEntry[];
+    /** Non-fatal warnings collected during loading. */
+    readonly warnings: string[];
+    constructor(errors: ConfigErrorEntry[], warnings: string[]);
+}
+/** Thrown when a configuration file cannot be read or parsed. */
+declare class ConfigFileError extends ConfigLoadError {
+    constructor(message: string);
+}
+
+declare class OptionErrors {
+    errors: ConfigErrorEntry[];
+    warnings: string[];
+    clearAll(): void;
+}
+
+type Value = boolean | string | number | object | InvalidValue;
+type DefaultValue = Value | (() => string) | (() => number) | (() => boolean);
+type TypedDefaultValue<T extends OptionKind> = T extends PrimitiveKind ? TypeOfPrimitiveKind<T> | (() => TypeOfPrimitiveKind<T>) : DefaultValue;
+interface Node {
+    [key: string]: OptionBase;
+}
+interface OptionClassParams<T extends OptionKind> {
+    kind: T;
+    required: boolean;
+    env: string | null;
+    cli: boolean;
+    help: string;
+    sensitive?: boolean;
+    defaultValue?: TypedDefaultValue<T>;
+    oneOf?: ReadonlyArray<string | number | boolean>;
+    validate?: StandardSchemaV1;
+}
+declare class OptionBase<T extends OptionKind = OptionKind> {
+    readonly params: OptionClassParams<T>;
+    constructor(params: OptionClassParams<T>);
+    getValue<U>(sourceFile: string | string[], env: {
+        [key: string]: string | undefined;
+    }, args: {
+        [key: string]: string | boolean;
+    }, path: Path, defaultValues?: Partial<U>, objectFromArray?: {
+        value: ConfigFileData;
+        file: string;
+        sourceMap?: {
+            lookup(path: string | string[]): {
+                line: number;
+                column: number;
+            } | undefined;
+        } | null;
+    }, envFileResults?: EnvFileResult[], errors?: OptionErrors): ConfigNode | null;
+    private resolveValue;
+    private runOneOfCheck;
+    private runValidation;
+    private resolveFromFileData;
+    checkType(val: Value, path: Path, sourceOfVal: string, errors?: OptionErrors): Value;
+    protected findInObject(obj: ConfigFileData, path: Path, errors?: OptionErrors): Value | ArrayValue;
+    buildArrayOption(_val: string[] | ConfigFileData[], _errors?: OptionErrors): ArrayValueContainer | InvalidValue;
+}
+
+type SourceTypes = "file" | "env" | "envFile" | "args" | "default";
+declare class ConfigNode {
+    value: Value | ArrayValueContainer;
+    path: string;
+    sourceType: SourceTypes;
+    file: string | null;
+    variableName: string | null;
+    argName: string | null;
+    line: number | null;
+    column: number | null;
+    sensitive: boolean;
+    constructor(value: Value | ArrayValue, path: string, sourceType: SourceTypes, file: string | null, variableName: string | null, argName: string | null, line?: number | null, column?: number | null, sensitive?: boolean);
+}
+
+declare class PrimitiveOption<T extends PrimitiveKind = PrimitiveKind, Narrowed = TypeOfPrimitiveKind<T>> extends OptionBase<T> {
+}
+
+type NodeTree = {
+    [key: string]: NodeTree | ConfigNode;
+};
+/** Result returned by `SettingsBuilder.loadExtended()`, including raw node data and warnings. */
+type ExtendedResult = {
+    /** Tree of `ConfigNode` objects preserving source metadata for each resolved value. */
+    data: NodeTree;
+    /** Non-fatal warnings collected during loading. */
+    warnings: string[];
+};
+type RecursivePartial<T> = {
+    [K in keyof T]?: RecursivePartial<T[K]>;
+};
+/** Configuration sources passed to `SettingsBuilder.load()` / `loadExtended()`. Priority: CLI > Env > Files > Defaults. */
+type SettingsSources<T> = {
+    /** Whether to read values from `process.env`. */
+    env: boolean;
+    /** Whether to parse CLI arguments via Commander. */
+    args: boolean;
+    /** YAML/JSON file path(s) to load, or `false` to skip. */
+    files?: string | string[] | false;
+    /** Directory to scan for config files, or `false` to skip. */
+    dir?: string | false;
+    /** `.env` file path(s) to load, or `false` to skip. */
+    envFile?: string | string[] | false;
+    /** Partial default values applied at the lowest priority. */
+    defaults?: RecursivePartial<T>;
+    /** When `true`, unknown keys in config files cause errors. */
+    strict?: boolean;
+};
+type OptionKind = "boolean" | "string" | "number" | "array" | "object";
+type PrimitiveKind = Extract<OptionKind, "boolean" | "string" | "number">;
+type TypeOfPrimitiveKind<T extends PrimitiveKind> = T extends "boolean" ? boolean : T extends "string" ? string : T extends "number" ? number : never;
+/** Recursively infers the plain TypeScript type from a schema definition. Maps option nodes to their resolved value types. */
+type SchemaValue<T extends OptionBase | Node> = T extends OptionBase ? T extends ArrayOption<OptionTypes> ? SchemaValue<T["item"]>[] : T extends ObjectOption<infer R> ? {
+    [K in keyof R]: SchemaValue<R[K]>;
+} : T extends PrimitiveOption<infer _R, infer Narrowed> ? Narrowed : never : T extends Node ? {
+    [K in keyof T]: SchemaValue<T[K]>;
+} : never;
+type Path = Array<string | number>;
+type ConfigFileStructure<T> = {
+    [key: string]: string | T | number | boolean | Array<T> | string[];
+};
+interface ConfigFileData extends ConfigFileStructure<ConfigFileData> {
+}
+type ArrayValue = Array<string | number | boolean | ConfigFileData>;
+declare class InvalidValue {
+}
+/**
+ * A single issue returned by a Standard Schema validator.
+ * Mirrors the Standard Schema v1 spec (https://github.com/standard-schema/standard-schema).
+ */
+interface StandardSchemaIssue {
+    message: string;
+    path?: ReadonlyArray<PropertyKey | object>;
+}
+type StandardSchemaResult<Output> = {
+    value: Output;
+} | {
+    issues: ReadonlyArray<StandardSchemaIssue>;
+};
+/**
+ * Minimal Standard Schema v1 interface for value validation.
+ * Any object with a `~standard.validate()` method is accepted — this covers
+ * Zod 3.24+/4+, Valibot 1.0+, ArkType 2.1+, and custom validators.
+ */
+interface StandardSchemaV1<Output = unknown> {
+    "~standard": {
+        version: 1;
+        vendor: string;
+        validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    };
+}
+
+interface ArrayOptionClassParams<T extends OptionTypes> {
+    required: boolean;
+    defaultValue?: SchemaValue<T>[] | (() => SchemaValue<T>[]);
+    item: T;
+    validate?: StandardSchemaV1;
+}
+declare class ArrayOption<T extends OptionTypes> extends OptionBase<"array"> {
+    item: T;
+    constructor(params: ArrayOptionClassParams<T>);
+    buildArrayOption(val: string[] | ConfigFileData[], errors?: OptionErrors): ArrayValueContainer | InvalidValue;
+    checkType(val: Value, path: Path, sourceOfVal: string, errors?: OptionErrors): Value;
+}
+
+interface ObjectOptionClassParams<T extends Node> {
+    required: boolean;
+    item: T;
+    validate?: StandardSchemaV1;
+}
+declare class ObjectOption<T extends Node = Node> extends OptionBase<"object"> {
+    item: T;
+    constructor(params: ObjectOptionClassParams<T>);
+}
+
+type OptionTypes = PrimitiveOption | ArrayOption<OptionTypes> | ObjectOption<Node>;
+
+/** A single change detected between two config loads. */
+interface ConfigChange {
+    /** Dot-separated path to the changed key (e.g. "db.url"). */
+    path: string;
+    /** The previous value (undefined if key was added). */
+    oldValue: unknown;
+    /** The new value (undefined if key was removed). */
+    newValue: unknown;
+    /** Whether the change was an addition, removal, or modification. */
+    type: "added" | "removed" | "changed";
+}
+/**
+ * Compares two plain config objects and returns a list of changes.
+ * Sensitive fields (from the schema) are masked in the output.
+ */
+declare function diffConfig(oldConfig: Record<string, unknown>, newConfig: Record<string, unknown>, schema?: Node): ConfigChange[];
+
+/** Options for the `watch()` method. */
+interface WatchOptions<T> {
+    /** Called after a successful reload with the new config, old config, and list of changes. */
+    onChange: (newConfig: T, oldConfig: T, changes: ConfigChange[]) => void;
+    /** Called when a reload fails (parse error, validation error). The previous config is retained. */
+    onError?: (error: Error) => void;
+    /** Debounce interval in milliseconds. Default: 100. */
+    debounce?: number;
+}
+/** Handle returned by `watch()`. Provides access to the current config and a `close()` method. */
+interface ConfigWatcher<T> {
+    /** The current resolved configuration. Updated on each successful reload. */
+    readonly config: T;
+    /** Stop watching all files. Idempotent. */
+    close(): void;
+}
+
+/** Fluent builder that takes a schema and resolves configuration from multiple sources. */
+declare class SettingsBuilder<T extends Node> {
+    private readonly schema;
+    constructor(schema: T);
+    /**
+     * Loads and validates configuration, returning a fully-typed plain object.
+     * @param sources - Which sources to read (env, args, files, etc.).
+     * @returns The resolved configuration object matching the schema type.
+     * @throws {ConfigLoadError} If validation fails (missing required fields, type errors, etc.).
+     */
+    load(sources: SettingsSources<SchemaValue<T>>): SchemaValue<T>;
+    /**
+     * Loads configuration and returns raw node data with source metadata alongside warnings.
+     * @param sources - Which sources to read (env, args, files, etc.).
+     * @returns An `ExtendedResult` containing the node tree and any warnings.
+     * @throws {ConfigLoadError} If validation fails.
+     */
+    loadExtended(sources: SettingsSources<SchemaValue<T>>): ExtendedResult;
+    /**
+     * Watches config files for changes and reloads automatically.
+     * File watchers are `.unref()`'d so they don't prevent the process from exiting.
+     * @param sources - Which sources to read (env, args, files, etc.).
+     * @param options - Callbacks and debounce configuration.
+     * @returns A `ConfigWatcher` with the current config and a `close()` method.
+     * @throws {ConfigLoadError} If the initial load fails.
+     */
+    watch(sources: SettingsSources<SchemaValue<T>>, options: WatchOptions<SchemaValue<T>>): ConfigWatcher<SchemaValue<T>>;
+}
+
+/**
+ * Masks sensitive values in an `ExtendedResult` from `loadExtended()`.
+ * Fields marked `sensitive: true` have their values replaced with `"***"`.
+ *
+ * @param result - The `ExtendedResult` returned by `loadExtended()`.
+ * @returns A new `ExtendedResult` with sensitive values masked.
+ */
+declare function maskSecrets(result: ExtendedResult): ExtendedResult;
+/**
+ * Masks sensitive values in a plain config object from `load()`.
+ * Fields marked `sensitive: true` in the schema have their values replaced with `"***"`.
+ *
+ * @param config - The plain config object returned by `load()`.
+ * @param schema - The schema definition used to identify sensitive fields.
+ * @returns A new object with sensitive values masked.
+ */
+declare function maskSecrets<T extends Record<string, unknown>>(config: T, schema: Node): T;
+
+declare class ConfigNodeArray {
+    arrayValues: ConfigNode[];
+    constructor(arrayValues: ConfigNode[]);
+}
+
+/**
+ * Formats the result of `loadExtended()` as a readable table showing each
+ * resolved value and where it came from.
+ *
+ * @param result - The `ExtendedResult` returned by `loadExtended()`.
+ * @param options - Optional settings.
+ * @param options.maxValueLength - Maximum length for value column (default: 50). Values longer than this are truncated.
+ * @returns The formatted table string. Also printed to `console.log` unless `options.silent` is `true`.
+ *
+ * @example
+ * ```ts
+ * const result = c.schema({ port: c.number({ env: "PORT" }) }).loadExtended({ env: true, args: false });
+ * printConfig(result);
+ * ```
+ */
+declare function printConfig(result: ExtendedResult, options?: {
+    silent?: boolean;
+    maxValueLength?: number;
+}): string;
+
+/** Options for configuring a primitive (`string`, `number`, `bool`) schema field. */
+interface OptionPropsArgs<T> {
+    /** Whether the field must be present in at least one source. */
+    required?: boolean;
+    /** Environment variable name to read from, or `null` to disable. */
+    env?: string | null;
+    /** Whether to expose this field as a CLI argument via Commander. */
+    cli?: boolean;
+    /** Static default value or factory function returning one. */
+    defaultValue?: T | (() => T);
+    /** Help text shown in CLI `--help` output. */
+    help?: string;
+    /** Mark this field as sensitive. Sensitive values are masked by `printConfig()` and `maskSecrets()`. */
+    sensitive?: boolean;
+    /** Restrict the value to a fixed set of allowed values. Checked after type coercion, before `validate`. */
+    oneOf?: readonly T[];
+    /** Standard Schema validator run after type coercion. Accepts Zod, Valibot, ArkType, or any Standard Schema v1 implementation. */
+    validate?: StandardSchemaV1;
+}
+/** Options for configuring an `array` schema field. */
+interface ArrayOptionPropsArgs<T extends OptionTypes> {
+    /** Whether the field must be present in at least one source. */
+    required?: boolean;
+    /** Schema definition for each item in the array. */
+    item: T;
+    /** Static default value or factory function returning one. */
+    defaultValue?: SchemaValue<T>[] | (() => SchemaValue<T>[]);
+    /** Standard Schema validator run on the resolved array. Accepts Zod, Valibot, ArkType, or any Standard Schema v1 implementation. */
+    validate?: StandardSchemaV1;
+}
+/** Options for configuring a nested `object` schema field. */
+interface ObjectOptionPropsArgs<T extends Node> {
+    /** Whether the field must be present in at least one source. */
+    required?: boolean;
+    /** Schema definition for the nested object's shape. */
+    item: T;
+    /** Standard Schema validator run on the resolved object. Accepts Zod, Valibot, ArkType, or any Standard Schema v1 implementation. */
+    validate?: StandardSchemaV1;
+}
+/**
+ * Creates a string configuration option.
+ * @param opts - Option configuration (env, cli, required, defaultValue, help, oneOf).
+ * @returns A `PrimitiveOption<"string">` for use in a schema.
+ * @example
+ * c.string({ env: "HOST", defaultValue: "localhost" })
+ * c.string({ env: "NODE_ENV", oneOf: ["development", "staging", "production"] })
+ */
+declare function string<const V extends readonly string[]>(opts: OptionPropsArgs<string> & {
+    oneOf: V;
+}): PrimitiveOption<"string", V[number]>;
+declare function string(opts?: OptionPropsArgs<string>): PrimitiveOption<"string">;
+/**
+ * Creates a number configuration option. String values from env/CLI are coerced to numbers.
+ * @param opts - Option configuration (env, cli, required, defaultValue, help, oneOf).
+ * @returns A `PrimitiveOption<"number">` for use in a schema.
+ * @example
+ * c.number({ env: "PORT", defaultValue: 3000 })
+ * c.number({ env: "LOG_LEVEL", oneOf: [0, 1, 2, 3] })
+ */
+declare function number<const V extends readonly number[]>(opts: OptionPropsArgs<number> & {
+    oneOf: V;
+}): PrimitiveOption<"number", V[number]>;
+declare function number(opts?: OptionPropsArgs<number>): PrimitiveOption<"number">;
+/**
+ * Creates a boolean configuration option. String values `"true"`/`"false"` are coerced.
+ * @param opts - Option configuration (env, cli, required, defaultValue, help).
+ * @returns A `PrimitiveOption<"boolean">` for use in a schema.
+ * @example
+ * c.bool({ env: "DEBUG", defaultValue: false })
+ */
+declare function bool(opts?: OptionPropsArgs<boolean>): PrimitiveOption<"boolean">;
+/**
+ * Config-loader entry point. Provides factory functions to define a typed configuration schema.
+ *
+ * @example
+ * ```ts
+ * import c from "@meltstudio/config-loader";
+ *
+ * const config = c.schema({
+ *   port: c.number({ env: "PORT", defaultValue: 3000 }),
+ *   host: c.string({ env: "HOST" }),
+ * }).load({ env: true, args: false });
+ * ```
+ */
+declare const option: {
+    string: typeof string;
+    number: typeof number;
+    bool: typeof bool;
+    array: <T extends OptionTypes>(opts: ArrayOptionPropsArgs<T>) => ArrayOption<T>;
+    object: <T extends Node>(opts: ObjectOptionPropsArgs<T>) => ObjectOption<T>;
+    schema: <T extends Node>(theSchema: T) => SettingsBuilder<T>;
+};
+
+export { type ConfigChange, type ConfigErrorEntry, ConfigFileError, ConfigLoadError, ConfigNode, ConfigNodeArray, type ConfigWatcher, type ExtendedResult, type NodeTree, type RecursivePartial, type SchemaValue, type SettingsSources, type StandardSchemaV1, type WatchOptions, option as default, diffConfig, maskSecrets, printConfig };

package/dist/index.js

@@ -1258,6 +1258,7 @@ function createWatcher(schema2, sources, options) {
     if (closed) return;
     try {
       clearFileCache();
+      clearEnvFileCache();
       const settings = new settings_default(schema2, sources);
       const newConfig = settings.get();
       const changes = diffConfig(