@flex-development/mlly 1.0.0-alpha.1 → 1.0.0-alpha.11

package/src/utils/resolve-module.ts

@@ -0,0 +1,153 @@
+/**
+ * @file resolveModule
+ * @module mlly/utils/resolveModule
+ */
+
+import type { ResolveModuleOptions } from '#src/interfaces'
+import isFunction from '#src/internal/is-function'
+import Resolver from '#src/internal/resolver'
+import { ErrorCode, type NodeError } from '@flex-development/errnode'
+import { isBuiltin } from '@flex-development/is-builtin'
+import pathe from '@flex-development/pathe'
+import type { Nullable } from '@flex-development/tutils'
+import { URL, fileURLToPath } from 'node:url'
+import CONDITIONS from './conditions'
+import RESOLVE_EXTENSIONS from './resolve-extensions'
+
+/**
+ * Resolves `specifier` according to the [ESM Resolver algorithm][1], mostly 😉.
+ *
+ * Adds support for:
+ *
+ * - Extensionless file and directory index resolution
+ * - Replacing file extensions
+ *
+ * Other differences between Node.js:
+ *
+ * - [Subpath import][2] targets (that are strings) must be relative to the
+ *   current working directory (e.g. `'./src/index.ts'`, `'./src/*.ts'`) or
+ *   start with a [NPM valid package name][3]. See [`nodejs/node#40579`][4] for
+ *   details.
+ *
+ * [1]: https://nodejs.org/api/esm.html#esm_resolver_algorithm
+ * [2]: https://nodejs.org/api/packages.html#subpath-imports
+ * [3]: https://regex101.com/r/BHcJfc
+ * [4]: https://github.com/nodejs/node/issues/40579
+ *
+ * @see {@linkcode NodeError}
+ * @see {@linkcode ResolveModuleOptions}
+ * @see {@linkcode URL}
+ *
+ * @async
+ *
+ * @param {string} specifier - Module specifier to resolve
+ * @param {ResolveModuleOptions} [options={}] - Module resolution options
+ * @return {Promise<URL>} Resolved module URL
+ * @throws {NodeError}
+ */
+const resolveModule = async (
+  specifier: string,
+  options: ResolveModuleOptions = {}
+): Promise<URL> => {
+  const {
+    condition = 'default',
+    conditions = CONDITIONS,
+    extensions = RESOLVE_EXTENSIONS,
+    parent = import.meta.url,
+    preserveSymlinks = false
+  } = options
+
+  /**
+   * Module resolver.
+   *
+   * @const {Resolver} resolver
+   */
+  const resolver: Resolver = new Resolver()
+
+  /**
+   * Module ids to try resolving.
+   *
+   * @const {string[]} tries
+   */
+  const tries: string[] =
+    isBuiltin(specifier) ||
+    (/^\S+:/.test(specifier) && !specifier.startsWith('file:'))
+      ? []
+      : [...extensions]
+          .flatMap(ext => [
+            specifier + (ext = pathe.formatExt(ext)),
+            specifier.startsWith('#') ? specifier + '/index' : '',
+            specifier + '/index' + ext
+          ])
+          .filter(id => id.length > 0)
+
+  // ensure attempt to resolve original specifier is first
+  tries.unshift(specifier)
+
+  /**
+   * Error codes to ignore when attempting to resolve {@linkcode specifier}.
+   *
+   * **Note**: If an error is thrown, it'll be reported **_after_** all module
+   * ids in {@linkcode tries} have been evaluated.
+   *
+   * @const {Set<ErrorCode>} ignore
+   */
+  const ignore: Set<ErrorCode> = new Set<ErrorCode>([
+    ErrorCode.ERR_MODULE_NOT_FOUND,
+    ErrorCode.ERR_PACKAGE_PATH_NOT_EXPORTED,
+    ErrorCode.ERR_UNSUPPORTED_DIR_IMPORT
+  ])
+
+  /**
+   * Module resolution error.
+   *
+   * @var {NodeError} error
+   */
+  let error: NodeError
+
+  /**
+   * Resolved module URL.
+   *
+   * @var {Nullable<URL>} url
+   */
+  let url: Nullable<URL> = null
+
+  // try module resolution
+  for (const id of tries) {
+    try {
+      url = resolver.resolveModule(
+        id,
+        parent,
+        condition,
+        new Set(conditions),
+        preserveSymlinks
+      )
+    } catch (e: unknown) {
+      url = null
+      if (id === specifier) error = e as NodeError
+      if (!ignore.has((e as NodeError).code)) throw e
+    }
+
+    // stop resolution attempts if module was resolved
+    if (url) break
+  }
+
+  // throw if module was not resolved
+  if (!url) throw error!
+
+  // replace file extension
+  if (url.protocol === 'file:') {
+    let { ext } = options
+
+    // get replacement extension
+    ext = isFunction(ext) ? await ext(specifier, url) : ext
+
+    // replace file extension in url href and pathname
+    url.href = pathe.changeExt(url.href, ext).replace(/\/index$/, '')
+    url.pathname = fileURLToPath(url.href)
+  }
+
+  return url
+}
+
+export default resolveModule

package/src/utils/resolve-modules.ts

@@ -0,0 +1,62 @@
+/**
+ * @file resolveModules
+ * @module mlly/utils/resolveModules
+ */
+
+import { SpecifierSyntaxKind } from '#src/enums'
+import type { ResolveModuleOptions } from '#src/interfaces'
+import regexp from '#src/internal/escape-reg-exp'
+import type { URL } from 'node:url'
+import extractStatements from './extract-statements'
+import resolveModule from './resolve-module'
+
+/**
+ * Converts all module specifiers in `code` to absolute specifiers.
+ *
+ * ::: info
+ * Useful for converting code to [`data:` URLs][1].
+ * :::
+ *
+ * [1]: https://nodejs.org/api/esm.html#data-imports
+ *
+ * @see {@linkcode ResolveModuleOptions}
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @async
+ *
+ * @param {string} code - Code to evaluate
+ * @param {ResolveModuleOptions} [options={}] - Module resolution options
+ * @return {Promise<string>} `code` with module specifiers fully resolved
+ */
+const resolveModules = async (
+  code: string,
+  options: ResolveModuleOptions = {}
+): Promise<string> => {
+  for (const statement of extractStatements(code)) {
+    // do nothing if statement does not have specifier
+    if (!statement.specifier) continue
+
+    // ignore statements with dynamic specifiers
+    if (statement.specifier_syntax === SpecifierSyntaxKind.DYNAMIC) continue
+
+    /**
+     * Resolved module URL.
+     *
+     * @const {URL} url
+     */
+    const url: URL = await resolveModule(statement.specifier, options)
+
+    // replace original specifier
+    code = code.replace(
+      statement.code,
+      statement.code.replace(
+        new RegExp(`(?<=["'])${regexp(statement.specifier)}(?=["'])`),
+        url.href
+      )
+    )
+  }
+
+  return code
+}
+
+export default resolveModules

package/src/utils/to-absolute-specifier.ts

@@ -0,0 +1,30 @@
+/**
+ * @file toAbsoluteSpecifier
+ * @module mlly/utils/toAbsoluteSpecifier
+ */
+
+import type { ModuleId } from '#src/types'
+import { pathToFileURL } from 'node:url'
+import toURL from './to-url'
+
+/**
+ * Converts `specifier` into an absolute specifier.
+ *
+ * ::: info
+ * The absolute specifier will only include a file extension if `specifier`
+ * includes a file extension.
+ * :::
+ *
+ * @see {@linkcode ModuleId}
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @param {ModuleId} specifier - Module specifier to convert
+ * @param {ModuleId} [cwd=pathToFileURL('./')] - Current working directory
+ * @return {string} `specifier` as absolute specifier (file url)
+ */
+const toAbsoluteSpecifier = (
+  specifier: ModuleId,
+  cwd: ModuleId = pathToFileURL('./')
+): string => toURL(specifier, cwd).href
+
+export default toAbsoluteSpecifier

package/src/utils/to-bare-specifier.ts

@@ -0,0 +1,201 @@
+/**
+ * @file toBareSpecifier
+ * @module mlly/utils/toBareSpecifier
+ */
+
+import type { PackageScope, ParsedModuleId } from '#src/interfaces'
+import regexp from '#src/internal/escape-reg-exp'
+import validateURLString from '#src/internal/validate-url-string'
+import type { ModuleId } from '#src/types'
+import {
+  ERR_OPERATION_FAILED,
+  ERR_PACKAGE_PATH_NOT_EXPORTED,
+  ErrorCode,
+  type NodeError
+} from '@flex-development/errnode'
+import { isBuiltin } from '@flex-development/is-builtin'
+import pathe from '@flex-development/pathe'
+import { isNIL, type Nullable } from '@flex-development/tutils'
+import { URL, fileURLToPath, pathToFileURL } from 'node:url'
+import CONDITIONS from './conditions'
+import findSubpath from './find-subpath'
+import isAbsoluteSpecifier from './is-absolute-specifier'
+import isRelativeSpecifier from './is-relative-specifier'
+import lookupPackageScope from './lookup-package-scope'
+import parseModuleId from './parse-module-id'
+import parseSubpath from './parse-subpath'
+import PATTERN_CHARACTER from './pattern-character'
+import toAbsoluteSpecifier from './to-absolute-specifier'
+import toNodeURL from './to-node-url'
+import toURL from './to-url'
+
+/**
+ * Converts the given module `specifier` into a bare specifier.
+ *
+ * The new specifier is **not** guaranteed to resolve to an existing module, nor
+ * is it guaranteed to have a file extension, but it *is* guaranteed to be a
+ * package path containing a valid [subpath export][1] if the specifier's parent
+ * package uses package [`exports`][2]. If the parent package does not use
+ * `exports`, the new specifier is only guaranteed to begin with a valid NPM
+ * package name or Node.js [builtin module][3] name.
+ *
+ * The given module `specifier` should be absolute, syntactically bare (i.e. not
+ * begin with `'/'` or `'.'`), or relative to the current working directory
+ * (e.g. `'./dist/index.mjs'`).
+ *
+ * ::: warning
+ * Internal specifier (i.e. [subpath import][4]; `'#src'`, `'#src/utils'`)
+ * conversion is not supported. Converting *_to_* an internal specifier will be
+ * supported in the future.
+ * :::
+ *
+ * [1]: https://nodejs.org/api/packages.html#subpath-exports
+ * [2]: https://nodejs.org/api/packages.html#exports
+ * [3]: https://nodejs.org/api/module.html#modulebuiltinmodules
+ * [4]: https://nodejs.org/api/packages.html#subpath-imports
+ *
+ * @see {@linkcode CONDITIONS}
+ * @see {@linkcode ModuleId}
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @param {ModuleId} specifier - Module specifier to convert
+ * @param {ModuleId} parent - URL of module to resolve from
+ * @param {Set<string>?} [conditions=CONDITIONS] - Export conditions
+ * @return {string} `specifier` as bare specifier
+ * @throws {NodeError}
+ */
+const toBareSpecifier = (
+  specifier: ModuleId,
+  parent: ModuleId,
+  conditions: Set<string> = CONDITIONS
+): string => {
+  validateURLString(specifier, 'specifier')
+  validateURLString(parent, 'parent')
+
+  // ensure specifier is a string
+  if (specifier instanceof URL) specifier = specifier.href
+
+  // exit early if specifier is builtin module
+  if (isBuiltin(specifier)) return toNodeURL(specifier)
+
+  // ensure specifier is a path
+  if (specifier.startsWith('file:')) specifier = fileURLToPath(specifier)
+
+  // convert relative specifiers to absolute paths
+  if (isRelativeSpecifier(specifier)) {
+    specifier = fileURLToPath(toAbsoluteSpecifier(specifier))
+  }
+
+  /**
+   * Location to begin package scope search for {@linkcode specifier}.
+   *
+   * @const {URL} url
+   */
+  const url: URL = toURL(
+    isAbsoluteSpecifier(specifier) || specifier.startsWith('node_modules')
+      ? specifier
+      : `node_modules/${specifier}`
+  )
+
+  /**
+   * Package scope result for {@linkcode specifier}.
+   *
+   * @const {Nullable<PackageScope>} scope
+   */
+  const scope: Nullable<PackageScope> = lookupPackageScope(
+    url,
+    pathToFileURL('.')
+  )
+
+  // throw if package scope was not found
+  if (!scope) {
+    throw new ERR_OPERATION_FAILED(`Package scope for '${specifier}' not found`)
+  }
+
+  // get directory containing package.json file and package.json object
+  const { dir: pkgdir, pkgjson } = scope
+
+  // get package exports and name
+  const { exports, main, name = '', types } = pkgjson
+
+  // convert specifier to bare specifier
+  specifier = url.pathname.includes(name)
+    ? name + url.pathname.replace(new RegExp(`.*?${regexp(name)}`), '')
+    : name + specifier.replace(fileURLToPath(pkgdir.replace(/\/$/, '')), '')
+
+  /**
+   * Parsed module specifier.
+   *
+   * Ensures {@linkcode specifier} has become a bare specifier.
+   *
+   * @const {ParsedModuleId} id
+   */
+  const id: ParsedModuleId = parseModuleId(specifier, {
+    internal: false,
+    parent,
+    pkgname: true
+  })
+
+  // exit early if subpath does not need to be validated
+  if (isNIL(exports)) {
+    return [main, types].some(ep => ep === id.path || ep === id.path.slice(2))
+      ? id.pkg
+      : specifier
+  }
+
+  // check if specifier contains valid subpath export
+  try {
+    parseSubpath(specifier, exports, { dir: pkgdir, parent })
+  } catch (e: unknown) {
+    // try finding defined subpath if specifier is invalid package path
+    if ((e as NodeError).code === ErrorCode.ERR_PACKAGE_PATH_NOT_EXPORTED) {
+      /**
+       * Package target to find defined subpath for.
+       *
+       * @const {string} target
+       */
+      const target: string = specifier.replace(name, '.')
+
+      /**
+       * Subpath in {@linkcode exports} thats maps to {@linkcode target}, if any
+       * at all.
+       *
+       * @var {Nullable<string>} subpath
+       */
+      let subpath: Nullable<string> = findSubpath(target, exports, {
+        conditions,
+        dir: pkgdir,
+        parent
+      })
+
+      // throw if target was not matched to a subpath
+      if (subpath === null) {
+        throw new ERR_PACKAGE_PATH_NOT_EXPORTED(
+          fileURLToPath(pkgdir),
+          id.path,
+          fileURLToPath(parent)
+        )
+      }
+
+      // replace pattern character in subpath
+      if (subpath.includes(PATTERN_CHARACTER)) {
+        subpath = subpath.slice(0, subpath.indexOf(PATTERN_CHARACTER)).slice(1)
+        subpath = '.' + target.slice(target.indexOf(subpath))
+      }
+
+      // subpath should not include extension if extension is already included
+      // via package target
+      if (pathe.extname(target) === pathe.extname(subpath)) {
+        subpath = pathe.changeExt(subpath, '')
+      }
+
+      return name + subpath.slice(1)
+    } /* c8 ignore next 3 */
+    // throw original error if package path error is not encountered
+    throw e
+  }
+
+  return specifier
+}
+
+export default toBareSpecifier

package/src/utils/to-data-url.ts

@@ -0,0 +1,42 @@
+/**
+ * @file toDataURL
+ * @module mlly/utils/toDataURL
+ */
+
+import validateString from '#src/internal/validate-string'
+import type { MimeType } from '#src/types'
+import type { NodeError } from '@flex-development/errnode'
+
+/**
+ * Converts `code` into a [`data:` URL][1] using `base64` encoding.
+ *
+ * ::: tip
+ * `data:` URLs only resolve [bare specifiers][2] for builtin modules and
+ * [absolute specifiers][2].
+ *
+ * Call [`await resolveModules(code)`][3] to ensure all specifiers are absolute
+ * or bare.
+ * :::
+ *
+ * [1]: https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
+ * [2]: https://nodejs.org/api/esm.html#terminology
+ * [3]: {@link ./resolve-modules.ts}
+ *
+ * @see {@linkcode MimeType}
+ * @see https://nodejs.org/api/esm.html#esm_data_imports
+ *
+ * @param {string} code - Code to convert
+ * @param {MimeType} [mime='text/javascript'] - MIME type
+ * @return {string} `code` as `data:` URL
+ * @throws {NodeError<TypeError>} If `code` or `mime` is not a string
+ */
+const toDataURL = (
+  code: string,
+  mime: MimeType = 'text/javascript'
+): string => {
+  validateString(code, 'code')
+  validateString(mime, 'mime')
+  return `data:${mime};base64,${Buffer.from(code).toString('base64')}`
+}
+
+export default toDataURL

package/src/utils/to-node-url.ts

@@ -0,0 +1,27 @@
+/**
+ * @file toNodeURL
+ * @module mlly/utils/toNodeURL
+ */
+
+import validateString from '#src/internal/validate-string'
+import type { NodeError } from '@flex-development/errnode'
+
+/**
+ * Converts the given module `specifier` to a `node:` URL.
+ *
+ * ::: warning
+ * Does not guarantee the new specifier is an existing Node.js builtin module.
+ * :::
+ *
+ * @see https://nodejs.org/api/esm.html#node-imports
+ *
+ * @param {string} specifier - Module specifier to convert
+ * @return {string} `specifier` as `node:` URL
+ * @throws {NodeError<TypeError>} If `specifier` is not a string
+ */
+const toNodeURL = (specifier: string): string => {
+  validateString(specifier, 'specifier')
+  return specifier.startsWith('node:') ? specifier : `node:${specifier}`
+}
+
+export default toNodeURL

package/src/utils/to-relative-specifier.ts

@@ -0,0 +1,47 @@
+/**
+ * @file toRelativeSpecifier
+ * @module mlly/utils/toRelativeSpecifier
+ */
+
+import type { ModuleId } from '#src/types'
+import pathe from '@flex-development/pathe'
+import { URL, fileURLToPath } from 'node:url'
+
+/**
+ * Converts `specifier` into a relative specifier.
+ *
+ * ::: info
+ * The relative specifier will only include a file extension if `specifier`
+ * includes a file extension.
+ * :::
+ *
+ * @see {@linkcode ModuleId}
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @param {ModuleId} specifier - Module specifier to convert
+ * @param {ModuleId} parent - Parent module URL or path to resolve from
+ * @return {string} `specifier` as relative specifier
+ */
+const toRelativeSpecifier = (specifier: ModuleId, parent: ModuleId): string => {
+  // convert file url objects to file url strings
+  if (parent instanceof URL) parent = parent.href
+  if (specifier instanceof URL) specifier = specifier.href
+
+  // convert file url strings to paths
+  if (parent.startsWith('file:')) parent = fileURLToPath(parent)
+  if (specifier.startsWith('file:')) specifier = fileURLToPath(specifier)
+
+  // convert specifier to relative specifier
+  specifier = pathe
+    .relative(pathe.resolve(parent), pathe.resolve(specifier))
+    .replace(/^\.\.\/?/, '')
+    .replace(/^(\w)/, './$1')
+
+  // set specifier to dot character if empty string
+  // this occurs when specifier is a directory, but is not fully specified
+  if (!specifier) specifier = '.'
+
+  return specifier
+}
+
+export default toRelativeSpecifier

package/src/utils/to-url.ts

@@ -0,0 +1,31 @@
+/**
+ * @file toURL
+ * @module mlly/utils/toURL
+ */
+
+import validateURLString from '#src/internal/validate-url-string'
+import type { ModuleId } from '#src/types'
+import type { NodeError } from '@flex-development/errnode'
+import { URL, pathToFileURL } from 'node:url'
+
+/**
+ * Converts the given module `id` to an instance of [`URL`][1].
+ *
+ * [1]: https://nodejs.org/api/url.html#class-url
+ *
+ * @see {@linkcode ModuleId}
+ *
+ * @param {ModuleId} id - Module id to evaluate
+ * @param {ModuleId?} [base=pathToFileURL('./')] - Base URL to resolve against
+ * if `id` is not absolute
+ * @return {URL} `id` as instance of `URL`
+ * @throws {NodeError<TypeError>} If either `id` or `base` is not a string or an
+ * instance of `URL`
+ */
+const toURL = (id: ModuleId, base: ModuleId = pathToFileURL('./')): URL => {
+  validateURLString(id, 'id')
+  validateURLString(base, 'base')
+  return id instanceof URL ? id : new URL(id, base)
+}
+
+export default toURL