@equinor/fusion-imports 1.1.12-next.0 → 2.0.0

package/README.md

@@ -1,116 +1,166 @@
-# Fusion Imports
+# @equinor/fusion-imports
 
-This package provides utility functions for handling imports.
+Utilities for importing and transpiling TypeScript, JavaScript, and JSON configuration files at **Node.js runtime** using [esbuild](https://esbuild.github.io/).
 
-> [!important]
-> This module is meant for usage of __file__ content, not __url__
+> [!IMPORTANT]
+> This package works with **file paths**, not URLs. It is designed for loading configuration scripts at runtime in Node.js CLI tools and build pipelines.
 
-## Usage
+## Installation
 
-This module is primary for loading configuration from scripts runtime.
+```bash
+pnpm add @equinor/fusion-imports
+```
+
+## When to use
 
-### importConfig
+| Scenario | Function |
+|---|---|
+| Load a config by basename, auto-resolving `.ts` → `.js` → `.json` | `importConfig` |
+| Bundle & import a single TypeScript/JS module at runtime | `importScript` |
+| Read and parse a JSON file from disk | `importJSON` |
+| Find the first accessible config file for a basename | `resolveConfigFile` |
 
-`importConfig` will resolve the provided basename by looking for `TypeScript`, then `JavaScript` and then `json`. Internally it will call [importScript](#importscript) and [importJSON](#importjson)
+## Quick start
 
-```ts
+```typescript
 import { importConfig } from '@equinor/fusion-imports';
 
-type MyConfig {
+interface AppSettings {
   name: string;
-  bar: {
-    foobar: number;
-  }
-};
-
-type ScriptModule = {
-  generateConfig: (options: any) => MyConfig;
+  port: number;
 }
 
-const config = importConfig('my-config', {
-  script: {
-    resolve: (module: ScriptModule) => {
-      return module.generateConfig(someOptions);
-    }
-  }
-});
+// Resolves app.config.ts → app.config.js → app.config.json
+const { config, path } = await importConfig<AppSettings>('app.config');
+console.log(`Loaded ${path}:`, config);
 ```
 
-__example file: `./my-config.ts`__
-```ts
-import { base } from './baseConfig.ts'
+## API
 
-export function generateConfig(options: any): MyConfig {
-  return {
-    name: 'foo'
-    ...base(options)
-  }
+### `importConfig<C>(basename, options?)`
+
+Resolves a configuration file by basename, probing extensions in order (`.ts`, `.mjs`, `.js`, `.json`). JSON files are parsed directly; script files are bundled with esbuild and dynamically imported.
+
+```typescript
+import { importConfig } from '@equinor/fusion-imports';
+
+interface MyConfig {
+  name: string;
+  bar: { foobar: number };
 }
+
+interface ScriptModule {
+  generateConfig: (options: { env: string }) => MyConfig;
+}
+
+const { config } = await importConfig<MyConfig, ScriptModule>('my-config', {
+  script: {
+    resolve: (module) => module.generateConfig({ env: 'production' }),
+  },
+});
 ```
 
-#### resolve
+By default the module's `default` export is used as the config value. Provide `script.resolve` to extract a different export or call a factory function.
 
-`importConfig` will try to resolve `module.default` as default
+#### Options
 
-```ts
-// my-script.ts
-const config = importConfig<number>('my-config');
+| Option | Type | Description |
+|---|---|---|
+| `baseDir` | `string` | Base directory for file resolution (default: `process.cwd()`) |
+| `extensions` | `string[]` | Extensions to probe (default: `['.ts', '.mjs', '.js', '.json']`) |
+| `script.resolve` | `(module) => C` | Extracts the config value from the imported module |
+| `script.esBuildOptions` | `ImportScriptOptions` | Esbuild overrides forwarded to `importScript` |
 
-// my-config.ts
-export default 1;
-```
+### `importScript<M>(entryPoint, options?)`
 
-### importScript
+Bundles a TypeScript or JavaScript file with esbuild (ESM, external packages) and dynamically imports the output. Two built-in esbuild plugins are included automatically:
 
-Method for loading a script module. This function will use `EsBuild` under the hood, which is useful for loading external script within runtime of other script since it will transpile within the context of the target script.
+- **`importMetaResolvePlugin`** — resolves `import.meta.resolve()` calls for relative paths at build time.
+- **`rawMarkdownPlugin`** — supports `?raw` imports for `.md` / `.mdx` files.
 
-#### EsBuild
+```typescript
+import { importScript } from '@equinor/fusion-imports';
 
-`ImportScriptOptions` is a restricted set of `EsBuild.BuildOptions` which means that you could provide options for compiling the import content.
+interface Greeting { greet(name: string): string }
+const mod = await importScript<Greeting>('./greet.ts');
+console.log(mod.greet('World'));
+```
 
-**plugins**
+#### Esbuild customisation
 
-our implementation does not use any plugins, but working with mono-repos you most likely need to add plugins like:
-- [esbuild-plugin-alias](https://www.npmjs.com/package/esbuild-plugin-alias)
-- [esbuild-plugin-tsc](https://www.npmjs.com/package/esbuild-plugin-tsc)
-- [...more](https://github.com/esbuild/community-plugins)
+`ImportScriptOptions` inherits all `esbuild.BuildOptions` except `entryPoints`, `bundle`, and `format`. You can pass custom plugins, define aliases, or change the output directory:
 
+```typescript
+import { importScript } from '@equinor/fusion-imports';
+import alias from 'esbuild-plugin-alias';
 
-### importJSON
+const mod = await importScript('./entry.ts', {
+  plugins: [alias({ '@app': './src' })],
+  outfile: '/tmp/bundle.js',
+});
+```
 
-Method for loading json from disk. Will read content and parse.
+### `importJSON<T>(filePath, encoding?)`
 
-### Plugins
+Reads a JSON file from disk and returns the parsed content. Throws with the original error as `cause` if the file is unreadable or contains invalid JSON.
+
+```typescript
+import { importJSON } from '@equinor/fusion-imports';
 
-The `importScript` function includes built-in plugins to handle common import scenarios:
+interface Manifest { name: string; version: string }
+const manifest = await importJSON<Manifest>('./package.json');
+```
 
-#### createMarkdownRawPlugin
+### `resolveConfigFile(baseName, options?)`
 
-Creates an esbuild plugin that handles `?raw` imports for markdown files. This plugin is automatically included when using `importScript`, but can also be used independently.
+Returns the absolute path of the first accessible configuration file matching the given basename and extension list. Useful when you need the path without importing the file.
 
-```ts
-import { importScript, createMarkdownRawPlugin } from '@equinor/fusion-imports';
+```typescript
+import { resolveConfigFile } from '@equinor/fusion-imports';
 
-// The plugin is automatically included, but you can also add it explicitly
-const module = await importScript('./my-script.ts', {
-  plugins: [createMarkdownRawPlugin()],
+const configPath = await resolveConfigFile('app.config', {
+  baseDir: '/project',
+  extensions: ['.ts', '.json'],
 });
 ```
 
-**Usage in imported files:**
+### Plugins
 
-```ts
-// my-script.ts
-import readmeContent from '../../README.md?raw';
+#### `rawMarkdownPlugin(options?)`
 
-export default readmeContent; // Returns the raw markdown content as a string
+Esbuild plugin that intercepts `?raw` imports for markdown files and returns
+their content as a default-exported string. Included automatically by `importScript`.
+
+```typescript
+// In a file bundled by importScript:
+import readme from '../../README.md?raw';
+console.log(readme); // raw markdown string
 ```
 
-The plugin:
-- Intercepts imports ending with `?raw`
-- Resolves paths relative to the importing file (handles `../` correctly)
-- Reads the file content and exports it as a default string export
+#### `createImportMetaResolvePlugin()`
+
+Esbuild plugin that replaces `import.meta.resolve('./relative')` calls with
+resolved `file://` URLs at build time. Included automatically by `importScript`.
+
+### Error handling
+
+The package provides two error classes for filesystem failures:
 
-#### createImportMetaResolvePlugin
+| Error | Thrown when |
+|---|---|
+| `FileNotFoundError` | File does not exist (`ENOENT`) |
+| `FileNotAccessibleError` | File exists but cannot be read (`EACCES`, `EISDIR`) |
 
-Creates an esbuild plugin that handles `import.meta.resolve()` calls. This plugin is automatically included when using `importScript`.
+Both extend `Error` and attach the original Node.js error as `cause`:
+
+```typescript
+import { importConfig, FileNotFoundError } from '@equinor/fusion-imports';
+
+try {
+  await importConfig('missing');
+} catch (error) {
+  if (error instanceof FileNotFoundError) {
+    console.error('Config not found:', error.message);
+  }
+}
+```

package/dist/esm/error.js

@@ -1,10 +1,20 @@
 /**
- * Represents an error that is thrown when a specified file cannot be found.
+ * Error thrown when a file cannot be found on disk (e.g. ENOENT).
  *
- * @extends {Error}
+ * Thrown by {@link processAccessError} when the underlying `fs` error code is
+ * `ENOENT`. Callers can use `instanceof FileNotFoundError` to distinguish
+ * "missing" from "permission denied" failures.
  *
- * @param message - A descriptive message providing details about the missing file.
- * @param options - Optional error options that can be used to provide additional context.
+ * @example
+ * ```typescript
+ * try {
+ *   await resolveConfigFile('app.config');
+ * } catch (error) {
+ *   if (error instanceof FileNotFoundError) {
+ *     console.error('Config file does not exist');
+ *   }
+ * }
+ * ```
  */
 export class FileNotFoundError extends Error {
     constructor(message, options) {
@@ -13,11 +23,11 @@ export class FileNotFoundError extends Error {
     }
 }
 /**
- * Represents an error that occurs when a file is not accessible.
+ * Error thrown when a file exists but cannot be accessed (e.g. EACCES or EISDIR).
  *
- * @extends Error
- * @param message - A descriptive message providing details about the error.
- * @param options - Optional error options that can include additional metadata or cause information.
+ * Thrown by {@link processAccessError} for permission or path-type errors.
+ * Callers can use `instanceof FileNotAccessibleError` to distinguish
+ * access failures from missing-file failures.
  */
 export class FileNotAccessibleError extends Error {
     constructor(message, options) {
@@ -26,14 +36,12 @@ export class FileNotAccessibleError extends Error {
     }
 }
 /**
- * Processes an access error and throws a specific error based on the error code.
+ * Converts a raw `fs` access error into a typed {@link FileNotFoundError},
+ * {@link FileNotAccessibleError}, or generic `Error` based on the errno code.
  *
- * @param error - The error object to process, typically of type `unknown`.
- * @param path - The file path associated with the error.
- *
- * @throws FileNotFoundError - If the error code is `ENOENT`, indicating the file was not found.
- * @throws FileNotAccessibleError - If the error code is `EACCES`, indicating the file is not accessible.
- * @throws Error - For any other error codes, indicating an unknown error occurred.
+ * @param error - The caught error, typically a `NodeJS.ErrnoException`.
+ * @param path  - Absolute or relative file path that triggered the error.
+ * @returns A typed error instance with the original error set as `cause`.
  */
 export const processAccessError = (error, path) => {
     switch (error.code) {

package/dist/esm/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAc,EAAE,IAAY,EAAS,EAAE;IACxE,QAAS,KAA+B,CAAC,IAAI,EAAE,CAAC;QAC9C,KAAK,QAAQ;YACX,OAAO,IAAI,iBAAiB,CAAC,mBAAmB,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5E,KAAK,QAAQ;YACX,OAAO,IAAI,sBAAsB,CAAC,wBAAwB,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QACtF,KAAK,QAAQ;YACX,OAAO,IAAI,sBAAsB,CAAC,wBAAwB,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QACtF;YACE,OAAO,IAAI,KAAK,CAAC,4BAA4B,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3E,CAAC;AACH,CAAC,CAAC"}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAc,EAAE,IAAY,EAAS,EAAE;IACxE,QAAS,KAA+B,CAAC,IAAI,EAAE,CAAC;QAC9C,KAAK,QAAQ;YACX,OAAO,IAAI,iBAAiB,CAAC,mBAAmB,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5E,KAAK,QAAQ;YACX,OAAO,IAAI,sBAAsB,CAAC,wBAAwB,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QACtF,KAAK,QAAQ;YACX,OAAO,IAAI,sBAAsB,CAAC,wBAAwB,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QACtF;YACE,OAAO,IAAI,KAAK,CAAC,4BAA4B,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3E,CAAC;AACH,CAAC,CAAC"}

package/dist/esm/import-config.js

@@ -3,20 +3,31 @@ import { importScript } from './import-script.js';
 import { importJSON } from './import-json.js';
 import { resolveConfigFile } from './resolve-config-file.js';
 /**
- * Imports a configuration file based on the provided basename and options.
+ * Loads a configuration file by basename, automatically resolving the file
+ * extension (`.ts` → `.mjs` → `.js` → `.json`) and using the appropriate
+ * import strategy.
  *
- * @template C - The type of the configuration content.
- * @template M - The type of the ES module, defaults to `EsmModule`.
+ * - **JSON files** are read and parsed with {@link importJSON}.
+ * - **Script files** (TypeScript / JavaScript) are bundled with esbuild via
+ *   {@link importScript} and the module's `default` export is returned unless
+ *   a custom `script.resolve` callback is provided.
  *
- * @param {string} basename - The base name of the configuration file to import.
- * @param {ImportConfigOptions<C, M>} [options={}] - Optional parameters for importing the configuration.
- * @param {string} [options.baseDir] - The base directory to resolve the configuration file from.
- * @param {string[]} [options.extensions] - The list of file extensions to consider when resolving the configuration file.
- * @param {object} [options.script] - Additional script options for importing non-JSON files.
+ * @template C - The configuration value type.
+ * @template M - The shape of the ES module when importing a script file.
  *
- * @returns {Promise<C>} A promise that resolves to the imported configuration content.
+ * @param basename  - File basename (without extension), or an array of
+ *   basenames to try in order.
+ * @param options   - Import behaviour overrides (base directory, extensions,
+ *   script resolver, esbuild options).
+ * @returns An {@link ImportConfigResult} containing the resolved path,
+ *   extension, and loaded configuration value.
+ * @throws {FileNotFoundError} When no matching file is found for any basename.
+ * @throws {Error} When esbuild bundling or JSON parsing fails.
  *
- * @throws Will throw an error if the configuration file cannot be resolved or imported.
+ * @example
+ * ```typescript
+ * const { config } = await importConfig<AppSettings>('app.config');
+ * ```
  */
 export async function importConfig(basename, options = {}) {
     const { baseDir, extensions, script } = options;

package/dist/esm/import-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"import-config.js","sourceRoot":"","sources":["../../src/import-config.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAA4C,MAAM,oBAAoB,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAmC7D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAA2B,EAC3B,UAAqC,EAAE;IAEvC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAChD,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEvC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE;QAC/B,QAAQ,OAAO,EAAE,CAAC;YAChB,KAAK,OAAO;gBACV,OAAO,UAAU,CAAI,QAAQ,CAAC,CAAC;YACjC,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,CAAC,CAAC,MAAS,EAAE,EAAE,CAAC,MAAM,CAAC,OAAY,CAAC,CAAC;gBACxE,MAAM,MAAM,GAAG,MAAM,YAAY,CAAI,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;gBACvE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IACL,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,SAAS,EAAE,OAAO;QAClB,MAAM;KACP,CAAC;AACJ,CAAC;AAED,eAAe,YAAY,CAAC"}
+{"version":3,"file":"import-config.js","sourceRoot":"","sources":["../../src/import-config.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAA4C,MAAM,oBAAoB,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAoD7D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAA2B,EAC3B,UAAqC,EAAE;IAEvC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAChD,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEvC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE;QAC/B,QAAQ,OAAO,EAAE,CAAC;YAChB,KAAK,OAAO;gBACV,OAAO,UAAU,CAAI,QAAQ,CAAC,CAAC;YACjC,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,CAAC,CAAC,MAAS,EAAE,EAAE,CAAC,MAAM,CAAC,OAAY,CAAC,CAAC;gBACxE,MAAM,MAAM,GAAG,MAAM,YAAY,CAAI,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;gBACvE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IACL,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,SAAS,EAAE,OAAO;QAClB,MAAM;KACP,CAAC;AACJ,CAAC;AAED,eAAe,YAAY,CAAC"}

package/dist/esm/import-json.js

@@ -1,11 +1,23 @@
 import { readFile } from 'node:fs/promises';
 /**
- * Asynchronously imports and parses a JSON file.
+ * Reads a JSON file from disk and returns the parsed content.
  *
- * @template T - The expected type of the parsed JSON content. It can be a record, string, or number.
- * @param {string} filePath - The path to the JSON file to be imported.
- * @returns {Promise<T>} A promise that resolves to the parsed JSON content.
- * @throws {Error} If the file cannot be read or the content is not valid JSON.
+ * Use this when you need to load a plain JSON configuration file without
+ * esbuild transpilation. For mixed TypeScript / JSON config resolution,
+ * prefer {@link importConfig}.
+ *
+ * @template T - Expected shape of the parsed JSON. Constrained to valid JSON value types.
+ * @param filePath  - Absolute or relative path to the `.json` file.
+ * @param encoding  - Character encoding used when reading the file (default `'utf-8'`).
+ * @returns The parsed JSON content cast to `T`.
+ * @throws {Error} When the file cannot be read or contains invalid JSON, with
+ *   the original error attached as `cause`.
+ *
+ * @example
+ * ```typescript
+ * interface AppManifest { name: string; version: string }
+ * const manifest = await importJSON<AppManifest>('./app.manifest.json');
+ * ```
  */
 export const importJSON = async (filePath, encoding = 'utf-8') => {
     try {

package/dist/esm/import-json.js.map

@@ -1 +1 @@
-{"version":3,"file":"import-json.js","sourceRoot":"","sources":["../../src/import-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAI5C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAC7B,QAAgB,EAChB,WAA2B,OAAO,EACtB,EAAE;IACd,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,oCAAoC,QAAQ,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACrF,CAAC;AACH,CAAC,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"import-json.js","sourceRoot":"","sources":["../../src/import-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAK5C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAC7B,QAAgB,EAChB,WAA2B,OAAO,EACtB,EAAE;IACd,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,oCAAoC,QAAQ,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACrF,CAAC;AACH,CAAC,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/esm/import-meta-resolve-plugin.js

@@ -1,10 +1,15 @@
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 /**
- * Transforms import.meta.resolve() calls in code to resolved file:// URLs
- * @param code - The code to transform
- * @param baseDir - The base directory for resolving relative paths
- * @returns The transformed code
+ * Replaces `import.meta.resolve('./relative')` calls in source code with
+ * static `file://` URLs resolved against `baseDir`.
+ *
+ * Only relative specifiers (starting with `./` or `../`) are transformed;
+ * bare package specifiers are left untouched.
+ *
+ * @param code    - Source code string to transform.
+ * @param baseDir - Directory used to resolve relative specifiers.
+ * @returns The transformed source code.
  */
 function transformImportMetaResolve(code, baseDir) {
     return code.replace(/import\.meta\.resolve\((['"`])([^'"`]+)\1\)/g, (match, quote, specifier) => {
@@ -24,7 +29,11 @@ function transformImportMetaResolve(code, baseDir) {
     });
 }
 /**
- * Gets the appropriate esbuild loader for a file extension
+ * Returns the esbuild loader name matching the file extension, or `undefined`
+ * for unsupported extensions.
+ *
+ * @param filePath - File path to inspect.
+ * @returns The loader identifier, or `undefined`.
  */
 function getLoader(filePath) {
     const ext = path.extname(filePath);
@@ -40,7 +49,10 @@ function getLoader(filePath) {
     return undefined;
 }
 /**
- * Safely reads a file, returning undefined on error
+ * Reads a file and returns its content, or `undefined` if reading fails.
+ *
+ * @param filePath - Absolute path to read.
+ * @returns File content or `undefined` on any I/O error.
  */
 async function readFileSafe(filePath) {
     try {
@@ -52,7 +64,12 @@ async function readFileSafe(filePath) {
     }
 }
 /**
- * Collects output files from esbuild result (handles both write: true and write: false)
+ * Gathers JavaScript output files from an esbuild `BuildResult`, supporting
+ * both in-memory (`write: false`) and on-disk (`write: true` with metafile)
+ * modes.
+ *
+ * @param result - The esbuild build result.
+ * @returns Array of `{ path, text }` objects for each `.js` / `.mjs` output.
  */
 async function collectOutputFiles(result) {
     const files = [];
@@ -86,13 +103,31 @@ async function collectOutputFiles(result) {
     return files;
 }
 /**
- * Creates an esbuild plugin that transforms `import.meta.resolve()` calls
- * to resolved file:// URLs at build time.
+ * Creates an esbuild plugin that statically resolves `import.meta.resolve()`
+ * calls for relative paths at build time.
+ *
+ * Esbuild does not handle `import.meta.resolve()` during bundling — it
+ * preserves the calls as runtime expressions. This plugin intercepts source
+ * files and bundled output to replace relative-path calls with pre-resolved
+ * `file://` URLs, ensuring they work correctly in the final bundle.
+ *
+ * The plugin is included automatically by {@link importScript} but can be
+ * added explicitly to a custom esbuild configuration.
+ *
+ * @returns An esbuild `Plugin` instance.
+ *
+ * @example
+ * ```typescript
+ * import { build } from 'esbuild';
+ * import { createImportMetaResolvePlugin } from '@equinor/fusion-imports';
  *
- * This plugin is necessary because esbuild doesn't handle `import.meta.resolve()`
- * calls during bundling - it leaves them as runtime calls. For local imports
- * (relative paths), we need to resolve them at build time so they work correctly
- * in the bundled output.
+ * await build({
+ *   entryPoints: ['src/index.ts'],
+ *   plugins: [createImportMetaResolvePlugin()],
+ *   bundle: true,
+ *   format: 'esm',
+ * });
+ * ```
  */
 export const importMetaResolvePlugin = () => {
     return {

package/dist/esm/import-meta-resolve-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"import-meta-resolve-plugin.js","sourceRoot":"","sources":["../../src/import-meta-resolve-plugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"import-meta-resolve-plugin.js","sourceRoot":"","sources":["../../src/import-meta-resolve-plugin.ts"],"names":[],"mappings":"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"}

package/dist/esm/import-script.js

@@ -7,22 +7,30 @@ import { readPackageUp } from 'read-package-up';
 import { importMetaResolvePlugin } from './import-meta-resolve-plugin.js';
 import { rawMarkdownPlugin } from './markdown-plugin.js';
 /**
- * Asynchronously imports a script file using esbuild to bundle it.
+ * Bundles a TypeScript or JavaScript file with esbuild and dynamically imports
+ * the resulting ESM module.
  *
- * @template M - The type of the module to be imported.
- * @param {string} entryPoint - The path to the script file to be imported.
- * @param {ImportScriptOptions} [options] - Optional build options to customize the bundling process.
- * @returns {Promise<M>} A promise that resolves to the imported module.
- * @throws {Error} Throws an error if the bundling process fails or no output files are generated.
+ * The function resolves the entry point, bundles it in ESM format with all
+ * npm packages marked as external, and loads the output via `import()`. Two
+ * built-in esbuild plugins are included automatically:
+ *
+ * - {@link createImportMetaResolvePlugin | importMetaResolvePlugin} — resolves
+ *   `import.meta.resolve()` calls for relative paths at build time.
+ * - {@link rawMarkdownPlugin} — supports `?raw` imports for markdown files.
+ *
+ * @template M - Module shape returned by the dynamic import.
+ * @param entryPoint - Path to the script file to bundle and import.
+ * @param options    - Optional esbuild build options (see {@link ImportScriptOptions}).
+ * @returns The imported module.
+ * @throws {FileNotFoundError} When the entry point does not exist.
+ * @throws {FileNotAccessibleError} When the entry point cannot be read.
+ * @throws {Error} When esbuild bundling fails or produces no output.
  *
  * @example
  * ```typescript
- * import { importScript } from './import-script';
- *
- * (async () => {
- *   const myModule = await importScript<MyModuleType>('./path/to/my-module.ts');
- *   // Use myModule here
- * })();
+ * interface MyModule { greet(name: string): string }
+ * const mod = await importScript<MyModule>('./greet.ts');
+ * console.log(mod.greet('World'));
  * ```
  */
 export const importScript = async (entryPoint, options) => {

package/dist/esm/import-script.js.map

@@ -1 +1 @@
-{"version":3,"file":"import-script.js","sourceRoot":"","sources":["../../src/import-script.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"import-script.js","sourceRoot":"","sources":["../../src/import-script.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -1,3 +1,18 @@
+/**
+ * @packageDocumentation
+ *
+ * Utilities for importing and transpiling TypeScript, JavaScript, and JSON
+ * configuration files at Node.js runtime using esbuild.
+ *
+ * Use {@link importConfig} to load a configuration file by basename,
+ * {@link importScript} to bundle and import a single script module, or
+ * {@link importJSON} to read and parse a JSON file from disk.
+ *
+ * @remarks
+ * This package is designed for **file-based** imports, not URL-based.
+ * It bundles the target with esbuild (ESM, external packages) and
+ * loads the result via dynamic `import()`.
+ */
 export { importScript } from './import-script.js';
 export { importJSON } from './import-json.js';
 export { default, importConfig, } from './import-config.js';

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EACL,OAAO,EACP,YAAY,GAGb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,uBAAuB,IAAI,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAC3G,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAA4C,MAAM,oBAAoB,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EACL,OAAO,EACP,YAAY,GAGb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAiC,MAAM,0BAA0B,CAAC;AAC5F,OAAO,EAAE,uBAAuB,IAAI,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAC3G,OAAO,EAAE,iBAAiB,EAAiC,MAAM,sBAAsB,CAAC;AAExF,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC"}