@rstackjs/load-config 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Rspack Contrib
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# @rstackjs/load-config
+
+<p>
+  <a href="https://npmjs.com/package/@rstackjs/load-config">
+   <img src="https://img.shields.io/npm/v/@rstackjs/load-config?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" />
+  </a>
+  <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="license" />
+  <a href="https://npmcharts.com/compare/@rstackjs/load-config?minimal=true"><img src="https://img.shields.io/npm/dm/@rstackjs/load-config.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="downloads" /></a>
+</p>
+
+A config loading utility for the Rstack ecosystem, designed for loading JavaScript and TypeScript config files for projects like Rspack and Rsbuild.
+
+## Installation
+
+```bash
+npm 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
+npm add jiti -D
+```
+
+## Usage
+
+```ts
+import { loadConfig } from '@rstackjs/load-config';
+
+const result = await loadConfig<{ name: string }>({
+  cwd: process.cwd(),
+  configFileNames: ['my-tool.config.ts', 'my-tool.config.mjs'],
+});
+
+console.log(result.content);
+console.log(result.filePath);
+```
+
+Given a config file:
+
+```ts
+// my-tool.config.ts
+export default {
+  name: 'my-tool',
+};
+```
+
+`loadConfig` returns:
+
+```ts
+type LoadConfigResult<Config = unknown> = {
+  content: Config;
+  filePath: string | null;
+  dependencies: string[];
+};
+```
+
+If no config file is found, `content` is an empty object, `filePath` is `null`, and `dependencies` is an empty array.
+
+## Supported Exports
+
+Default object export:
+
+```ts
+export default {
+  name: 'my-tool',
+};
+```
+
+Function export:
+
+```ts
+export default ({ mode }) => {
+  return { mode };
+};
+```
+
+Async function export:
+
+```ts
+export default async ({ mode }) => {
+  return { mode };
+};
+```
+
+## API
+
+### loadConfig
+
+```ts
+function loadConfig<Config = unknown, Params extends unknown[] = []>(
+  options?: LoadConfigOptions<Params>,
+): Promise<LoadConfigResult<Config>>;
+```
+
+### Options
+
+#### cwd
+
+The root directory used to resolve config files.
+
+- Type: `string`
+- Default: `process.cwd()`
+
+#### path
+
+A relative or absolute path to a specific config file.
+
+- Type: `string`
+- Default: `undefined`
+
+When `path` is provided, the file must exist. Relative paths are resolved from `cwd`.
+
+```ts
+await loadConfig({
+  path: path.join(import.meta.dirname, 'custom.config.ts'),
+});
+```
+
+#### configFileNames
+
+A list of file names to search in `cwd` when `path` is not provided.
+
+- Type: `string[]`
+- Default: `[]`
+
+```ts
+await loadConfig({
+  configFileNames: [
+    'tool.config.ts',
+    'tool.config.mts',
+    'tool.config.js',
+    'tool.config.mjs',
+  ],
+});
+```
+
+#### loader
+
+Controls how the config file is loaded.
+
+- Type: `'auto' | 'jiti' | 'native'`
+- Default: `'auto'`
+
+`auto` uses the native loader when possible and falls back to `jiti`.
+
+JavaScript config files (`.js`, `.mjs`, `.cjs`) are always attempted with native dynamic import first; if native import fails and `loader` is not `native`, they fall back to `jiti`.
+
+TypeScript config files use the native loader in runtimes with TypeScript support, Bun, or Deno; otherwise they use `jiti`.
+
+Set `loader` to `native` to disable the `jiti` fallback.
+
+```ts
+await loadConfig({
+  path: 'tool.config.ts',
+  loader: 'native',
+});
+```
+
+#### exportName
+
+The export to read from the config module.
+
+- Type: `string | false`
+- Default: `'default'`
+
+Use a string to read a named export:
+
+```ts
+// tool.config.ts
+export const config = {
+  name: 'my-tool',
+};
+```
+
+```ts
+await loadConfig({
+  path: 'tool.config.ts',
+  exportName: 'config',
+});
+```
+
+Set `exportName` to `false` to execute the config file without reading exports. The returned `content` is an empty object.
+
+#### configParams
+
+Arguments passed to a function config export.
+
+- Type: `Params`
+- Default: `[]`
+
+```ts
+// tool.config.ts
+export default ({ mode }: { mode: string }) => ({
+  mode,
+});
+```
+
+```ts
+const result = await loadConfig<{ mode: string }, [{ mode: string }]>({
+  path: 'tool.config.ts',
+  configParams: [{ mode: 'production' }],
+});
+```
+
+Config functions may be async, but they must return a config object.
+
+#### fresh
+
+Bypasses module cache when loading the config.
+
+- Type: `boolean`
+- Default: `false`
+
+```ts
+await loadConfig({
+  path: 'tool.config.mjs',
+  fresh: true,
+});
+```
+
+When using the `native` loader and `fresh` is enabled, `dependencies` contains absolute paths for files imported by the config file.
+
+## License
+
+[MIT](./LICENSE).

package/dist/freshImport.js

@@ -0,0 +1,111 @@
+import { Module } from "node:module";
+import { fileURLToPath } from "node:url";
+import { MessageChannel } from "node:worker_threads";
+const instanceId = Math.random().toString(36).slice(2);
+const relativeImportRE = /^\.{1,2}(?:\/|\\)/;
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function buildQueryName() {
+    return `fresh-import-${instanceId}`;
+}
+function buildQueryRE(queryName) {
+    return new RegExp(`(?:\\?|&)${escapeRegExp(queryName)}=(\\d+),([^&]+)(?:&|$)`);
+}
+function formatTrackingQuery(queryName, id, context) {
+    return `?${queryName}=${id},${context}`;
+}
+function trackResolved(specifier, context, result, queryName, queryRE, onDependency) {
+    const isRelativeImport = relativeImportRE.test(specifier);
+    if ("builtin" === result.format || !isRelativeImport) return result;
+    if (!context.parentURL || queryRE.test(result.url) || !result.url.startsWith("file:")) return result;
+    const m = queryRE.exec(context.parentURL);
+    if (m) {
+        const [, id, contextFile] = m;
+        onDependency(contextFile, result.url);
+        result.url = result.url.replace(/(\?)|$/, (_n, n1)=>`?${queryName}=${id},${contextFile}${"?" === n1 ? "&" : ""}`);
+    }
+    return result;
+}
+var loader_default = 'data:text/javascript,Math.random().toString(36).slice(2);%0Aconst relativeImportRE = /^\\.{1,2}(%3F:\\/|\\\\)/;%0Afunction escapeRegExp(value) {%0A%09return value.replace(/[.*+%3F^${}()|[\\]\\\\]/g, "\\\\$&");%0A}%0A/**%0A* Build the regex that matches the tracking query `%3F<name>=<id>,<context>`%0A* (or the `&<name>=...` form).%0A*/%0Afunction buildQueryRE(queryName) {%0A%09return new RegExp(`(%3F:\\\\%3F|&)${escapeRegExp(queryName)}=(\\\\d+),([^&]+)(%3F:&|$)`);%0A}%0A/**%0A* Shared body of the resolve hook for both the on-thread and off-thread%0A* importers. Given an already-resolved `result`, decides whether it is a tracked%0A* relative file dependency; if so, reports it via `onDependency` and tags the%0A* URL so the query propagates to its own dependencies.%0A*%0A* The sync/async difference between the two hooks lives entirely in the caller%0A* (which awaits `nextResolve` or not); this function performs no I/O. `result`%0A* is mutated in place and returned.%0A*/%0Afunction trackResolved(specifier, context, result, queryName, queryRE, onDependency) {%0A%09const isRelativeImport = relativeImportRE.test(specifier);%0A%09if (result.format === "builtin" || !isRelativeImport) return result;%0A%09if (!context.parentURL || queryRE.test(result.url) || !result.url.startsWith("file:")) return result;%0A%09const m = queryRE.exec(context.parentURL);%0A%09if (m) {%0A%09%09const [, id, contextFile] = m;%0A%09%09onDependency(contextFile, result.url);%0A%09%09result.url = result.url.replace(/(\\%3F)|$/, (_n, n1) => `%3F${queryName}=${id},${contextFile}${n1 === "%3F" %3F "&" : ""}`);%0A%09}%0A%09return result;%0A}%0A//%23endregion%0A//%23region src/off-thread/loader.ts%0Alet port;%0Alet queryName;%0Alet queryRE;%0Aconst initialize = async (data) => {%0A%09port = data.port;%0A%09queryName = data.queryName;%0A%09queryRE = buildQueryRE(queryName);%0A};%0Aconst resolve = async (specifier, context, nextResolve) => {%0A%09return trackResolved(specifier, context, await nextResolve(specifier, context), queryName, queryRE, (ctx, url) => {%0A%09%09port.postMessage({%0A%09%09%09context: ctx,%0A%09%09%09url%0A%09%09});%0A%09});%0A};%0A//%23endregion%0Aexport { initialize, resolve };%0A';
+let nextId$1 = 0;
+function createOffThreadImporter() {
+    const queryName = buildQueryName();
+    const { port1, port2 } = new MessageChannel();
+    Module.register(loader_default, {
+        data: {
+            port: port2,
+            queryName
+        },
+        transferList: [
+            port2
+        ]
+    });
+    port1.unref();
+    return {
+        async collect (specifier) {
+            const id = nextId$1++;
+            const depsList = /* @__PURE__ */ new Set();
+            const onMessage = (e)=>{
+                if (e.context === specifier) depsList.add(e.url);
+            };
+            port1.on("message", onMessage);
+            port1.unref();
+            try {
+                const result = await import(specifier + formatTrackingQuery(queryName, id, specifier));
+                await new Promise((resolve)=>setImmediate(resolve));
+                return {
+                    result,
+                    dependencies: [
+                        ...depsList
+                    ].filter((url)=>url.startsWith("file:")).map((url)=>fileURLToPath(url))
+                };
+            } finally{
+                port1.off("message", onMessage);
+            }
+        }
+    };
+}
+let nextId = 0;
+function createOnThreadImporter() {
+    const registry = /* @__PURE__ */ new Map();
+    const queryName = buildQueryName();
+    const queryRE = buildQueryRE(queryName);
+    const resolve = (specifier, context, nextResolve)=>trackResolved(specifier, context, nextResolve(specifier, context), queryName, queryRE, (ctx, url)=>{
+            registry.get(ctx)?.add(url);
+        });
+    Module.registerHooks({
+        resolve
+    });
+    return {
+        async collect (specifier) {
+            const id = nextId++;
+            const depsList = /* @__PURE__ */ new Set();
+            registry.set(specifier, depsList);
+            try {
+                return {
+                    result: await import(specifier + formatTrackingQuery(queryName, id, specifier)),
+                    dependencies: [
+                        ...depsList
+                    ].filter((url)=>url.startsWith("file:")).map((url)=>fileURLToPath(url))
+                };
+            } finally{
+                registry.delete(specifier);
+            }
+        }
+    };
+}
+function createImporter() {
+    if (Module.registerHooks) return createOnThreadImporter();
+    if (Module.register) return createOffThreadImporter();
+}
+let importer;
+let initialized = false;
+function freshImport(specifier) {
+    if (!initialized) {
+        importer = createImporter();
+        initialized = true;
+    }
+    return importer?.collect(specifier);
+}
+export { freshImport };

package/dist/helpers.d.ts

@@ -0,0 +1,3 @@
+import type { ConfigDefinition, ConfigFunction } from './types.js';
+export declare const isConfigFunction: <Config, Params extends unknown[]>(configExport: ConfigDefinition<Config, Params>) => configExport is ConfigFunction<Config, Params>;
+export declare const getConfigExport: <Config, Params extends unknown[]>(configModule: unknown, exportName: string | false, configPath: string) => ConfigDefinition<Config, Params>;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { LoadConfigOptions, LoadConfigResult } from './types.js';
+export type { ConfigDefinition, 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

@@ -0,0 +1,117 @@
+import { pathToFileURL } from "node:url";
+import node_fs from "node:fs";
+import { isAbsolute, join } from "node:path";
+const canReadExport = (module)=>null !== module && ('object' == typeof module || 'function' == typeof module);
+const isConfigFunction = (configExport)=>'function' == typeof configExport;
+const getConfigExport = (configModule, exportName, configPath)=>{
+    if (false === exportName) return {};
+    if ('default' === exportName) return canReadExport(configModule) && 'default' in configModule ? configModule.default : configModule;
+    if (canReadExport(configModule) && Object.hasOwn(configModule, exportName)) return configModule[exportName];
+    throw new Error(`Cannot find export ${exportName} in config file: ${configPath}`);
+};
+const loadWithJiti = async (configPath, exportName, fresh)=>{
+    let createJiti;
+    try {
+        ({ createJiti } = await import("jiti"));
+    } catch (error) {
+        throw new Error('The "jiti" package is required to load this config. Install it with your package manager.', {
+            cause: error
+        });
+    }
+    const jiti = createJiti(configPath, {
+        moduleCache: !fresh,
+        interopDefault: true,
+        nativeModules: [
+            "typescript"
+        ]
+    });
+    if ('default' === exportName) return {
+        configExport: await jiti.import(configPath, {
+            default: true
+        }),
+        dependencies: []
+    };
+    const configModule = await jiti.import(configPath);
+    return {
+        configExport: getConfigExport(configModule, exportName, configPath),
+        dependencies: []
+    };
+};
+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) {
+        const configModule = await import(configFileURL);
+        return {
+            configModule,
+            dependencies: []
+        };
+    }
+    const freshImportResult = await tryFreshImport(configFileURL);
+    if (freshImportResult) return {
+        configModule: freshImportResult.result,
+        dependencies: freshImportResult.dependencies.sort()
+    };
+    const configModule = await import(`${configFileURL}?t=${Date.now()}`);
+    return {
+        configModule,
+        dependencies: []
+    };
+};
+const resolveConfigPath = (root, customConfig, configFileNames = [])=>{
+    if (customConfig) {
+        const customConfigPath = isAbsolute(customConfig) ? customConfig : join(root, customConfig);
+        if (node_fs.existsSync(customConfigPath)) return customConfigPath;
+        throw new Error(`Cannot find config file: ${customConfigPath}`);
+    }
+    for (const file of configFileNames){
+        const configFile = join(root, file);
+        if (node_fs.existsSync(configFile)) return configFile;
+    }
+    return null;
+};
+async function loadConfig({ cwd = process.cwd(), path, configFileNames = [], loader = 'auto', exportName = 'default', configParams = [], fresh = false } = {}) {
+    const configPath = resolveConfigPath(cwd, path, configFileNames);
+    if (!configPath) return {
+        content: {},
+        filePath: configPath,
+        dependencies: []
+    };
+    let loadedConfig;
+    const useNative = Boolean('native' === loader || 'auto' === loader && (process.features.typescript || process.versions.bun || process.versions.deno));
+    if (useNative || JS_CONFIG_REGEXP.test(configPath)) {
+        let result;
+        try {
+            result = await loadWithNative(configPath, fresh);
+        } catch (err) {
+            if ('native' === loader) throw err;
+        }
+        if (result) loadedConfig = {
+            configExport: getConfigExport(result.configModule, exportName, configPath),
+            dependencies: result.dependencies
+        };
+    }
+    if (!loadedConfig) loadedConfig = await loadWithJiti(configPath, exportName, fresh);
+    const { configExport, dependencies } = loadedConfig;
+    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,
+        filePath: configPath,
+        dependencies
+    };
+}
+export { loadConfig };

package/dist/jiti.d.ts

@@ -0,0 +1,2 @@
+import type { LoadedConfig } from './types.js';
+export declare const loadWithJiti: <Config, Params extends unknown[]>(configPath: string, exportName: string | false, fresh: boolean) => Promise<LoadedConfig<Config, Params>>;

package/dist/native.d.ts

@@ -0,0 +1,7 @@
+type NativeLoadResult = {
+    configModule: unknown;
+    dependencies: string[];
+};
+export declare const JS_CONFIG_REGEXP: RegExp;
+export declare const loadWithNative: (configPath: string, fresh: boolean) => Promise<NativeLoadResult>;
+export {};

package/dist/resolve.d.ts

@@ -0,0 +1 @@
+export declare const resolveConfigPath: (root: string, customConfig?: string, configFileNames?: string[]) => string | null;

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+export type ConfigLoader = 'auto' | 'jiti' | 'native';
+export type ConfigFunction<Config, Params extends unknown[]> = (...params: Params) => Config | Promise<Config>;
+export type ConfigDefinition<Config, Params extends unknown[]> = Config | ConfigFunction<Config, Params>;
+export type LoadConfigOptions<Params extends unknown[] = []> = {
+    /**
+     * The root path to resolve the config file.
+     * @default process.cwd()
+     */
+    cwd?: string;
+    /**
+     * The path to the config file, can be a relative or absolute path.
+     * If `path` is not provided, the function will search for the config file in the `cwd`.
+     */
+    path?: string;
+    /**
+     * Config file names to search in `cwd` when `path` is not provided.
+     * The package-level loader has no built-in framework defaults.
+     * @default []
+     */
+    configFileNames?: string[];
+    /**
+     * Specify the config loader, can be `auto`, `jiti` or `native`.
+     * @default 'auto'
+     */
+    loader?: ConfigLoader;
+    /**
+     * The export name to read from the config file.
+     * Set to `false` to execute the config file without reading exports.
+     * @default 'default'
+     */
+    exportName?: string | false;
+    /**
+     * Arguments passed to a function config export.
+     * @default []
+     */
+    configParams?: Params;
+    /**
+     * Whether to bypass module cache when loading the config.
+     * @default false
+     */
+    fresh?: boolean;
+};
+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.
+     */
+    filePath: string | null;
+    /**
+     * Absolute file paths of statically imported (relative) dependencies of the
+     * config file.
+     */
+    dependencies: string[];
+};
+export type LoadedConfig<Config, Params extends unknown[]> = {
+    configExport: ConfigDefinition<Config, Params>;
+    dependencies: string[];
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@rstackjs/load-config",
+  "version": "0.0.0",
+  "repository": "https://github.com/rstackjs/load-config",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rs lib",
+    "dev": "rs lib -w",
+    "lint": "rs lint && prettier -c .",
+    "lint:write": "rs lint --fix && prettier -w .",
+    "test": "rs test",
+    "bump": "pnpx bumpp"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.2",
+    "fresh-import": "^0.2.1",
+    "jiti": "^2.7.0",
+    "prettier": "^3.9.4",
+    "rstack": "0.0.2",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "jiti": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "jiti": {
+      "optional": true
+    }
+  },
+  "packageManager": "pnpm@11.9.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}