bare-module-traverse 2.4.4 → 2.5.0

package/README.md

@@ -50,118 +50,9 @@ for await (const dependency of traverse(
 
 ## API
 
-#### `const dependencies = traverse(url[, options], readModule[, listPrefix[, probeModule[, resolveModule]]])`
+See the [`bare-module-traverse` reference](https://docs.pears.com/reference/bare/modules/bare-module-traverse).
 
-Traverse the module graph rooted at `url`, 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. `probeModule` is called with a `URL` instance to test whether a module exists and must return `true` if it does, `false` if it doesn't, or `undefined` if probing isn't supported; this lets existence be checked without reading the full module source, such as when locating an addon or asset. When it returns `undefined`, existence is instead determined by reading the module, so no source is read twice. If not provided, `probeModule` returns `undefined` and no probing is performed. `resolveModule` is called with a `URL` instance for every resolved, existing module and must return the `URL` to use in its place, applying any post-resolution transform; a file system implementation would canonicalize symlinks here with `realpath` so a module reached through different symlinks dedupes against its real location. If not provided, resolutions are used unchanged. If `readModule`, `probeModule`, or `resolveModule` returns a promise, or `listPrefix` returns a promise generator, synchronous iteration is not supported.
-
-Options include:
-
-```js
-options = {
-  defaultType: constants.SCRIPT,
-  aliases: {
-    // Map an extension to a supported extension, e.g. `'.ts': '.js'`. The
-    // aliased extension is used for module type detection, so `readModule()`
-    // must return source compatible with that type. Aliased modules are also
-    // emitted with the aliased extension, and resolutions to them are
-    // rewritten to match, so `'.ts': '.js'` yields a `file:///foo.js`
-    // dependency rather than `file:///foo.ts`.
-  },
-  resolve: resolve.default,
-  visited: new Set()
-}
-```
-
-When a module URL uses the `data:` protocol, its source is decoded directly from the specifier rather than read via `readModule()`, so no source module effect is emitted for it. base64 encoded data is decoded to a `Buffer`, other data is percent-decoded to a string, and the module type is derived from the media type (`text/javascript` and `application/javascript` map to a script or module, `application/json` to JSON, and anything else to `defaultType`). A JavaScript `data:` URL inherits the type of the module that imports it, so it is a script when imported from a script and a module when imported from a module, falling back to `defaultType` when it has no referrer, such as a `data:` entry. Only the UTF-8 charset is supported; a `data:` URL specifying any other charset throws.
-
-`visited` is a `Set` of already visited module hrefs. If provided, modules whose href is already in the set are skipped and the set is updated in place as traversal proceeds. This allows a single set to be shared across several traversals so that a later traversal, such as one rooted at a dynamically imported module, does not revisit modules already seen by an earlier one.
-
-Options supported by <https://github.com/holepunchto/bare-module-resolve> and <https://github.com/holepunchto/bare-addon-resolve> may also be specified.
-
-#### `for (const dependency of dependencies)`
-
-Synchronously iterate the module graph. Each yielded dependency has the following shape:
-
-```js
-dependency = {
-  url: URL,
-  source: 'string' | Buffer, // Source as returned by `readModule()`
-  type: constants.SCRIPT, // The detected module type, or `0` if unknown
-  imports: {
-    // See https://github.com/holepunchto/bare-module#imports
-  },
-  lexer: {
-    imports: [
-      // See https://github.com/holepunchto/bare-module-lexer#api
-    ],
-    exports: [
-      // See https://github.com/holepunchto/bare-module-lexer#api
-    ]
-  }
-}
-```
-
-#### `for await (const dependency of dependencies)`
-
-Asynchronously iterate the module graph. If `readModule` returns a promise or `listPrefix` returns a promise generator, these will be awaited. The same comments as `for (const dependency of dependencies)` apply.
-
-#### `constants`
-
-The module type constants used by the `type` field of each dependency and accepted as the `defaultType` option.
-
-| Constant | Description        |
-| :------- | :----------------- |
-| `SCRIPT` | A CommonJS module. |
-| `MODULE` | An ES module.      |
-| `JSON`   | A JSON module.     |
-| `BUNDLE` | A bundle module.   |
-| `ADDON`  | A native addon.    |
-| `BINARY` | A binary module.   |
-| `TEXT`   | A text module.     |
-
-### Resolution
-
-Module and addon resolution is configurable by providing a resolver function. A resolver function is a generator function that yields values matching the shapes defined by <https://github.com/holepunchto/bare-module-resolve#algorithm>. Several resolvers are provided out of the box to support the most common use cases.
-
-#### `resolve.module`
-
-Convenience export from <https://github.com/holepunchto/bare-module-resolve>.
-
-#### `resolve.addon`
-
-Convenience export from <https://github.com/holepunchto/bare-addon-resolve>.
-
-#### `resolve.default`
-
-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.
-
-#### `resolve.bare`
-
-The Bare resolver, which matches the options used by the Bare module system. The resolver accepts the following additional options:
-
-```js
-options = {
-  host,
-  hosts: [host]
-}
-```
-
-For single target traversal it is sufficient to pass `host`. For multi target traversal pass a list of `hosts` identifiers instead.
-
-#### `resolve.node`
-
-The Node.js resolver, which matches the options used by the Node.js module system. The resolver accepts the following additional options:
-
-```js
-options = {
-  host,
-  hosts: [host]
-}
-```
-
-For single target traversal it is sufficient to pass `host`. For multi target traversal pass a list of `hosts` identifiers instead.
-
-### Algorithm
+## Algorithm
 
 The following generator functions implement the traversal algorithm. The yielded values have the following shape:
 
@@ -321,19 +212,19 @@ Options are the same as `traverse()` for all functions.
 > [!WARNING]
 > These functions are currently subject to change between minor releases. If using them directly, make sure to specify a tilde range (`~1.2.3`) when declaring the module dependency.
 
-#### `const generator = traverse.module(url, source, attributes, artifacts, visited[, options])`
+### `const generator = traverse.module(url, source, attributes, artifacts, visited[, options])`
 
-#### `const generator = traverse.package(url, source, artifacts, visited[, options])`
+### `const generator = traverse.package(url, source, artifacts, visited[, options])`
 
-#### `const generator = traverse.preresolved(url, source, resolutions, artifacts, visited[, options])`
+### `const generator = traverse.preresolved(url, source, resolutions, artifacts, visited[, options])`
 
-#### `const generator = traverse.imports(parentURL, source, imports, artifacts, lexer, visited[, options])`
+### `const generator = traverse.imports(parentURL, source, imports, artifacts, lexer, visited[, options])`
 
-#### `const generator = traverse.link(entry, specifier, condition, parentURL, imports, artifacts, visited[, options])`
+### `const generator = traverse.link(entry, specifier, condition, parentURL, imports, artifacts, visited[, options])`
 
-#### `const generator = traverse.addons(parentURL, artifacts, visited[, options])`
+### `const generator = traverse.addons(parentURL, artifacts, visited[, options])`
 
-#### `const generator = traverse.assets(patterns, parentURL, artifacts, visited[, options])`
+### `const generator = traverse.assets(patterns, parentURL, artifacts, visited[, options])`
 
 ## License
 

package/index.d.ts

@@ -36,9 +36,42 @@ type AliasableExtension =
 interface TraverseOptions extends ResolveOptions {
   defaultType?: number
   aliases?: Record<string, AliasableExtension>
+  /**
+   * @param entry - The import to resolve, as produced by `bare-module-lexer`.
+   * @param parentURL - The WHATWG `URL` to resolve `entry` relative to.
+   * @param opts - Resolve options forwarded to the underlying resolution algorithm.
+   * @returns A `Resolver` that yields the candidate resolutions for `entry`.
+   */
   resolve?: (entry: Import, parentURL: URL, opts?: ResolveOptions) => Resolver
+  /**
+   * Record a specifier that resolves nowhere under `deferredProtocol` rather
+   * than throwing, leaving it for whoever names it to resolve when they get
+   * there. Only for callers that reach a resolver again, such as a module
+   * system; a tool that only links wants the error.
+   */
+  deferUnresolved?: boolean
 }
 
+/**
+ * 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.
+ * @param entry - The WHATWG `URL` of the entry module to root the graph at.
+ * @param readModule - 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.
+ * @param listPrefix - 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.
+ * @param probeModule - Called with the `URL` of each module to probe for existence; returns a
+ * boolean, or `undefined` to fall back to `readModule`.
+ * @param resolveModule - Called with each resolution `URL` to transform; returns the `URL` to use
+ * in its place. Defaults to the identity function.
+ * @returns An iterable of resolved `Dependency` records for the module graph; asynchronous when any
+ * callback returns a promise.
+ */
 declare function traverse(
   entry: URL,
   readModule: (url: URL) => Buffer | string | null,

package/index.js

@@ -464,7 +464,8 @@ function* resolveImport(entry, specifier, condition, parentURL, imports, artifac
     resolve = exports.resolve.default,
     builtinProtocol = 'builtin:',
     linkedProtocol = 'linked:',
-    deferredProtocol = 'deferred:'
+    deferredProtocol = 'deferred:',
+    deferUnresolved = false
   } = opts
 
   const matchedConditions = []
@@ -586,6 +587,12 @@ function* resolveImport(entry, specifier, condition, parentURL, imports, artifac
     }
   }
 
+  if (resolutions === 0 && deferUnresolved) {
+    addResolution(imports, specifier, matchedConditions, new URL(deferredProtocol + specifier))
+
+    resolutions++
+  }
+
   matchedConditions.pop()
 
   if (resolutions === 0) {

package/lib/resolve/bare.d.ts

@@ -7,6 +7,12 @@ interface BareResolveOptions extends ResolveOptions {
   hosts?: string[]
 }
 
+/**
+ * @param entry - The import to resolve, as produced by `bare-module-lexer`.
+ * @param parentURL - The WHATWG `URL` to resolve `entry` relative to.
+ * @param opts - Resolve options forwarded to the underlying resolution algorithm.
+ * @returns A `Resolver` that yields the candidate resolutions for `entry`.
+ */
 declare function resolve(entry: Import, parentURL: URL, opts?: BareResolveOptions): Resolver
 
 declare namespace resolve {

package/lib/resolve/default.d.ts

@@ -1,6 +1,12 @@
 import { type Import } from 'bare-module-lexer'
 import { type ResolveOptions, type Resolver } from 'bare-addon-resolve'
 
+/**
+ * @param entry - The import to resolve, as produced by `bare-module-lexer`.
+ * @param parentURL - The WHATWG `URL` to resolve `entry` relative to.
+ * @param opts - Resolve options forwarded to the underlying resolution algorithm.
+ * @returns A `Resolver` that yields the candidate resolutions for `entry`.
+ */
 declare function resolve(entry: Import, parentURL: URL, opts?: ResolveOptions): Resolver
 
 export = resolve

package/lib/resolve/node.d.ts

@@ -6,6 +6,12 @@ interface NodeResolveOptions extends ResolveOptions {
   hosts?: string[]
 }
 
+/**
+ * @param entry - The import to resolve, as produced by `bare-module-lexer`.
+ * @param parentURL - The WHATWG `URL` to resolve `entry` relative to.
+ * @param opts - Resolve options forwarded to the underlying resolution algorithm.
+ * @returns A `Resolver` that yields the candidate resolutions for `entry`.
+ */
 declare function resolve(entry: Import, parentURL: URL, opts?: NodeResolveOptions): Resolver
 
 declare namespace resolve {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-module-traverse",
-  "version": "2.4.4",
+  "version": "2.5.0",
   "description": "Low-level module graph traversal for Bare",
   "exports": {
     ".": {