bare-module-traverse

stable

bare-module-traverse — Low-level module graph traversal for Bare.

npm i bare-module-traverse

Usage

For synchronous traversal:

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

function readModule(url) {
  // Read `url` if it exists, otherwise `null`
}

function* listPrefix(url) {
  // Yield URLs that have `url` as a prefix. The list may be empty.
}

for (const dependency of traverse(new URL('file:///directory/file.js'), readModule, listPrefix)) {
  console.log(dependency)
}

For asynchronous traversal:

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

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

async function* listPrefix(url) {
  // Yield URLs that have `url` as a prefix. The list may be empty.
}

for await (const dependency of traverse(
  new URL('file:///directory/file.js'),
  readModule,
  listPrefix
)) {
  console.log(dependency)
}

API

Functions

`traverse`

traverse(entry: URL, readModule: (url: URL) => Buffer | string | null, listPrefix?: (url: URL) => Iterable<URL>, probeModule?: (url: URL) => boolean | undefined, resolveModule?: (url: URL) => URL): Iterable<Dependency>

Traverse the module graph rooted at entry, which must be a WHATWG URL instance. readModule is called with a URL instance for every module to be read and must either return the module source, if it exists, or null. listPrefix is called with a URL instance of every prefix to be listed and must yield URL instances that have the specified URL as a prefix. If not provided, prefixes won't be traversed. If readModule returns a promise or listPrefix returns a promise generator, synchronous iteration is not supported.

Parameters

Parameter	Type	Default	Description
`entry`	`URL`	—	The WHATWG `URL` of the entry module to root the graph at.
`readModule`	`(url: URL) => Buffer \| string \| null`	—	Called with the `URL` of each module to read; returns its source as a `Buffer` or `string`, or `null` if it does not exist. Returning a promise disables synchronous iteration.
`listPrefix?`	`(url: URL) => Iterable<URL>`	—	Called with the `URL` of each prefix to list; must yield the `URL`s that have it as a prefix. If omitted, prefixes are not traversed.
`probeModule?`	`(url: URL) => boolean \| undefined`	—	Called with the `URL` of each module to probe for existence; returns a boolean, or `undefined` to fall back to `readModule`.
`resolveModule?`	`(url: URL) => URL`	—	Called with each resolution `URL` to transform; returns the `URL` to use in its place. Defaults to the identity function.

Returns Iterable<Dependency> — An iterable of resolved Dependency records for the module graph; asynchronous when any callback returns a promise.

`traverse.addons`

traverse.addons(parentURL: URL, artifacts: Artifacts, visited: Set<string>, opts?: TraverseOptions): Traversal

Parameters

Parameter	Type	Default	Description
`parentURL`	`URL`	—	—
`artifacts`	`Artifacts`	—	—
`visited`	`Set<string>`	—	—
`opts?`	`TraverseOptions`	—	—

`traverse.assets`

traverse.assets(patterns: ConditionalSpecifier, parentURL: URL, artifacts: Artifacts, visited: Set<string>, opts?: TraverseOptions): Traversal

Parameters

Parameter	Type	Default	Description
`patterns`	`ConditionalSpecifier`	—	—
`parentURL`	`URL`	—	—
`artifacts`	`Artifacts`	—	—
`visited`	`Set<string>`	—	—
`opts?`	`TraverseOptions`	—	—

`traverse.imports`

traverse.imports(parentURL: URL, source: string | Buffer, imports: ImportsMap, artifacts: Artifacts, lexer: {
      imports: Import[]
      exports: Export[]
    }, visited: Set<string>, opts?: TraverseOptions): Traversal

Parameters

Parameter	Type	Default	Description
`parentURL`	`URL`	—	—
`source`	`string` \| `Buffer`	—	—
`imports`	`ImportsMap`	—	—
`artifacts`	`Artifacts`	—	—
`lexer`	`{ imports: Import[] exports: Export[] }`	—	—
`visited`	`Set<string>`	—	—
`opts?`	`TraverseOptions`	—	—

`traverse.link`

traverse.link(entry: Import, specifier: string, condition: string, parentURL: URL, imports: ImportsMap, artifacts: Artifacts, visited: Set<string>, opts?: TraverseOptions): Traversal

Parameters

Parameter	Type	Default	Description
`entry`	`Import`	—	—
`specifier`	`string`	—	—
`condition`	`string`	—	—
`parentURL`	`URL`	—	—
`imports`	`ImportsMap`	—	—
`artifacts`	`Artifacts`	—	—
`visited`	`Set<string>`	—	—
`opts?`	`TraverseOptions`	—	—

`traverse.module`

traverse.module(url: URL, source: string | Buffer, attributes: Record<string, string> | null, artifacts: Artifacts, visited: Set<string>, opts?: TraverseOptions): Traversal

Parameters

Parameter	Type	Default	Description
`url`	`URL`	—	—
`source`	`string` \| `Buffer`	—	—
`attributes`	`Record<string, string> \| null`	—	—
`artifacts`	`Artifacts`	—	—
`visited`	`Set<string>`	—	—
`opts?`	`TraverseOptions`	—	—

`traverse.package`

traverse.package(url: URL, source: string | Buffer, artifacts: Artifacts, visited: Set<string>, opts?: TraverseOptions): Traversal

Parameters

Parameter	Type	Default	Description
`url`	`URL`	—	—
`source`	`string` \| `Buffer`	—	—
`artifacts`	`Artifacts`	—	—
`visited`	`Set<string>`	—	—
`opts?`	`TraverseOptions`	—	—

`traverse.preresolved`

traverse.preresolved(url: URL, source: string | Buffer, resolution: ResolutionsMap, artifacts: Artifacts, visited: Set<string>, opts?: TraverseOptions): Traversal

Parameters

Parameter	Type	Default	Description
`url`	`URL`	—	—
`source`	`string` \| `Buffer`	—	—
`resolution`	`ResolutionsMap`	—	—
`artifacts`	`Artifacts`	—	—
`visited`	`Set<string>`	—	—
`opts?`	`TraverseOptions`	—	—

Constants and variables

`traverse.constants`

traverse.constants: {
    SCRIPT: number
    MODULE: number
    JSON: number
    BUNDLE: number
    ADDON: number
    BINARY: number
    TEXT: number
  }

Types

`traverse.Traversal`

type Traversal = Generator<
    | { module: URL; artifact: boolean }
    | { probe: URL }
    | { resolution: URL }
    | { prefix: URL }
    | { links: Traversal[] }
    | { children: Traversal; deferred: boolean }
    | { dependency: Dependency },
    boolean,
    void | URL | URL[] | Buffer | string | boolean | null
  >

Each yielded value tells the driver what to resolve next; drive the generator by calling .next() with the corresponding response, repeating until next.done is true:

Yield	Description	Respond with
`{ module, artifact }`	A module to read. When `artifact` is `true`, it's an addon or asset whose contents are loaded lazily; a driver that only needs to locate it, such as a module loader, may return `null` without reading once existence is established by probing.	Its source, or `null` if it doesn't exist.
`{ probe }`	A module whose existence is to be tested without reading its full source.	`true` or `false`, or `undefined` to fall back to determining existence by reading the module instead.
`{ resolution }`	A resolved, existing module URL to transform, for example canonicalizing symlinks with `realpath`.	The URL to use in its place, or the URL unchanged.
`{ prefix }`	A prefix to list.	The URLs that have it as a prefix (the list may be empty).
`{ links }`	A set of independent imports to resolve, each itself a `Traversal`. Every generator in `links` must be driven to completion (one at a time, or concurrently since they're independent) before the parent is resumed.	Nothing — call `.next()` once every generator in `links` is done.
`{ children, deferred }`	A child dependency subgraph to traverse by driving its generator the same way as the parent. When `deferred` is `true`, traverse it only after every non-deferred subgraph has been traversed.	Nothing — call `.next()` after queuing or traversing `children`.
`{ dependency }`	A fully resolved node of the module graph — the traversal's output, and what the iterable forms of `traverse()` yield to the caller.	Nothing — this is a terminal yield for that branch.

traverse() drives this loop automatically from readModule, listPrefix, probeModule, and resolveModule; drive a step function's Traversal manually only when using it directly instead of traverse().

`TraverseOptions`

interface TraverseOptions {
  defaultType?: number
  importType?: number
  artifacts?: boolean
  aliases?: Record<string, AliasableExtension>
  resolve?: (entry: Import, parentURL: URL, opts?: ResolveOptions) => Resolver
  deferUnresolved?: boolean
  builtinProtocol?: string
  builtins?: Builtins
  conditions?: Conditions
  extensions?: string[]
  host?: string
  hosts?: string[]
  linked?: boolean
  linkedProtocol?: string
  matchedConditions?: string[]
  resolutions?: ResolutionsMap
}

`Artifacts`

interface Artifacts {
  addons: URL[] | Set<string>
  assets: URL[] | Set<string>
}

`Dependency`

interface Dependency {
  url: URL
  source: string | Buffer
  type: number
  naturalType: number
  imports: ImportsMap
  lexer: {
    imports: Import[]
    exports: Export[]
  }
}

A fully resolved node of the module graph, and what the iterable forms of traverse() yield to the caller. type is the module's effective type, one of the traverse.constants flags (for example SCRIPT or MODULE); naturalType is the type the module has on its own, ignoring import attributes, or 0 if it has no type of its own. lexer holds the raw imports and exports bare-module-lexer detected in source.

Parameter	Type	Default	Description
`specifier`	`string`	—	—
`parentURL`	`URL`	—	—
`opts?`	`ResolveOptions`	—	—

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

Parameters

Parameter	Type	Default	Description
`specifier`	`string`	—	—
`parentURL`	`URL`	—	—
`opts?`	`ResolveOptions`	—	—

`default(entry: Import, parentURL: URL, opts?: ResolveOptions): Resolver`

The default resolver, which simply forwards to <https://github.com/holepunchto/bare-module-resolve> and <https://github.com/holepunchto/bare-addon-resolve> with the literal options passed by the caller.

Parameters

Parameter	Type	Default	Description
`entry`	`Import`	—	The import to resolve, as produced by `bare-module-lexer`.
`parentURL`	`URL`	—	The WHATWG `URL` to resolve `entry` relative to.
`opts?`	`ResolveOptions`	—	Resolve options forwarded to the underlying resolution algorithm.

Returns Resolver — A Resolver that yields the candidate resolutions for entry.

`bare(entry: Import, parentURL: URL, opts?: BareResolveOptions): Resolver`

The Bare resolver, which matches the options used by the Bare module system.

Parameters

Parameter	Type	Default	Description
`entry`	`Import`	—	The import to resolve, as produced by `bare-module-lexer`.
`parentURL`	`URL`	—	The WHATWG `URL` to resolve `entry` relative to.
`opts?`	`BareResolveOptions`	—	Resolve options forwarded to the underlying resolution algorithm.

Returns Resolver — A Resolver that yields the candidate resolutions for entry.

`node(entry: Import, parentURL: URL, opts?: NodeResolveOptions): Resolver`

The Node.js resolver, which matches the options used by the Node.js module system.

Parameters

Parameter	Type	Default	Description
`entry`	`Import`	—	The import to resolve, as produced by `bare-module-lexer`.
`parentURL`	`URL`	—	The WHATWG `URL` to resolve `entry` relative to.
`opts?`	`NodeResolveOptions`	—	Resolve options forwarded to the underlying resolution algorithm.

Returns Resolver — A Resolver that yields the candidate resolutions for entry.

Types

`bare.BareResolveOptions`

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

`node.NodeResolveOptions`

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

Parameter	Type	Default	Description
`entry`	`Import`	—	The import to resolve, as produced by `bare-module-lexer`.
`parentURL`	`URL`	—	The WHATWG `URL` to resolve `entry` relative to.
`opts?`	`ResolveOptions`	—	Resolve options forwarded to the underlying resolution algorithm.

Returns Resolver — A Resolver that yields the candidate resolutions for entry.

Parameter	Type	Default	Description
`entry`	`Import`	—	The import to resolve, as produced by `bare-module-lexer`.
`parentURL`	`URL`	—	The WHATWG `URL` to resolve `entry` relative to.
`opts?`	`BareResolveOptions`	—	Resolve options forwarded to the underlying resolution algorithm.

Returns Resolver — A Resolver that yields the candidate resolutions for entry.

Types

`BareResolveOptions`

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

Parameter	Type	Default	Description
`entry`	`Import`	—	The import to resolve, as produced by `bare-module-lexer`.
`parentURL`	`URL`	—	The WHATWG `URL` to resolve `entry` relative to.
`opts?`	`NodeResolveOptions`	—	Resolve options forwarded to the underlying resolution algorithm.

Returns Resolver — A Resolver that yields the candidate resolutions for entry.

Types

`NodeResolveOptions`

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

bare-module-traverse

On this page