c12 1.3.0 → 1.4.0

package/README.md

@@ -16,6 +16,7 @@ Smart Configuration Loader.
 - Reads config from the nearest `package.json` file
 - [Extends configurations](https://github.com/unjs/c12#extending-configuration) from multiple local or git sources
 - Overwrite with [environment-specific configuration](#environment-specific-configuration)
+- Config watcher with auto-reload and HMR support
 
 ## Usage
 
@@ -36,10 +37,10 @@ Import:
 
 ```js
 // ESM
-import { loadConfig } from "c12";
+import { loadConfig, watchConfig } from "c12";
 
 // CommonJS
-const { loadConfig } = require("c12");
+const { loadConfig, watchConfig } = require("c12");
 ```
 
 Load configuration:
@@ -59,7 +60,7 @@ c12 merged config sources with [unjs/defu](https://github.com/unjs/defu) by belo
 1. Config overrides passed by options
 2. Config file in CWD
 3. RC file in CWD
-4. Global RC file in user's home directory
+4. Global RC file in the user's home directory
 5. Config from `package.json`
 6. Default config passed by options
 7. Extended config layers
@@ -234,6 +235,46 @@ c12 tries to match [`envName`](#envname) and override environment config if spec
 }
 ```
 
+## Watching Configuration
+
+you can use `watchConfig` instead of `loadConfig` to load config and watch for changes, add and removals in all expected configuration paths and auto reload with new config.
+
+### Lifecycle hooks
+
+- `onWatch`: This function is always called when config is updated, added, or removed before attempting to reload the config.
+- `acceptHMR`: By implementing this function, you can compare old and new functions and return `true` if a full reload is not needed.
+- `onUpdate`: This function is always called after the new config is updated. If `acceptHMR` returns true, it will be skipped.
+
+```ts
+import { watchConfig } from "c12";
+
+const config = watchConfig({
+  cwd: ".",
+  // chokidarOptions: {}, // Default is { ignoreInitial: true }
+  // debounce: 200 // Default is 100. You can set it to false to disable debounced watcher
+  onWatch: (event) => {
+    console.log("[watcher]", event.type, event.path);
+  },
+  acceptHMR({ oldConfig, newConfig, getDiff }) {
+    const diff = getDiff();
+    if (diff.length === 0) {
+      console.log("No config changed detected!");
+      return true; // No changes!
+    }
+  },
+  onUpdate({ oldConfig, newConfig, getDiff }) {
+    const diff = getDiff();
+    console.log("Config updated:\n" + diff.map((i) => i.toJSON()).join("\n"));
+  },
+});
+
+console.log("watching config files:", config.watchingFiles);
+console.log("initial config", config.config);
+
+// Stop watcher when not needed anymore
+// await config.unwatch();
+```
+
 ## 💻 Development
 
 - Clone this repository

package/dist/index.cjs

@@ -9,6 +9,9 @@ const createJiti = require('jiti');
 const rc9 = require('rc9');
 const defu = require('defu');
 const pkgTypes = require('pkg-types');
+const chokidar = require('chokidar');
+const perfectDebounce = require('perfect-debounce');
+const ohash = require('ohash');
 
 function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
 
@@ -318,7 +321,86 @@ function createDefineConfig() {
   return (input) => input;
 }
 
+const eventMap = {
+  add: "created",
+  change: "updated",
+  unlink: "removed"
+};
+async function watchConfig(options) {
+  let config = await loadConfig(options);
+  const configName = options.name || "config";
+  const watchingFiles = [
+    ...new Set(
+      (config.layers || []).filter((l) => l.cwd).flatMap((l) => [
+        ...["ts", "js", "mjs", "cjs", "cts", "mts", "json"].map(
+          (ext) => pathe.resolve(l.cwd, (options.name || "config") + "." + ext)
+        ),
+        l.source && pathe.resolve(l.cwd, l.source),
+        // TODO: Support watching rc from home and workspace
+        options.rcFile && pathe.resolve(
+          l.cwd,
+          typeof options.rcFile === "string" ? options.rcFile : `.${configName}rc`
+        ),
+        options.packageJson && pathe.resolve(l.cwd, "package.json")
+      ]).filter(Boolean)
+    )
+  ];
+  const _fswatcher = chokidar.watch(watchingFiles, {
+    ignoreInitial: true,
+    ...options.chokidarOptions
+  });
+  const onChange = async (event, path) => {
+    const type = eventMap[event];
+    if (!type) {
+      return;
+    }
+    if (options.onWatch) {
+      await options.onWatch({
+        type,
+        path
+      });
+    }
+    const oldConfig = config;
+    const newConfig = await loadConfig(options);
+    config = newConfig;
+    const changeCtx = {
+      newConfig,
+      oldConfig,
+      getDiff: () => ohash.diff(oldConfig.config, config.config)
+    };
+    if (options.acceptHMR) {
+      const changeHandled = await options.acceptHMR(changeCtx);
+      if (changeHandled) {
+        return;
+      }
+    }
+    if (options.onUpdate) {
+      await options.onUpdate(changeCtx);
+    }
+  };
+  if (options.debounce !== false) {
+    _fswatcher.on("all", perfectDebounce.debounce(onChange, options.debounce));
+  } else {
+    _fswatcher.on("all", onChange);
+  }
+  const utils = {
+    watchingFiles,
+    unwatch: async () => {
+      await _fswatcher.close();
+    }
+  };
+  return new Proxy(utils, {
+    get(_, prop) {
+      if (prop in utils) {
+        return utils[prop];
+      }
+      return config[prop];
+    }
+  });
+}
+
 exports.createDefineConfig = createDefineConfig;
 exports.loadConfig = loadConfig;
 exports.loadDotenv = loadDotenv;
 exports.setupDotenv = setupDotenv;
+exports.watchConfig = watchConfig;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { JITI } from 'jiti';
 import { JITIOptions } from 'jiti/dist/types';
+import { WatchOptions } from 'chokidar';
+import { diff } from 'ohash';
 
 interface DotenvOptions {
     /**
@@ -91,4 +93,28 @@ declare function createDefineConfig<T extends UserInputConfig = UserInputConfig,
 
 declare function loadConfig<T extends UserInputConfig = UserInputConfig, MT extends ConfigLayerMeta = ConfigLayerMeta>(options: LoadConfigOptions<T, MT>): Promise<ResolvedConfig<T, MT>>;
 
-export { C12InputConfig, ConfigLayer, ConfigLayerMeta, DefineConfig, DotenvOptions, Env, InputConfig, LoadConfigOptions, ResolvedConfig, SourceOptions, UserInputConfig, createDefineConfig, loadConfig, loadDotenv, setupDotenv };
+type ConfigWatcher<T extends UserInputConfig = UserInputConfig, MT extends ConfigLayerMeta = ConfigLayerMeta> = ResolvedConfig<T, MT> & {
+    watchingFiles: string[];
+    unwatch: () => Promise<void>;
+};
+interface WatchConfigOptions<T extends UserInputConfig = UserInputConfig, MT extends ConfigLayerMeta = ConfigLayerMeta> extends LoadConfigOptions<T, MT> {
+    chokidarOptions?: WatchOptions;
+    debounce?: false | number;
+    onWatch?: (event: {
+        type: "created" | "updated" | "removed";
+        path: string;
+    }) => void | Promise<void>;
+    acceptHMR?: (context: {
+        getDiff: () => ReturnType<typeof diff>;
+        newConfig: ResolvedConfig<T, MT>;
+        oldConfig: ResolvedConfig<T, MT>;
+    }) => void | boolean | Promise<void | boolean>;
+    onUpdate?: (context: {
+        getDiff: () => ReturnType<typeof diff>;
+        newConfig: ResolvedConfig<T, MT>;
+        oldConfig: ResolvedConfig<T, MT>;
+    }) => void | Promise<void>;
+}
+declare function watchConfig<T extends UserInputConfig = UserInputConfig, MT extends ConfigLayerMeta = ConfigLayerMeta>(options: WatchConfigOptions<T, MT>): Promise<ConfigWatcher<T, MT>>;
+
+export { C12InputConfig, ConfigLayer, ConfigLayerMeta, ConfigWatcher, DefineConfig, DotenvOptions, Env, InputConfig, LoadConfigOptions, ResolvedConfig, SourceOptions, UserInputConfig, WatchConfigOptions, createDefineConfig, loadConfig, loadDotenv, setupDotenv, watchConfig };

package/dist/index.mjs

@@ -7,6 +7,9 @@ import createJiti from 'jiti';
 import * as rc9 from 'rc9';
 import { defu } from 'defu';
 import { findWorkspaceDir, readPackageJSON } from 'pkg-types';
+import { watch } from 'chokidar';
+import { debounce } from 'perfect-debounce';
+import { diff } from 'ohash';
 
 async function setupDotenv(options) {
   const targetEnvironment = options.env ?? process.env;
@@ -298,4 +301,82 @@ function createDefineConfig() {
   return (input) => input;
 }
 
-export { createDefineConfig, loadConfig, loadDotenv, setupDotenv };
+const eventMap = {
+  add: "created",
+  change: "updated",
+  unlink: "removed"
+};
+async function watchConfig(options) {
+  let config = await loadConfig(options);
+  const configName = options.name || "config";
+  const watchingFiles = [
+    ...new Set(
+      (config.layers || []).filter((l) => l.cwd).flatMap((l) => [
+        ...["ts", "js", "mjs", "cjs", "cts", "mts", "json"].map(
+          (ext) => resolve(l.cwd, (options.name || "config") + "." + ext)
+        ),
+        l.source && resolve(l.cwd, l.source),
+        // TODO: Support watching rc from home and workspace
+        options.rcFile && resolve(
+          l.cwd,
+          typeof options.rcFile === "string" ? options.rcFile : `.${configName}rc`
+        ),
+        options.packageJson && resolve(l.cwd, "package.json")
+      ]).filter(Boolean)
+    )
+  ];
+  const _fswatcher = watch(watchingFiles, {
+    ignoreInitial: true,
+    ...options.chokidarOptions
+  });
+  const onChange = async (event, path) => {
+    const type = eventMap[event];
+    if (!type) {
+      return;
+    }
+    if (options.onWatch) {
+      await options.onWatch({
+        type,
+        path
+      });
+    }
+    const oldConfig = config;
+    const newConfig = await loadConfig(options);
+    config = newConfig;
+    const changeCtx = {
+      newConfig,
+      oldConfig,
+      getDiff: () => diff(oldConfig.config, config.config)
+    };
+    if (options.acceptHMR) {
+      const changeHandled = await options.acceptHMR(changeCtx);
+      if (changeHandled) {
+        return;
+      }
+    }
+    if (options.onUpdate) {
+      await options.onUpdate(changeCtx);
+    }
+  };
+  if (options.debounce !== false) {
+    _fswatcher.on("all", debounce(onChange, options.debounce));
+  } else {
+    _fswatcher.on("all", onChange);
+  }
+  const utils = {
+    watchingFiles,
+    unwatch: async () => {
+      await _fswatcher.close();
+    }
+  };
+  return new Proxy(utils, {
+    get(_, prop) {
+      if (prop in utils) {
+        return utils[prop];
+      }
+      return config[prop];
+    }
+  });
+}
+
+export { createDefineConfig, loadConfig, loadDotenv, setupDotenv, watchConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c12",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Smart Config Loader",
   "repository": "unjs/c12",
   "license": "MIT",
@@ -30,12 +30,15 @@
     "test:types": "tsc --noEmit"
   },
   "dependencies": {
+    "chokidar": "^3.5.3",
     "defu": "^6.1.2",
     "dotenv": "^16.0.3",
     "giget": "^1.1.2",
     "jiti": "^1.18.2",
     "mlly": "^1.2.0",
+    "ohash": "^1.1.1",
     "pathe": "^1.1.0",
+    "perfect-debounce": "^0.1.3",
     "pkg-types": "^1.0.2",
     "rc9": "^2.1.0"
   },
@@ -50,5 +53,5 @@
     "unbuild": "^1.2.1",
     "vitest": "^0.30.1"
   },
-  "packageManager": "pnpm@8.2.0"
+  "packageManager": "pnpm@8.3.0"
 }