bare-module-traverse 2.4.0 → 2.4.2

package/README.md

@@ -72,6 +72,8 @@ options = {
 }
 ```
 
+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.
@@ -165,11 +167,12 @@ The following generator functions implement the traversal algorithm. The yielded
 
 **Source module**
 
-A module to be read. The driver returns its source if it exists, otherwise `null`.
+A module to be read. The driver returns its source if it exists, otherwise `null`. When `artifact` is `true`, the module is an addon or asset whose contents are loaded lazily and referenced by path. A driver that only needs to locate such artifacts, such as a module loader, may return `null` without reading, having already established existence by probing; a driver that embeds their contents, such as a bundler, reads them as normal.
 
 ```js
 next.value = {
-  module: URL
+  module: URL,
+  artifact: boolean
 }
 ```
 
@@ -265,7 +268,9 @@ function drive(generator) {
     const value = next.value
 
     if (value.module) {
-      // Read `value.module` if it exists, otherwise `null`
+      // Read `value.module` if it exists, otherwise `null`. When
+      // `value.artifact` is `true`, the module is an addon or asset that may be
+      // left unread, returning `null`, unless its contents are needed
       let source
 
       next = generator.next(source)
@@ -322,7 +327,7 @@ Options are the same as `traverse()` for all functions.
 
 #### `const generator = traverse.preresolved(url, source, resolutions, artifacts, visited[, options])`
 
-#### `const generator = traverse.imports(parentURL, source, imports, artifacts, 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])`
 

package/index.d.ts

@@ -77,7 +77,7 @@ declare namespace traverse {
   export { type TraverseOptions }
 
   export type Traversal = Generator<
-    | { module: URL }
+    | { module: URL; artifact: boolean }
     | { probe: URL }
     | { resolution: URL }
     | { prefix: URL }
@@ -134,6 +134,10 @@ declare namespace traverse {
     source: string | Buffer,
     imports: ImportsMap,
     artifacts: Artifacts,
+    lexer: {
+      imports: Import[]
+      exports: Export[]
+    },
     visited: Set<string>,
     opts?: TraverseOptions
   ): Traversal
@@ -149,8 +153,8 @@ declare namespace traverse {
     opts?: TraverseOptions
   ): Traversal
 
-  export function prebuilds(
-    packageURL: URL,
+  export function addons(
+    parentURL: URL,
     artifacts: Artifacts,
     visited: Set<string>,
     opts?: TraverseOptions
@@ -158,7 +162,7 @@ declare namespace traverse {
 
   export function assets(
     patterns: ConditionalSpecifier,
-    packageURL: URL,
+    parentURL: URL,
     artifacts: Artifacts,
     visited: Set<string>,
     opts?: TraverseOptions

package/index.js

@@ -1,5 +1,6 @@
 const { lookupPackageScope, conditionMatches } = require('bare-module-resolve')
 const lex = require('bare-module-lexer')
+const MIME = require('bare-mime')
 const resolve = require('./lib/resolve')
 const errors = require('./lib/errors')
 
@@ -196,16 +197,20 @@ exports.module = function* (url, source, attributes, artifacts, visited, opts =
   const artifact = asset === true || moduleType(url, attributes, null, opts) === constants.ADDON
 
   if (source === null) {
-    const exists = probed !== undefined ? probed : artifact ? yield { probe: url } : undefined
+    if (url.protocol === 'data:') {
+      source = decodeDataURL(url)
+    } else {
+      const exists = probed !== undefined ? probed : artifact ? yield { probe: url } : undefined
 
-    if (exists === false) {
-      throw errors.MODULE_NOT_FOUND(`Cannot find module '${url.href}'`, url.href)
-    }
+      if (exists === false) {
+        throw errors.MODULE_NOT_FOUND(`Cannot find module '${url.href}'`, url.href)
+      }
 
-    source = yield { module: url }
+      source = yield { module: url, artifact }
 
-    if (exists !== true && source === null) {
-      throw errors.MODULE_NOT_FOUND(`Cannot find module '${url.href}'`, url.href)
+      if (exists !== true && source === null) {
+        throw errors.MODULE_NOT_FOUND(`Cannot find module '${url.href}'`, url.href)
+      }
     }
   }
 
@@ -219,27 +224,29 @@ exports.module = function* (url, source, attributes, artifacts, visited, opts =
 
   let info = null
 
-  for (const packageURL of lookupPackageScope(url, opts)) {
-    const source = yield { module: packageURL }
+  if (url.protocol !== 'data:') {
+    for (const packageURL of lookupPackageScope(url, opts)) {
+      const source = yield { module: packageURL, artifact: false }
 
-    if (source !== null) {
-      info = JSON.parse(source)
+      if (source !== null) {
+        info = JSON.parse(source)
 
-      imports['#package'] = packageURL.href
+        imports['#package'] = packageURL.href
 
-      yield {
-        children: exports.package(packageURL, source, artifacts, visited, opts),
-        deferred: false
-      }
+        yield {
+          children: exports.package(packageURL, source, artifacts, visited, opts),
+          deferred: false
+        }
 
-      break
+        break
+      }
     }
   }
 
   if (typeof attributes.imports === 'string') {
     const url = new URL(attributes.imports)
 
-    const source = yield { module: url }
+    const source = yield { module: url, artifact: false }
 
     if (source !== null) {
       opts = {
@@ -255,7 +262,10 @@ exports.module = function* (url, source, attributes, artifacts, visited, opts =
 
   if (asset === false) {
     if (type === constants.SCRIPT || type === constants.MODULE) {
-      yield* exports.imports(url, source, imports, artifacts, lexer, visited, opts)
+      yield* exports.imports(url, source, imports, artifacts, lexer, visited, {
+        ...opts,
+        referrerType: type
+      })
     } else if (type === constants.ADDON) {
       yield* exports.addons(url, artifacts, visited, opts)
     }
@@ -280,7 +290,7 @@ exports.package = function* (url, source, artifacts, visited, opts = {}) {
   visited.add(url.href)
 
   if (source === null) {
-    source = yield { module: url }
+    source = yield { module: url, artifact: false }
 
     if (source === null) return false
   }
@@ -339,16 +349,12 @@ exports.preresolved = function* (url, source, resolutions, artifacts, visited, o
         } else if (asset) {
           addURL(artifacts.assets, url)
 
-          const source = yield { module: url }
-
-          if (source !== null) {
-            yield {
-              children: exports.module(url, source, {}, artifacts, visited, {
-                ...opts,
-                asset: true
-              }),
-              deferred: true
-            }
+          yield {
+            children: exports.module(url, null, {}, artifacts, visited, {
+              ...opts,
+              asset: true
+            }),
+            deferred: true
           }
         } else if (
           url.protocol !== builtinProtocol &&
@@ -473,7 +479,7 @@ function* resolveImport(entry, specifier, condition, parentURL, imports, artifac
     const value = next.value
 
     if (value.package) {
-      next = resolver.next(JSON.parse(yield { module: value.package }))
+      next = resolver.next(JSON.parse(yield { module: value.package, artifact: false }))
     } else {
       const url = value.resolution
 
@@ -510,19 +516,22 @@ function* resolveImport(entry, specifier, condition, parentURL, imports, artifac
         }
 
         if (resolved) addResolution(imports, specifier, matchedConditions, url)
-      } else if (condition === 'addon') {
+      } else if (
+        condition === 'addon' ||
+        moduleType(url, entry.attributes, null, opts) === constants.ADDON
+      ) {
         let exists = yield { probe: url }
         let source = null
 
         if (exists === undefined) {
-          source = yield { module: url }
+          source = yield { module: url, artifact: false }
           exists = source !== null
         }
 
         if (exists) {
           resolution = yield* postresolve(url)
 
-          addResolution(imports, specifier, matchedConditions, resolution)
+          addResolution(imports, specifier, matchedConditions, exports.alias(resolution, opts))
 
           yield {
             children: exports.module(resolution, source, {}, artifacts, visited, {
@@ -535,7 +544,13 @@ function* resolveImport(entry, specifier, condition, parentURL, imports, artifac
           resolved = true
         }
       } else {
-        const source = yield { module: url }
+        let source
+
+        if (url.protocol === 'data:') {
+          source = decodeDataURL(url)
+        } else {
+          source = yield { module: url, artifact: false }
+        }
 
         if (source !== null) {
           resolution = yield* postresolve(url)
@@ -621,23 +636,19 @@ exports.assets = function* (patterns, parentURL, artifacts, visited, opts = {})
   let yielded = false
 
   for (const url of matches) {
-    const source = yield { module: url }
-
-    if (source !== null) {
-      const resolution = yield* postresolve(url)
-
-      addURL(artifacts.assets, resolution)
+    const resolution = yield* postresolve(url)
 
-      yield {
-        children: exports.module(resolution, source, {}, artifacts, visited, {
-          ...opts,
-          asset: true
-        }),
-        deferred: true
-      }
+    addURL(artifacts.assets, resolution)
 
-      yielded = true
+    yield {
+      children: exports.module(resolution, null, {}, artifacts, visited, {
+        ...opts,
+        asset: true
+      }),
+      deferred: true
     }
+
+    yielded = true
   }
 
   return yielded
@@ -711,7 +722,7 @@ function* postresolve(url) {
 }
 
 function moduleType(url, attributes, info, opts = {}) {
-  const { defaultType = constants.SCRIPT, aliases = null } = opts
+  const { defaultType = constants.SCRIPT, referrerType, aliases = null } = opts
 
   if (typeof attributes.type === 'string') {
     switch (attributes.type) {
@@ -734,6 +745,20 @@ function moduleType(url, attributes, info, opts = {}) {
     return 0
   }
 
+  if (url.protocol === 'data:') {
+    const { mime } = parseDataURL(url)
+
+    if (mime === null || mime.subtype === 'javascript') {
+      if (referrerType) return referrerType
+
+      return defaultType === constants.MODULE ? constants.MODULE : constants.SCRIPT
+    }
+
+    if (mime.subtype === 'json') return constants.JSON
+
+    return defaultType
+  }
+
   const match = url.pathname.match(/\.[a-z]+$/)
 
   if (match === null) return defaultType
@@ -770,6 +795,36 @@ function moduleType(url, attributes, info, opts = {}) {
   return defaultType
 }
 
+function parseDataURL(url) {
+  const { pathname } = url
+
+  const comma = pathname.indexOf(',')
+
+  const meta = comma === -1 ? pathname : pathname.slice(0, comma)
+  const data = comma === -1 ? '' : pathname.slice(comma + 1)
+
+  const base64 = /;base64$/i.test(meta)
+
+  return { mime: MIME.parse(meta), base64, data }
+}
+
+function decodeDataURL(url) {
+  const { mime, base64, data } = parseDataURL(url)
+
+  const charset = mime === null ? undefined : mime.parameters.get('charset')
+
+  if (charset !== undefined && !/^utf-?8$/i.test(charset)) {
+    throw errors.UNKNOWN_DATA_URL_CHARSET(
+      `Unsupported charset '${charset}' in data URL '${url.href}'`,
+      charset
+    )
+  }
+
+  if (base64) return Buffer.from(data, 'base64')
+
+  return decodeURIComponent(data)
+}
+
 function addURL(collection, url) {
   if (Array.isArray(collection)) {
     let lo = 0

package/lib/errors.js

@@ -45,4 +45,12 @@ module.exports = class ModuleTraverseError extends Error {
   static INVALID_IMPORTS_MAP(msg) {
     return new ModuleTraverseError(msg, ModuleTraverseError.INVALID_IMPORTS_MAP)
   }
+
+  static UNKNOWN_DATA_URL_CHARSET(msg, charset) {
+    const err = new ModuleTraverseError(msg, ModuleTraverseError.UNKNOWN_DATA_URL_CHARSET)
+
+    err.charset = charset
+
+    return err
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-module-traverse",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "Low-level module graph traversal for Bare",
   "exports": {
     ".": {
@@ -55,6 +55,7 @@
   "homepage": "https://github.com/holepunchto/bare-module-traverse#readme",
   "dependencies": {
     "bare-addon-resolve": "^1.5.0",
+    "bare-mime": "^1.0.0",
     "bare-module-lexer": "^1.6.0",
     "bare-module-resolve": "^1.7.0"
   },