mirror of
https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools.git
synced 2025-09-15 12:27:30 +00:00
273 lines
9.0 KiB
Markdown
273 lines
9.0 KiB
Markdown
# resolve.exports [](https://github.com/lukeed/resolve.exports/actions) [](https://licenses.dev/npm/resolve.exports) [](https://codecov.io/gh/lukeed/resolve.exports)
|
||
|
||
> A tiny (952b), correct, general-purpose, and configurable `"exports"` and `"imports"` resolver without file-system reliance
|
||
|
||
***Why?***
|
||
|
||
Hopefully, this module may serve as a reference point (and/or be used directly) so that the varying tools and bundlers within the ecosystem can share a common approach with one another **as well as** with the native Node.js implementation.
|
||
|
||
With the push for ESM, we must be _very_ careful and avoid fragmentation. If we, as a community, begin propagating different _dialects_ of the resolution algorithm, then we're headed for deep trouble. It will make supporting (and using) `"exports"` nearly impossible, which may force its abandonment and along with it, its benefits.
|
||
|
||
Let's have nice things.
|
||
|
||
## Install
|
||
|
||
```sh
|
||
$ npm install resolve.exports
|
||
```
|
||
|
||
## Usage
|
||
|
||
> Please see [`/test/`](/test) for examples.
|
||
|
||
```js
|
||
import * as resolve from 'resolve.exports';
|
||
|
||
// package.json contents
|
||
const pkg = {
|
||
"name": "foobar",
|
||
"module": "dist/module.mjs",
|
||
"main": "dist/require.js",
|
||
"imports": {
|
||
"#hash": {
|
||
"import": {
|
||
"browser": "./hash/web.mjs",
|
||
"node": "./hash/node.mjs",
|
||
},
|
||
"default": "./hash/detect.js"
|
||
}
|
||
},
|
||
"exports": {
|
||
".": {
|
||
"import": "./dist/module.mjs",
|
||
"require": "./dist/require.js"
|
||
},
|
||
"./lite": {
|
||
"worker": {
|
||
"browser": "./lite/worker.browser.js",
|
||
"node": "./lite/worker.node.js"
|
||
},
|
||
"import": "./lite/module.mjs",
|
||
"require": "./lite/require.js"
|
||
}
|
||
}
|
||
};
|
||
|
||
// ---
|
||
// Exports
|
||
// ---
|
||
|
||
// entry: "foobar" === "." === default
|
||
// conditions: ["default", "import", "node"]
|
||
resolve.exports(pkg);
|
||
resolve.exports(pkg, '.');
|
||
resolve.exports(pkg, 'foobar');
|
||
//=> ["./dist/module.mjs"]
|
||
|
||
// entry: "foobar/lite" === "./lite"
|
||
// conditions: ["default", "import", "node"]
|
||
resolve.exports(pkg, 'foobar/lite');
|
||
resolve.exports(pkg, './lite');
|
||
//=> ["./lite/module.mjs"]
|
||
|
||
// Enable `require` condition
|
||
// conditions: ["default", "require", "node"]
|
||
resolve.exports(pkg, 'foobar', { require: true }); //=> ["./dist/require.js"]
|
||
resolve.exports(pkg, './lite', { require: true }); //=> ["./lite/require.js"]
|
||
|
||
// Throws "Missing <entry> specifier in <name> package" Error
|
||
resolve.exports(pkg, 'foobar/hello');
|
||
resolve.exports(pkg, './hello/world');
|
||
|
||
// Add custom condition(s)
|
||
// conditions: ["default", "worker", "import", "node"]
|
||
resolve.exports(pkg, 'foobar/lite', {
|
||
conditions: ['worker']
|
||
}); //=> ["./lite/worker.node.js"]
|
||
|
||
// Toggle "browser" condition
|
||
// conditions: ["default", "worker", "import", "browser"]
|
||
resolve.exports(pkg, 'foobar/lite', {
|
||
conditions: ['worker'],
|
||
browser: true
|
||
}); //=> ["./lite/worker.browser.js"]
|
||
|
||
// Disable non-"default" condition activate
|
||
// NOTE: breaks from Node.js default behavior
|
||
// conditions: ["default", "custom"]
|
||
resolve.exports(pkg, 'foobar/lite', {
|
||
conditions: ['custom'],
|
||
unsafe: true,
|
||
});
|
||
//=> Error: No known conditions for "./lite" specifier in "foobar" package
|
||
|
||
// ---
|
||
// Imports
|
||
// ---
|
||
|
||
// conditions: ["default", "import", "node"]
|
||
resolve.imports(pkg, '#hash');
|
||
resolve.imports(pkg, 'foobar/#hash');
|
||
//=> ["./hash/node.mjs"]
|
||
|
||
// conditions: ["default", "import", "browser"]
|
||
resolve.imports(pkg, '#hash', { browser: true });
|
||
resolve.imports(pkg, 'foobar/#hash');
|
||
//=> ["./hash/web.mjs"]
|
||
|
||
// conditions: ["default"]
|
||
resolve.imports(pkg, '#hash', { unsafe: true });
|
||
resolve.imports(pkg, 'foobar/#hash');
|
||
//=> ["./hash/detect.mjs"]
|
||
|
||
resolve.imports(pkg, '#hello/world');
|
||
resolve.imports(pkg, 'foobar/#hello/world');
|
||
//=> Error: Missing "#hello/world" specifier in "foobar" package
|
||
|
||
// ---
|
||
// Legacy
|
||
// ---
|
||
|
||
// prefer "module" > "main" (default)
|
||
resolve.legacy(pkg); //=> "dist/module.mjs"
|
||
|
||
// customize fields order
|
||
resolve.legacy(pkg, {
|
||
fields: ['main', 'module']
|
||
}); //=> "dist/require.js"
|
||
```
|
||
|
||
## API
|
||
|
||
The [`resolve()`](#resolvepkg-entry-options), [`exports()`](#exportspkg-entry-options), and [`imports()`](#importspkg-target-options) functions share similar API signatures:
|
||
|
||
```ts
|
||
export function resolve(pkg: Package, entry?: string, options?: Options): string[] | undefined;
|
||
export function exports(pkg: Package, entry?: string, options?: Options): string[] | undefined;
|
||
export function imports(pkg: Package, target: string, options?: Options): string[] | undefined;
|
||
// ^ not optional!
|
||
```
|
||
|
||
All three:
|
||
* accept a `package.json` file's contents as a JSON object
|
||
* accept a target/entry identifier
|
||
* may accept an [Options](#options) object
|
||
* return `string[]`, `string`, or `undefined`
|
||
|
||
The only difference is that `imports()` must accept a target identifier as there can be no inferred default.
|
||
|
||
See below for further API descriptions.
|
||
|
||
> **Note:** There is also a [Legacy Resolver API](#legacy-resolver)
|
||
|
||
---
|
||
|
||
### resolve(pkg, entry?, options?)
|
||
Returns: `string[]` or `undefined`
|
||
|
||
A convenience helper which automatically reroutes to [`exports()`](#exportspkg-entry-options) or [`imports()`](#importspkg-target-options) depending on the `entry` value.
|
||
|
||
When unspecified, `entry` defaults to the `"."` identifier, which means that `exports()` will be invoked.
|
||
|
||
```js
|
||
import * as r from 'resolve.exports';
|
||
|
||
let pkg = {
|
||
name: 'foobar',
|
||
// ...
|
||
};
|
||
|
||
r.resolve(pkg);
|
||
//~> r.exports(pkg, '.');
|
||
|
||
r.resolve(pkg, 'foobar');
|
||
//~> r.exports(pkg, '.');
|
||
|
||
r.resolve(pkg, 'foobar/subpath');
|
||
//~> r.exports(pkg, './subpath');
|
||
|
||
r.resolve(pkg, '#hash/md5');
|
||
//~> r.imports(pkg, '#hash/md5');
|
||
|
||
r.resolve(pkg, 'foobar/#hash/md5');
|
||
//~> r.imports(pkg, '#hash/md5');
|
||
```
|
||
|
||
### exports(pkg, entry?, options?)
|
||
Returns: `string[]` or `undefined`
|
||
|
||
Traverse the `"exports"` within the contents of a `package.json` file. <br>
|
||
If the contents _does not_ contain an `"exports"` map, then `undefined` will be returned.
|
||
|
||
Successful resolutions will always result in a `string` or `string[]` value. This will be the value of the resolved mapping itself – which means that the output is a relative file path.
|
||
|
||
This function may throw an Error if:
|
||
|
||
* the requested `entry` cannot be resolved (aka, not defined in the `"exports"` map)
|
||
* an `entry` _is_ defined but no known conditions were matched (see [`options.conditions`](#optionsconditions))
|
||
|
||
#### pkg
|
||
Type: `object` <br>
|
||
Required: `true`
|
||
|
||
The `package.json` contents.
|
||
|
||
#### entry
|
||
Type: `string` <br>
|
||
Required: `false` <br>
|
||
Default: `.` (aka, root)
|
||
|
||
The desired target entry, or the original `import` path.
|
||
|
||
When `entry` _is not_ a relative path (aka, does not start with `'.'`), then `entry` is given the `'./'` prefix.
|
||
|
||
When `entry` begins with the package name (determined via the `pkg.name` value), then `entry` is truncated and made relative.
|
||
|
||
When `entry` is already relative, it is accepted as is.
|
||
|
||
***Examples***
|
||
|
||
Assume we have a module named "foobar" and whose `pkg` contains `"name": "foobar"`.
|
||
|
||
| `entry` value | treated as | reason |
|
||
|-|-|-|
|
||
| `null` / `undefined` | `'.'` | default |
|
||
| `'.'` | `'.'` | value was relative |
|
||
| `'foobar'` | `'.'` | value was `pkg.name` |
|
||
| `'foobar/lite'` | `'./lite'` | value had `pkg.name` prefix |
|
||
| `'./lite'` | `'./lite'` | value was relative |
|
||
| `'lite'` | `'./lite'` | value was not relative & did not have `pkg.name` prefix |
|
||
|
||
|
||
### imports(pkg, target, options?)
|
||
Returns: `string[]` or `undefined`
|
||
|
||
Traverse the `"imports"` within the contents of a `package.json` file. <br>
|
||
If the contents _does not_ contain an `"imports"` map, then `undefined` will be returned.
|
||
|
||
Successful resolutions will always result in a `string` or `string[]` value. This will be the value of the resolved mapping itself – which means that the output is a relative file path.
|
||
|
||
This function may throw an Error if:
|
||
|
||
* the requested `target` cannot be resolved (aka, not defined in the `"imports"` map)
|
||
* an `target` _is_ defined but no known conditions were matched (see [`options.conditions`](#optionsconditions))
|
||
|
||
#### pkg
|
||
Type: `object` <br>
|
||
Required: `true`
|
||
|
||
The `package.json` contents.
|
||
|
||
#### target
|
||
Type: `string` <br>
|
||
Required: `true`
|
||
|
||
The target import identifier; for example, `#hash` or `#hash/md5`.
|
||
|
||
Import specifiers _must_ begin with the `#` character, as required by the resolution specification. However, if `target` begins with the package name (determined by the `pkg.name` value), then `resolve.exports` will trim it from the `target` identifier. For example, `"foobar/#hash/md5"` will be treated as `"#hash/md5"` for the `"foobar"` package.
|
||
|
||
## Options
|
||
|
||
The [`resolve()`](#resolvepkg-entry-options), [`imports()`](#importspkg-target-options), and [`exports()`](#exportspkg-entry-options) functions share these options. All properties are optional and you are not required to pass an `options` argument.
|
||
|
||
Collectively, the `options` are used to assemble a list of [conditions](https://nodejs.org/docs/latest-v18.x/api/packages.html#conditional-exports) that should be activated while resolving your |