bare-module-resolve

Reference for bare-module-resolve: the low-level module resolution algorithm for Bare, exposed as a synchronous or asynchronous generator.

stable

bare-module-resolve implements Bare's low-level module resolution algorithm. It's a pure-JavaScript generator that yields candidate URLs for a specifier; the caller supplies package reads and decides which candidate exists.

This is a low-level building block. Most applications resolve modules implicitly through the runtime or bundle with bare-pack; reach for this directly only when implementing tooling.

npm i bare-module-resolve

Usage

const resolve = require('bare-module-resolve')

function readPackage (url) {
  // Read and parse `url` if it exists, otherwise return null
}

for (const resolution of resolve('./file.js', new URL('file:///directory/'), readPackage)) {
  console.log(resolution)
}

For asynchronous resolution, pass an async readPackage and iterate with for await:

const resolve = require('bare-module-resolve')

async function readPackage (url) {
  // Read and parse `url` if it exists, otherwise null
}

for await (const resolution of resolve('./file.js', new URL('file:///directory/'), readPackage)) {
  console.log(resolution)
}

API

`const resolver = resolve(specifier, parentURL[, options][, readPackage])`

Resolve specifier relative to parentURL, which must be a WHATWG URL instance. readPackage is called with a URL instance for every package manifest to be read and must either return the parsed JSON package manifest, if it exists, or null. If readPackage returns a promise, synchronous iteration is not supported.

Options include:

options = {
  // A default "imports" map to apply to all specifiers. Follows the same
  // syntax and rules as the "imports" property defined in `package.json`.
  imports,
  // A list of builtin module specifiers. If matched, the protocol of the
  // resolved URL will be `builtinProtocol`.
  builtins: [],
  // The protocol to use for resolved builtin module specifiers.
  builtinProtocol: 'builtin:',
  // A list of module specifiers whose resolution should be deferred. If
  // matched, the protocol of the resolved URL will be `deferredProtocol`.
  defer: [],
  // The protocol to use for resolved deferred module specifiers.
  deferredProtocol: 'deferred:',
  // The supported import conditions. "default" is always recognized.
  conditions: [],
  // An array reference that will contain the matched conditions when
  // yielding resolutions.
  matchedConditions: [],
  // An array reference that will contain the matched targets when yielding
  // remapped specifiers, such as those from resolution or import maps.
  matchedTargets: [],
  // The supported engine versions.
  engines: {},
  // The file extensions to look for. Must be provided to support
  // extensionless specifier resolution and directory support, such as
  // resolving './foo' to './foo.js' or './foo/index.js'.
  extensions: [],
  // A map of preresolved imports with keys being serialized parent URLs
  // and values being "imports" maps.
  resolutions
}

`for (const resolution of resolver)`

Synchronously iterate the module resolution candidates. The resolved module is the first candidate that exists, either as a file on a file system, a resource at a URL, or something else entirely.

`for await (const resolution of resolver)`

Asynchronously iterate the module resolution candidates. If readPackage returns promises, these will be awaited. The same semantics as for (const resolution of resolver) apply.

Sub-generators

These functions are currently subject to change between minor releases. If using them directly, specify a tilde range (~1.2.3) when declaring the module dependency.

The algorithm's steps are exposed for fine-grained use: resolve.module, resolve.url, resolve.preresolved, resolve.deferred, resolve.package, resolve.packageSelf, resolve.packageExports, resolve.packageImports, resolve.packageImportsExports, resolve.packageTarget, resolve.builtinTarget, resolve.file, and resolve.directory. See the repository README for each step's signature and options.

Builds on bare-semver. Paired with bare-addon-resolve and bare-module-traverse.