@meltstudio/config-loader 3.6.0 → 3.7.0

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. v2 includes breaking changes to the public API, object schema syntax, and requires Node.js >= 20. 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` or `yarn add @meltstudio/config-loader@latest`.
 
 **[Full documentation](https://meltstudio.github.io/config-loader/)**
 
@@ -54,6 +54,7 @@ const config = c
 - **Strict mode** — promote warnings to errors for production safety
 - **Default values** — static or computed (via functions)
 - **Multiple files / directory loading** — load from a list of files or an entire directory
+- **File watching** — `watch()` reloads config on file changes with debouncing, change detection, and error recovery
 
 ## Installation
 
@@ -72,9 +73,21 @@ Requires Node.js >= 20.
 See the **[full documentation](https://meltstudio.github.io/config-loader/)** for:
 
 - [Schema API](https://meltstudio.github.io/config-loader/schema-api) — primitives, objects, arrays, `oneOf`, `sensitive`, validation
-- [Loading & Sources](https://meltstudio.github.io/config-loader/loading-and-sources) — `load()`, `loadExtended()`, file/env/CLI/.env sources, `printConfig()`, `maskSecrets()`, error handling, strict mode
+- [Loading & Sources](https://meltstudio.github.io/config-loader/loading-and-sources) — `load()`, `loadExtended()`, `watch()`, file/env/CLI/.env sources, `printConfig()`, `maskSecrets()`, error handling, strict mode
 - [TypeScript Utilities](https://meltstudio.github.io/config-loader/typescript-utilities) — `SchemaValue`, exported types, type narrowing
 
+## Examples
+
+The [`example/`](./example) directory contains runnable examples:
+
+- **[Basic](./example/basic)** — Schema definition, YAML file loading, nested objects and arrays, CLI arguments
+- **[Advanced](./example/advanced)** — TOML config, `.env` files, `oneOf` constraints, `sensitive` fields, validation, `printConfig()`, `maskSecrets()`, error handling
+
+```bash
+yarn example:basic
+yarn example:advanced
+```
+
 ## Documentation for AI Agents
 
 This project provides machine-readable documentation for AI coding agents at the docs site:

package/dist/index.d.ts

@@ -207,6 +207,40 @@ declare class ObjectOption<T extends Node = Node> extends OptionBase<"object"> {
 
 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;
@@ -225,6 +259,15 @@ declare class SettingsBuilder<T extends Node> {
      * @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>>;
 }
 
 /**
@@ -363,4 +406,4 @@ declare const option: {
     schema: <T extends Node>(theSchema: T) => SettingsBuilder<T>;
 };
 
-export { type ConfigErrorEntry, ConfigFileError, ConfigLoadError, ConfigNode, ConfigNodeArray, type ExtendedResult, type NodeTree, type RecursivePartial, type SchemaValue, type SettingsSources, type StandardSchemaV1, option as default, maskSecrets, printConfig };
+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

@@ -35,6 +35,7 @@ __export(index_exports, {
   ConfigNode: () => configNode_default,
   ConfigNodeArray: () => configNodeArray_default,
   default: () => index_default,
+  diffConfig: () => diffConfig,
   maskSecrets: () => maskSecrets,
   printConfig: () => printConfig
 });
@@ -1153,6 +1154,176 @@ var Settings = class {
 };
 var settings_default = Settings;
 
+// src/watcher.ts
+var fs4 = __toESM(require("fs"));
+
+// src/diffConfig.ts
+var MASK = "***";
+function collectSensitivePaths(schema2, prefix = "") {
+  const paths = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(schema2)) {
+    const opt = schema2[key];
+    const fullPath = prefix ? `${prefix}.${key}` : key;
+    if (opt instanceof PrimitiveOption && opt.params.sensitive) {
+      paths.add(fullPath);
+    }
+    if (opt instanceof ObjectOption) {
+      const childPaths = collectSensitivePaths(opt.item, fullPath);
+      for (const p of childPaths) {
+        paths.add(p);
+      }
+    }
+  }
+  return paths;
+}
+function diffObjects(oldObj, newObj, sensitivePaths, prefix = "") {
+  const changes = [];
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(oldObj), ...Object.keys(newObj)]);
+  for (const key of allKeys) {
+    const fullPath = prefix ? `${prefix}.${key}` : key;
+    const isSensitive = sensitivePaths.has(fullPath);
+    const oldVal = oldObj[key];
+    const newVal = newObj[key];
+    const hasOld = key in oldObj;
+    const hasNew = key in newObj;
+    if (hasNew && !hasOld) {
+      changes.push({
+        path: fullPath,
+        type: "added",
+        oldValue: void 0,
+        newValue: isSensitive ? MASK : newVal
+      });
+    } else if (hasOld && !hasNew) {
+      changes.push({
+        path: fullPath,
+        type: "removed",
+        oldValue: isSensitive ? MASK : oldVal,
+        newValue: void 0
+      });
+    } else if (oldVal !== null && newVal !== null && typeof oldVal === "object" && typeof newVal === "object" && !Array.isArray(oldVal) && !Array.isArray(newVal)) {
+      changes.push(
+        ...diffObjects(
+          oldVal,
+          newVal,
+          sensitivePaths,
+          fullPath
+        )
+      );
+    } else if (!Object.is(oldVal, newVal)) {
+      if (Array.isArray(oldVal) && Array.isArray(newVal) && JSON.stringify(oldVal) === JSON.stringify(newVal)) {
+        continue;
+      }
+      changes.push({
+        path: fullPath,
+        type: "changed",
+        oldValue: isSensitive ? MASK : oldVal,
+        newValue: isSensitive ? MASK : newVal
+      });
+    }
+  }
+  return changes;
+}
+function diffConfig(oldConfig, newConfig, schema2) {
+  const sensitivePaths = schema2 ? collectSensitivePaths(schema2) : /* @__PURE__ */ new Set();
+  return diffObjects(oldConfig, newConfig, sensitivePaths);
+}
+
+// src/watcher.ts
+function resolveFilePaths(sources) {
+  const paths = [];
+  const configFiles = validateFiles(
+    sources.files ?? false,
+    sources.dir ?? false
+  );
+  if (Array.isArray(configFiles)) {
+    paths.push(...configFiles);
+  } else if (configFiles) {
+    paths.push(configFiles);
+  }
+  if (sources.envFile) {
+    const envFiles = Array.isArray(sources.envFile) ? sources.envFile : [sources.envFile];
+    paths.push(...envFiles);
+  }
+  return paths;
+}
+function createWatcher(schema2, sources, options) {
+  const debounceMs = options.debounce ?? 100;
+  const initialSettings = new settings_default(schema2, sources);
+  let currentConfig = initialSettings.get();
+  const filePaths = resolveFilePaths(sources);
+  const watchers = [];
+  let debounceTimer = null;
+  let closed = false;
+  function reload() {
+    if (closed) return;
+    try {
+      clearFileCache();
+      const settings = new settings_default(schema2, sources);
+      const newConfig = settings.get();
+      const changes = diffConfig(
+        currentConfig,
+        newConfig,
+        schema2
+      );
+      if (changes.length > 0) {
+        const oldConfig = currentConfig;
+        currentConfig = newConfig;
+        options.onChange(newConfig, oldConfig, changes);
+      }
+    } catch (err) {
+      if (options.onError) {
+        options.onError(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+  }
+  function scheduleReload() {
+    if (closed) return;
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+    debounceTimer = setTimeout(reload, debounceMs);
+    debounceTimer.unref();
+  }
+  for (const filePath of filePaths) {
+    try {
+      const watcher = fs4.watch(filePath, () => {
+        scheduleReload();
+      });
+      watcher.unref();
+      watchers.push(watcher);
+    } catch {
+    }
+  }
+  if (sources.dir && typeof sources.dir === "string") {
+    try {
+      const dirWatcher = fs4.watch(sources.dir, () => {
+        scheduleReload();
+      });
+      dirWatcher.unref();
+      watchers.push(dirWatcher);
+    } catch {
+    }
+  }
+  function close() {
+    if (closed) return;
+    closed = true;
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+    for (const watcher of watchers) {
+      watcher.close();
+    }
+    watchers.length = 0;
+  }
+  return {
+    get config() {
+      return currentConfig;
+    },
+    close
+  };
+}
+
 // src/builder/settings.ts
 var SettingsBuilder = class {
   schema;
@@ -1182,17 +1353,28 @@ var SettingsBuilder = class {
       warnings: settings.getWarnings()
     };
   }
+  /**
+   * 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, options) {
+    return createWatcher(this.schema, sources, options);
+  }
 };
 
 // src/maskSecrets.ts
-var MASK = "***";
+var MASK2 = "***";
 function maskNodeTree(tree) {
   const result = {};
   for (const [key, entry] of Object.entries(tree)) {
     if (entry instanceof configNode_default) {
       if (entry.sensitive) {
         const masked = new configNode_default(
-          MASK,
+          MASK2,
           entry.path,
           entry.sourceType,
           entry.file,
@@ -1233,7 +1415,7 @@ function maskPlainObject(obj, schema2) {
         result[key] = value;
       }
     } else if (schemaNode instanceof OptionBase) {
-      result[key] = schemaNode.params.sensitive ? MASK : value;
+      result[key] = schemaNode.params.sensitive ? MASK2 : value;
     } else {
       result[key] = value;
     }
@@ -1433,6 +1615,7 @@ var index_default = option;
   ConfigLoadError,
   ConfigNode,
   ConfigNodeArray,
+  diffConfig,
   maskSecrets,
   printConfig
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meltstudio/config-loader",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "Type-safe configuration loader with full TypeScript inference. Load from YAML, JSON, TOML, .env, environment variables, and CLI args.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -39,7 +39,8 @@
     "type-check": "tsc --noEmit",
     "test": "jest --verbose",
     "replace-tspaths": "./scripts/replace-tspaths/index.mjs",
-    "example:run": "ts-node -r tsconfig-paths/register ./example/index.ts",
+    "example:basic": "ts-node -r tsconfig-paths/register ./example/basic/index.ts",
+    "example:advanced": "ts-node -r tsconfig-paths/register ./example/advanced/index.ts",
     "prepare": "husky",
     "docs:build": "docusaurus build && node scripts/fix-llms-urls.mjs",
     "docs:serve": "docusaurus serve",