Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wooorm/import-meta-resolve

Resolve things like Node.js — ponyfill for `import.meta.resolve`
https://github.com/wooorm/import-meta-resolve

esm module node resolve

Last synced: 17 days ago
JSON representation

Resolve things like Node.js — ponyfill for `import.meta.resolve`

Awesome Lists containing this project

README 

        
# import-meta-resolve



[![Build][build-badge]][build]

[![Coverage][coverage-badge]][coverage]

[![Downloads][downloads-badge]][downloads]



Resolve things like Node.js.



## Contents



* [What is this?](#what-is-this)

* [When to use this?](#when-to-use-this)

* [Install](#install)

* [Use](#use)

* [API](#api)

  * [`resolve(specifier, parent)`](#resolvespecifier-parent)

  * [`moduleResolve(specifier, parent, conditions, preserveSymlinks)`](#moduleresolvespecifier-parent-conditions-preservesymlinks)

  * [`ErrnoException`](#errnoexception)

* [Algorithm](#algorithm)

* [Differences to Node](#differences-to-node)

* [Types](#types)

* [Compatibility](#compatibility)

* [Contribute](#contribute)

* [License](#license)



## What is this?



This package is a ponyfill for [`import.meta.resolve`][native-resolve].

It supports everything you need to resolve files just like modern Node does:

import maps, export maps, loading CJS and ESM projects, all of that!



## When to use this?



As of Node.js 20.0, `import.meta.resolve` is still behind an experimental flag.

This package can be used to do what it does in Node 16–20.



## Install



This package is [ESM only][esm].

In Node.js (version 16+), install with [npm][]:



```sh

npm install import-meta-resolve

```



## Use



```js

import {resolve} from 'import-meta-resolve'



// A file:

console.log(resolve('./index.js', import.meta.url))

//=> file:///Users/tilde/Projects/oss/import-meta-resolve/index.js



// A CJS package:

console.log(resolve('builtins', import.meta.url))

//=> file:///Users/tilde/Projects/oss/import-meta-resolve/node_modules/builtins/index.js



// A scoped CJS package:

console.log(resolve('@eslint/eslintrc', import.meta.url))

//=> file:///Users/tilde/Projects/oss/import-meta-resolve/node_modules/@eslint/eslintrc/lib/index.js



// A package with an export map:

console.log(resolve('micromark/lib/parse', import.meta.url))

//=> file:///Users/tilde/Projects/oss/import-meta-resolve/node_modules/micromark/lib/parse.js



// A node builtin:

console.log(resolve('fs', import.meta.url))

//=> node:fs

```



## API



This package exports the identifiers [`moduleResolve`][moduleresolve] and

[`resolve`][resolve].

There is no default export.



### `resolve(specifier, parent)`



Match `import.meta.resolve` except that `parent` is required (you can pass

`import.meta.url`).



###### Parameters



* `specifier` (`string`)

  — the module specifier to resolve relative to parent

  (`/example.js`, `./example.js`, `../example.js`, `some-package`, `fs`, etc)

* `parent` (`string`, example: `import.meta.url`)

  — the absolute parent module URL to resolve from; you must pass

  `import.meta.url` or something else



###### Returns



Full `file:`, `data:`, or `node:` URL (`string`) to the found thing



###### Throws



Throws an [`ErrnoException`][errnoexception].



### `moduleResolve(specifier, parent, conditions, preserveSymlinks)`



The [“Resolver Algorithm Specification”][algo] as detailed in the Node docs

(which is slightly lower-level than `resolve`).



###### Parameters



* `specifier` (`string`)

  — `/example.js`, `./example.js`, `../example.js`, `some-package`, `fs`, etc

* `parent` (`URL`, example: `import.meta.url`)

  — full URL (to a file) that `specifier` is resolved relative from

* `conditions` (`Set`, default: `new Set(['node', 'import'])`)

  — conditions

* `preserveSymlinks` (`boolean`, default: `false`)

  — keep symlinks instead of resolving them



###### Returns



A URL object (`URL`) to the found thing.



###### Throws



Throws an [`ErrnoException`][errnoexception].



### `ErrnoException`



One of many different errors that occur when resolving (TypeScript type).



###### Type



```ts

type ErrnoExceptionFields = Error & {

  errnode?: number | undefined

  code?: string | undefined

  path?: string | undefined

  syscall?: string | undefined

  url?: string | undefined

}

```



The `code` field on errors is one of the following strings:



* `'ERR_INVALID_MODULE_SPECIFIER'`

  — when `specifier` is invalid (example: `'#'`)

* `'ERR_INVALID_PACKAGE_CONFIG'`

  — when a `package.json` is invalid (example: invalid JSON)

* `'ERR_INVALID_PACKAGE_TARGET'`

  — when a `package.json` `exports` or `imports` is invalid (example: when it

  does not start with `'./'`)

* `'ERR_MODULE_NOT_FOUND'`

  — when `specifier` cannot be found in `parent` (example: `'some-missing-package'`)

* `'ERR_NETWORK_IMPORT_DISALLOWED'`

  — thrown when trying to resolve a local file or builtin from a remote file

  (`node:fs` relative to `'https://example.com'`)

* `'ERR_PACKAGE_IMPORT_NOT_DEFINED'`

  — when a local import is not defined in an import map (example: `'#local'`

  when not defined)

* `'ERR_PACKAGE_PATH_NOT_EXPORTED'`

  — when an export is not defined in an export map (example: `'tape/index.js'`,

  which is not in its export map)

* `'ERR_UNSUPPORTED_DIR_IMPORT'`

  — when attempting to import a directory (example: `'./lib/'`)

* `'ERR_UNKNOWN_FILE_EXTENSION'`

  — when somehow reading a file that has an unexpected extensions (`'./readme.md'`)

* `'ERR_INVALID_ARG_VALUE'`

  — when `conditions` is incorrect



## Algorithm



The algorithm for `resolve` matches how Node handles `import.meta.resolve`, with

a couple of differences.



The algorithm for `moduleResolve` matches the [Resolver Algorithm

Specification][algo] as detailed in the Node docs (which is sync and slightly

lower-level than `resolve`).



## Differences to Node



* `parent` defaulting to `import.meta.url` cannot be ponyfilled: you have to

  explicitly pass it

* no support for loaders (that would mean implementing all of loaders)

* no support for CLI flags:

  `--conditions`,

  `--experimental-default-type`,

  `--experimental-json-modules`,

  `--experimental-network-imports`,

  `--experimental-policy`,

  `--experimental-wasm-modules`,

  `--input-type`,

  `--no-addons`,

  `--preserve-symlinks`, nor

  `--preserve-symlinks-main`

  work

* no support for `WATCH_REPORT_DEPENDENCIES` env variable

* no attempt is made to add a suggestion based on how things used to work in

  CJS before to not-found errors

* prototypal methods are not guarded: Node protects for example `String#slice`

  or so from being tampered with, whereas this doesn’t



## Types



This package is fully typed with [TypeScript][].

It exports the additional type [`ErrnoException`][errnoexception].



## Compatibility



This package is at least compatible with all maintained versions of Node.js.

As of now, that is Node.js 16 and later.



## Contribute



Yes please!

See [How to Contribute to Open Source][contribute].



## License



[MIT][license] © [Titus Wormer][author] and Node.js contributors



[build-badge]: https://github.com/wooorm/import-meta-resolve/workflows/main/badge.svg



[build]: https://github.com/wooorm/import-meta-resolve/actions



[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/import-meta-resolve.svg



[coverage]: https://codecov.io/github/wooorm/import-meta-resolve



[downloads-badge]: https://img.shields.io/npm/dm/import-meta-resolve.svg



[downloads]: https://www.npmjs.com/package/import-meta-resolve



[npm]: https://docs.npmjs.com/cli/install



[license]: license



[author]: https://wooorm.com



[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c



[typescript]: https://www.typescriptlang.org



[contribute]: https://opensource.guide/how-to-contribute/



[algo]: https://nodejs.org/dist/latest-v14.x/docs/api/esm.html#esm_resolver_algorithm



[native-resolve]: https://nodejs.org/api/esm.html#esm_import_meta_resolve_specifier_parent



[resolve]: #resolvespecifier-parent



[moduleresolve]: #moduleResolvespecifier-parent-conditions-preserveSymlinks



[errnoexception]: #errnoexception