basant307/AI_Governance_Project

1# exsolve2 3[![npm version](https://img.shields.io/npm/v/exsolve?color=yellow)](https://npmjs.com/package/exsolve)4[![npm downloads](https://img.shields.io/npm/dm/exsolve?color=yellow)](https://npm.chart.dev/exsolve)5[![pkg size](https://img.shields.io/npm/unpacked-size/exsolve?color=yellow)](https://packagephobia.com/result?p=exsolve)6 7> Module resolution utilities for Node.js (based on previous work in [unjs/mlly](https://github.com/unjs/mlly), [wooorm/import-meta-resolve](https://github.com/wooorm/import-meta-resolve), and the upstream [Node.js](https://github.com/nodejs/node) implementation).8 9This library exposes an API similar to [`import.meta.resolve`](https://nodejs.org/api/esm.html#importmetaresolvespecifier) based on Node.js's upstream implementation and [resolution algorithm](https://nodejs.org/api/esm.html#esm_resolution_algorithm). It supports all built-in functionalities—import maps, export maps, CJS, and ESM—with some additions:10 11- Pure JS with no native dependencies (only Node.js is required).12- Built-in resolve [cache](#resolve-cache).13- Throws an error (or [try](#try)) if the resolved path does not exist in the filesystem.14- Can override the default [conditions](#conditions).15- Can resolve [from](#from) one or more parent URLs.16- Can resolve with custom [suffixes](#suffixes).17- Can resolve with custom [extensions](#extensions).18 19## Usage20 21Install the package:22 23```sh24# ✨ Auto-detect (npm, yarn, pnpm, bun, deno)25npx nypm install exsolve26```27 28Import:29 30```ts31// ESM import32import {33  resolveModuleURL,34  resolveModulePath,35  createResolver,36  clearResolveCache,37} from "exsolve";38 39// Or using dynamic import40const { resolveModulePath } = await import("exsolve");41```42 43```ts44resolveModuleURL(id, {45  /* options */46});47 48resolveModulePath(id, {49  /* options */50});51```52 53Differences between `resolveModuleURL` and `resolveModulePath`:54 55- `resolveModuleURL` returns a URL string like `file:///app/dep.mjs`.56- `resolveModulePath` returns an absolute path like `/app/dep.mjs`.57  - If the resolved URL does not use the `file://` scheme (e.g., `data:` or `node:`), it will throw an error.58 59## Resolver with Options60 61You can create a custom resolver instance with default [options](#resolve-options) using `createResolver`.62 63**Example:**64 65```ts66import { createResolver } from "exsolve";67 68const { resolveModuleURL, resolveModulePath } = createResolver({69  suffixes: ["", "/index"],70  extensions: [".mjs", ".cjs", ".js", ".mts", ".cts", ".ts", ".json"],71  conditions: ["node", "import", "production"],72});73```74 75## Resolve Cache76 77To speed up resolution, resolved values (and errors) are globally cached with a unique key based on id and options.78 79**Example:** Invalidate all (global) cache entries (to support file-system changes).80 81```ts82import { clearResolveCache } from "exsolve";83 84clearResolveCache();85```86 87**Example:** Custom resolver with custom cache object.88 89```ts90import { createResolver } from "exsolve";91 92const { clearResolveCache, resolveModulePath } = createResolver({93  cache: new Map(),94});95```96 97**Example:** Resolve without cache.98 99```ts100import { resolveModulePath } from "exsolve";101 102resolveModulePath("id", { cache: false });103```104 105## Resolve Options106 107### `try`108 109If set to `true` and the module cannot be resolved, the resolver returns `undefined` instead of throwing an error.110 111**Example:**112 113```ts114// undefined115const resolved = resolveModuleURL("non-existing-package", { try: true });116```117 118### `from`119 120A URL, path, or array of URLs/paths from which to resolve the module.121 122If not provided, resolution starts from the current working directory. Setting this option is recommended.123 124You can use `import.meta.url` for `from` to mimic the behavior of `import.meta.resolve()`.125 126> [!TIP]127> For better performance, ensure the value is a `file://` URL or at least ends with `/`.128>129> If it is set to an absolute path, the resolver must first check the filesystem to see if it is a file or directory.130> If the input is a `file://` URL or ends with `/`, the resolver can skip this check.131 132### `conditions`133 134Conditions to apply when resolving package exports (default: `["node", "import"]`).135 136**Example:**137 138```ts139// "/app/src/index.ts"140const src = resolveModuleURL("pkg-name", {141  conditions: ["deno", "node", "import", "production"],142});143```144 145> [!NOTE]146> Conditions are applied **without order**. The order is determined by the `exports` field in `package.json`.147 148### `extensions`149 150Additional file extensions to check as fallbacks.151 152**Example:**153 154```ts155// "/app/src/index.ts"156const src = resolveModulePath("./src/index", {157  extensions: [".mjs", ".cjs", ".js", ".mts", ".cts", ".ts", ".json"],158});159```160 161> [!TIP]162> For better performance, use explicit extensions and avoid this option.163 164### `suffixes`165 166Path suffixes to check.167 168**Example:**169 170```ts171// "/app/src/utils/index.ts"172const src = resolveModulePath("./src/utils", {173  suffixes: ["", "/index"],174  extensions: [".mjs", ".cjs", ".js"],175});176```177 178> [!TIP]179> For better performance, use explicit `/index` when needed and avoid this option.180 181### `cache`182 183Resolve cache (enabled by default with a shared global object).184 185Can be set to `false` to disable or a custom `Map` to bring your own cache object.186 187See [cache](#resolve-cache) for more info.188 189## Other Performance Tips190 191**Use explicit module extensions `.mjs` or `.cjs` instead of `.js`:**192 193This allows the resolution fast path to skip reading the closest `package.json` for the [`type`](https://nodejs.org/api/packages.html#type).194 195## Development196 197<details>198 199<summary>local development</summary>200 201- Clone this repository202- Install the latest LTS version of [Node.js](https://nodejs.org/en/)203- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`204- Install dependencies using `pnpm install`205- Run interactive tests using `pnpm dev`206 207</details>208 209## License210 211Published under the [MIT](https://github.com/unjs/exsolve/blob/main/LICENSE) license.212 213Based on previous work in [unjs/mlly](https://github.com/unjs/mlly), [wooorm/import-meta-resolve](https://github.com/wooorm/import-meta-resolve) and [Node.js](https://github.com/nodejs/node) original implementation.214