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.

Types

`TraverseOptions`

interface TraverseOptions {
  defaultType?: number
  aliases?: Record<string, AliasableExtension>
  resolve?: (entry: Import, parentURL: URL, opts?: ResolveOptions) => Resolver
  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
  imports: ImportsMap
  lexer: {
    imports: Import[]
    exports: Export[]
  }
}

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`	—	—