@rstackjs/load-config 0.1.1 → 1.0.0

package/README.md

@@ -13,13 +13,27 @@ A config loading utility for the Rstack ecosystem, designed for loading JavaScri
 ## Installation
 
 ```bash
+# pnpm
+pnpm add @rstackjs/load-config -D
+# yarn
+yarn add @rstackjs/load-config -D
+# npm
 npm add @rstackjs/load-config -D
+# bun
+bun add @rstackjs/load-config -D
 ```
 
 [jiti](https://github.com/unjs/jiti) is an optional peer dependency. Install it only when you use the `jiti` or `auto` loaders:
 
 ```bash
+# pnpm
+pnpm add jiti -D
+# yarn
+yarn add jiti -D
+# npm
 npm add jiti -D
+# bun
+bun add jiti -D
 ```
 
 ## Usage
@@ -221,6 +235,27 @@ await loadConfig({
 
 When using the `native` loader and `fresh` is enabled, `dependencies` contains absolute paths for files imported by the config file.
 
+### withConfigMeta
+
+Preserve the original config path and dependencies when loading through an adapter:
+
+```ts
+import { withConfigMeta } from '@rstackjs/load-config';
+
+const config = { name: 'my-tool' };
+
+export default withConfigMeta(config, {
+  filePath: '/project/project.config.ts',
+  dependencies: ['/project/shared.ts'],
+});
+```
+
+`loadConfig` uses the supplied `filePath` and merges `dependencies` with the adapter file and its collected dependencies, removing duplicates.
+
+- Use absolute paths. `filePath: null` means no underlying config was found; `dependencies` is optional.
+- The helper modifies and returns the original config object. Repeated calls replace its metadata. Frozen or non-extensible objects are not supported.
+- Call it on the final config object: object spread and JSON serialization discard the metadata.
+
 ## License
 
 [MIT](./LICENSE).

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 import type { LoadConfigOptions, LoadConfigResult } from './types.js';
-export type { ConfigDefinition, ConfigLoader, LoadConfigOptions, LoadConfigResult, } from './types.js';
+export { withConfigMeta } from './meta.js';
+export type { ConfigDefinition, ConfigFileMeta, ConfigLoader, LoadConfigOptions, LoadConfigResult, } from './types.js';
 export declare function loadConfig<Config = unknown, Params extends unknown[] = []>({ cwd, path, configFileNames, loader, exportName, configParams, fresh, }?: LoadConfigOptions<Params>): Promise<LoadConfigResult<Config>>;

package/dist/index.js

@@ -37,13 +37,23 @@ const loadWithJiti = async (configPath, exportName, fresh)=>{
         dependencies: []
     };
 };
+const CONFIG_META = Symbol.for('@rstackjs/load-config/meta');
+function withConfigMeta(config, meta) {
+    Object.defineProperty(config, CONFIG_META, {
+        configurable: true,
+        value: {
+            filePath: meta.filePath,
+            dependencies: [
+                ...meta.dependencies ?? []
+            ]
+        }
+    });
+    return config;
+}
+function getConfigMeta(config) {
+    if (null !== config && 'object' == typeof config && Object.hasOwn(config, CONFIG_META)) return config[CONFIG_META];
+}
 const JS_CONFIG_REGEXP = /\.(?:js|mjs|cjs)$/;
-const tryFreshImport = async (configFileURL)=>{
-    try {
-        const { freshImport } = await import("./freshImport.js");
-        return await freshImport(configFileURL);
-    } catch  {}
-};
 const loadWithNative = async (configPath, fresh)=>{
     const configFileURL = pathToFileURL(configPath).href;
     if (!fresh) {
@@ -53,7 +63,8 @@ const loadWithNative = async (configPath, fresh)=>{
             dependencies: []
         };
     }
-    const freshImportResult = await tryFreshImport(configFileURL);
+    const { freshImport } = await import("./freshImport.js");
+    const freshImportResult = await freshImport(configFileURL);
     if (freshImportResult) return {
         configModule: freshImportResult.result,
         dependencies: freshImportResult.dependencies.sort()
@@ -77,6 +88,7 @@ const resolveConfigPath = (root, customConfig, configFileNames = [])=>{
     return null;
 };
 async function loadConfig({ cwd = process.cwd(), path, configFileNames = [], loader = 'auto', exportName = 'default', configParams = [], fresh = false } = {}) {
+    if (!path && 0 === configFileNames.length) throw new Error('Either `path` or at least one `configFileNames` entry must be provided.');
     const configPath = resolveConfigPath(cwd, path, configFileNames);
     if (!configPath) return {
         content: {},
@@ -99,19 +111,28 @@ async function loadConfig({ cwd = process.cwd(), path, configFileNames = [], loa
     }
     if (!loadedConfig) loadedConfig = await loadWithJiti(configPath, exportName, fresh);
     const { configExport, dependencies } = loadedConfig;
+    let content;
     if (isConfigFunction(configExport)) {
         const result = await configExport(...configParams);
         if (void 0 === result) throw new Error('The config function must return a config object.');
-        return {
-            content: result,
-            filePath: configPath,
-            dependencies
-        };
-    }
-    return {
-        content: configExport,
+        content = result;
+    } else content = configExport;
+    const meta = getConfigMeta(content);
+    const result = {
+        content,
         filePath: configPath,
         dependencies
     };
+    if (meta) {
+        result.filePath = meta.filePath;
+        result.dependencies = [
+            ...new Set([
+                ...meta.dependencies ?? [],
+                configPath,
+                ...dependencies
+            ])
+        ];
+    }
+    return result;
 }
-export { loadConfig };
+export { loadConfig, withConfigMeta };

package/dist/meta.d.ts

@@ -0,0 +1,8 @@
+import type { ConfigFileMeta } from './types.js';
+/**
+ * Attach file metadata in place and return the original configuration object.
+ * Repeated calls replace the metadata. Requires an extensible, unfrozen object.
+ * Call this after merging the config: object spread does not preserve metadata.
+ */
+export declare function withConfigMeta<Config extends object>(config: Config, meta: ConfigFileMeta): Config;
+export declare function getConfigMeta(config: unknown): ConfigFileMeta | undefined;

package/dist/types.d.ts

@@ -14,7 +14,7 @@ export type LoadConfigOptions<Params extends unknown[] = []> = {
     path?: string;
     /**
      * Config file names to search in `cwd` when `path` is not provided.
-     * The package-level loader has no built-in framework defaults.
+     * Required when `path` is not provided.
      * @default []
      */
     configFileNames?: string[];
@@ -43,19 +43,33 @@ export type LoadConfigOptions<Params extends unknown[] = []> = {
      */
     fresh?: boolean;
 };
+export type ConfigFileMeta = {
+    /**
+     * Absolute path of the actual configuration file.
+     * Use `null` when no underlying configuration file was found.
+     */
+    filePath: string | null;
+    /**
+     * Absolute paths of additional configuration dependencies.
+     * These are merged with the adapter file and its collected dependencies.
+     */
+    dependencies?: readonly string[];
+};
 export type LoadConfigResult<Config = unknown> = {
     /**
      * The loaded configuration object.
      */
     content: Config;
     /**
-     * The path to the loaded configuration file.
-     * Return `null` if the configuration file is not found.
+     * The path to the loaded configuration file, or the source set by `withConfigMeta`.
+     * Returns `null` if no configuration file was found, including an explicit
+     * `null` source set by `withConfigMeta`.
      */
     filePath: string | null;
     /**
-     * Absolute file paths of statically imported (relative) dependencies of the
-     * config file.
+     * Absolute paths of collected configuration dependencies. When `withConfigMeta`
+     * is used, also includes explicit dependencies and the loaded adapter file,
+     * with duplicates removed.
      */
     dependencies: string[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rstackjs/load-config",
-  "version": "0.1.1",
+  "version": "1.0.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/rstackjs/load-config"
@@ -21,8 +21,7 @@
     "@types/node": "^24.13.2",
     "fresh-import": "^0.2.1",
     "jiti": "^2.7.0",
-    "prettier": "^3.9.4",
-    "rstack": "0.0.2",
+    "rstack": "^0.6.4",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
@@ -39,10 +38,11 @@
   },
   "scripts": {
     "build": "rs lib",
+    "check": "rs check --type-check",
     "dev": "rs lib -w",
-    "lint": "rs lint && prettier -c .",
-    "lint:write": "rs lint --fix && prettier -w .",
+    "format": "rs fmt",
+    "lint": "rs lint",
     "test": "rs test",
-    "bump": "pnpx bumpp"
+    "bump": "pnpm version -m \"release: v%s\""
   }
 }