bare-addon-resolve

bare-addon-resolve — Low-level addon resolution algorithm for Bare.

npm i bare-addon-resolve

Usage

For synchronous resolution:

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

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

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

For asynchronous resolution:

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

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

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

API

Functions

resolve

resolve(specifier: string, parentURL: URL, readPackage?: (url: URL) => JSON | null): Iterable<URL>

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.

Parameters

Returns Iterable<URL> — Yields candidate resolution URLs for the caller to test, in the order the algorithm tries them.

Throws

• INVALID_ADDON_SPECIFIER — the addon specifier is not a valid package name or contains an invalid escape sequence.
• INVALID_PACKAGE_NAME — a package manifest's name field is invalid (for example contains __).

resolve.addon(specifier: string, parentURL: URL, opts?: ResolveOptions): Resolver

One step of the resolution algorithm, exposed for fine-grained use: resolve specifier as an addon — a relative or absolute specifier resolves via resolve.file/resolve.directory, otherwise via resolve.package.

Parameters

Returns Resolver — A Resolver yielding the candidate resolutions.

resolve.directory

resolve.directory(dirname: string, version: string, parentURL: URL, opts?: ResolveOptions): Resolver

Resolve dirname as a prebuilds directory addon candidate relative to parentURL.

Parameters

Returns Resolver — A Resolver yielding the candidate resolutions.

resolve.file(filename: string, parentURL: URL, opts?: ResolveOptions): Resolver

Resolve filename as a file addon candidate relative to parentURL, trying each of opts.extensions in turn.

Parameters

Returns Resolver — A Resolver yielding the candidate resolutions.

resolve.linked(name: string, version?: string, opts?: ResolveOptions): Resolver

Resolve name to a linked: specifier, for runtimes that link addons ahead of time by platform (for example iOS or Android) rather than resolving a prebuild at runtime.

Parameters

Returns Resolver — A Resolver yielding the candidate linked: resolutions.

resolve.package

resolve.package(packageSpecifier: string, packageVersion: string, parentURL: URL, opts?: ResolveOptions): Resolver

Resolve packageSpecifier (optionally @packageVersion) as a package name, locating the addon within it.

Parameters

Returns Resolver — A Resolver yielding the candidate resolutions.

resolve.packageSelf

resolve.packageSelf(packageName: string, packageSubpath: string, packageVersion: string, parentURL: URL, opts?: ResolveOptions): Resolver

Resolve packageSubpath against the package named packageName, for when parentURL lies within that package's own scope — a package requiring its own addon by name.

Parameters

Returns Resolver — A Resolver yielding the candidate resolutions.

resolve.url(specifier: string, parentURL: URL, opts?: ResolveOptions): Resolver

Resolve specifier as an absolute URL, yielding it as a single candidate.

Parameters

Returns Resolver — A Resolver yielding the candidate resolution.

Constants and variables

resolve.constants

resolve.constants: {
    UNRESOLVED: number
    YIELDED: number
    RESOLVED: number
  }

The generator status codes yielded by each resolution step: UNRESOLVED, YIELDED, and RESOLVED.

Types

resolve.Resolver

type Resolver = Generator<
    { resolution: URL } | { package: URL },
    number,
    void | boolean | JSON | null
  >

The shared generator type every resolve.* step function returns.

ResolveOptions

interface ResolveOptions {
  builtinProtocol?: string
  builtins?: Builtins
  conditions?: Conditions
  extensions?: string[]
  host?: string
  hosts?: string[]
  linked?: boolean
  linkedProtocol?: string
  matchedConditions?: string[]
  resolutions?: ResolutionsMap
}

bare-addon-resolve/errors

AddonResolveError

AddonResolveError.INVALID_ADDON_SPECIFIER(msg: string): AddonResolveError

Parameters

Returns AddonResolveError — A new AddonResolveError with code INVALID_ADDON_SPECIFIER.

AddonResolveError.INVALID_PACKAGE_NAME(msg: string): AddonResolveError

Parameters

Returns AddonResolveError — A new AddonResolveError with code INVALID_PACKAGE_NAME.

code: string

See also

• Builds on bare-module-resolve and bare-semver.
• The resolved addon is the first candidate resolve yields that exists as a file on the file system.
• The resolve.* step functions are subject to change between minor releases; if using them directly, specify a tilde range (for example ~1.10.0) when declaring the module dependency.
• Addons normally resolve through the runtime or are bundled by bare-pack; reach for this module directly only when building tooling on the resolution algorithm itself, such as bare-module-traverse.
• Bare modules — the full bare-* catalog.
• Bare runtime API — the runtime these modules extend.