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

package/src/utils/find-subpath.ts

@@ -0,0 +1,241 @@
+/**
+ * @file findSubpath
+ * @module mlly/utils/findSubpath
+ */
+
+import type { FindSubpathOptions } from '#src/interfaces'
+import getSubpaths from '#src/internal/get-subpaths'
+import validateBoolean from '#src/internal/validate-boolean'
+import validateSet from '#src/internal/validate-set'
+import validateString from '#src/internal/validate-string'
+import validateURLString from '#src/internal/validate-url-string'
+import type { NodeError } from '@flex-development/errnode'
+import pathe from '@flex-development/pathe'
+import type { Exports, Imports } from '@flex-development/pkg-types'
+import { isNIL, type Nullable } from '@flex-development/tutils'
+import { URL } from 'node:url'
+import compareSubpaths from './compare-subpaths'
+import CONDITIONS from './conditions'
+import isExportsSugar from './is-exports-sugar'
+import PATTERN_CHARACTER from './pattern-character'
+import toURL from './to-url'
+
+/**
+ * Finds the subpath defined in `context`, a `package.json` [`exports`][1] or
+ * [`imports`][2] field, that maps to the given package `target`.
+ *
+ * Supports extensionless targets. Returns `null` if a subpath is not found.
+ *
+ * [1]: https://nodejs.org/api/packages.html#exports
+ * [2]: https://nodejs.org/api/packages.html#imports
+ *
+ * @see {@linkcode Exports}
+ * @see {@linkcode FindSubpathOptions}
+ * @see {@linkcode Imports}
+ * @see https://nodejs.org/api/packages.html#subpath-exports
+ * @see https://nodejs.org/api/packages.html#subpath-imports
+ *
+ * @param {string} target - Package target to find in `context`
+ * @param {Exports | Imports | undefined} context - Package context
+ * @param {FindSubpathOptions} options - Search options
+ * @return {Nullable<string>} Subpath defined in `context` or `null`
+ * @throws {NodeError<Error | TypeError>}
+ */
+const findSubpath = (
+  target: string,
+  context: Exports | Imports | undefined,
+  options: FindSubpathOptions
+): Nullable<string> => {
+  const {
+    condition = 'default',
+    conditions = CONDITIONS,
+    dir,
+    internal = false,
+    parent
+  } = options
+
+  // exit early if context is nil
+  if (isNIL(context)) return null
+
+  // ensure target is a string
+  validateString(target, 'target')
+
+  // exit early if target is an exactish match
+  if (typeof context === 'string') {
+    if (target === context || target === pathe.changeExt(context, '')) {
+      return '.'
+    }
+  }
+
+  // ensure option schemas
+  validateString(condition, 'options.condition')
+  validateSet(conditions, 'options.conditions')
+  validateURLString(dir, 'options.dir')
+  validateBoolean(internal, 'options.internal')
+  validateURLString(parent, 'options.parent')
+
+  /**
+   * Finds the subpath defined in `context`, a `package.json` [`exports`][1] or
+   * [`imports`][2] field, that maps to the given package `target`.
+   *
+   * Returns `null` if a subpath is not found.
+   *
+   * [1]: https://nodejs.org/api/packages.html#exports
+   * [2]: https://nodejs.org/api/packages.html#imports
+   *
+   * @param {string} target - Package target to find in `context`
+   * @param {Exports | Imports | undefined} context - Package context
+   * @param {string} [key='.'] - Subpath in `context` being checked
+   * @return {Nullable<string>} Subpath defined in `context` or `null`
+   */
+  const find = (
+    target: string,
+    context: Exports | Imports | undefined,
+    key: string = '.'
+  ): Nullable<string> => {
+    /**
+     * Subpath defined in {@linkcode context} that maps to {@linkcode target}.
+     *
+     * @var {Nullable<string>} subpath
+     */
+    let subpath: Nullable<string> = null
+
+    // match target to subpath
+    switch (true) {
+      case !isNIL(context) && typeof context === 'object':
+      case typeof context === 'string':
+        /**
+         * URL of directory containing relevant `package.json` file.
+         *
+         * @const {string} pkgdir
+         */
+        const pkgdir: string = toURL(dir).href.replace(/\/$/, '') + pathe.sep
+
+        /**
+         * URL of relevant `package.json` file.
+         *
+         * @const {URL} pkg
+         */
+        const pkg: URL = new URL('package.json', pkgdir)
+
+        // convert package context to object if using exports sugar
+        if (!internal && isExportsSugar(context, pkg, parent)) {
+          context = { [key]: context } as Record<string, Exports>
+        }
+
+        // context is now an object
+        context = context as Record<string, Exports>
+
+        /**
+         * Subpaths defined in {@linkcode context}.
+         *
+         * **Note**: Sorted from least to greatest.
+         *
+         * @see {@linkcode compareSubpaths}
+         *
+         * @const {string[]} keys
+         */
+        const subpaths: string[] = getSubpaths(
+          context,
+          internal,
+          pkg,
+          parent
+        ).sort((s1, s2) => compareSubpaths(s1, s2) * -1)
+
+        // match target to subpath defined in context
+        for (const pkgsubpath of subpaths) {
+          /**
+           * Current package target being checked.
+           *
+           * @var {Exports} tar
+           */
+          let tar: Exports = context[pkgsubpath]!
+
+          // find subpath
+          switch (true) {
+            case Array.isArray(tar):
+              tar = tar as string[]
+
+              // try matching target based first match in target array
+              for (const item of tar) {
+                subpath = find(target, item, pkgsubpath)
+                if (subpath) break
+              }
+
+              break
+            case typeof tar === 'object' && !isNIL(tar):
+              tar = tar as Record<string, Exports>
+
+              // try matching target based on export conditions
+              for (const prop of Object.getOwnPropertyNames(tar)) {
+                if (prop === condition || conditions.has(prop)) {
+                  subpath = find(target, tar[prop], pkgsubpath)
+                  if (subpath) break
+                }
+              }
+
+              break
+            case typeof tar === 'string':
+              tar = tar as string
+
+              /**
+               * {@linkcode tar} without file extension.
+               *
+               * @const {string} tar_no_ext
+               */
+              const tar_ne: string = pathe.changeExt(tar, '')
+
+              /**
+               * Index of {@linkcode PATTERN_CHARACTER} in {@linkcode tar}.
+               *
+               * @const {number} pattern
+               */
+              const pattern: number = tar.indexOf(PATTERN_CHARACTER)
+
+              switch (true) {
+                // target is an exactish match
+                case target === tar:
+                case target === tar_ne:
+                case pattern === -1 && (target === tar || target === tar_ne):
+                  subpath = pkgsubpath
+                  break
+                // pattern character => try finding best match for target
+                case pattern !== -1 && target.startsWith(tar.slice(0, pattern)):
+                  /**
+                   * Boolean indicating if {@linkcode target} ends with the
+                   * characters after the pattern character (`*`) in
+                   * {@linkcode tar}.
+                   *
+                   * @const {boolean} match
+                   */
+                  const match: boolean =
+                    target.length >= tar.length &&
+                    tar.lastIndexOf(PATTERN_CHARACTER) === pattern &&
+                    (target.endsWith(tar.slice(pattern + 1)) ||
+                      target.endsWith(tar_ne.slice(pattern + 1)))
+
+                  // set subpath if match was found
+                  if (match) subpath = pkgsubpath
+
+                  break
+              }
+
+              break
+          }
+
+          // stop searching for subpath if subpath has been found
+          if (subpath) break
+        }
+
+        break
+      default:
+        break
+    }
+
+    return subpath
+  }
+
+  return find(target, context)
+}
+
+export default findSubpath

package/src/utils/get-format.ts

@@ -0,0 +1,222 @@
+/**
+ * @file getFormat
+ * @module mlly/utils/getFormat
+ */
+
+import { Format } from '#src/enums'
+import type { GetFormatOptions, PackageScope } from '#src/interfaces'
+import type { ModuleId } from '#src/types'
+import {
+  ERR_UNKNOWN_FILE_EXTENSION,
+  type NodeError
+} from '@flex-development/errnode'
+import { isBuiltin } from '@flex-development/is-builtin'
+import pathe, { type Ext } from '@flex-development/pathe'
+import type { EmptyString, Nilable, Nullable } from '@flex-development/tutils'
+import type { URL } from 'node:url'
+import EXTENSION_FORMAT_MAP from './extension-format-map'
+import lookupPackageScope from './lookup-package-scope'
+import parseDataURL from './parse-data-url'
+import toURL from './to-url'
+
+/**
+ * Retrieves a module format for the given module `id`.
+ *
+ * @see {@linkcode Format}
+ * @see {@linkcode GetFormatOptions}
+ * @see {@linkcode ModuleId}
+ *
+ * @async
+ *
+ * @param {ModuleId} id - Module id to evaluate
+ * @param {GetFormatOptions?} [options={}] - Format retrieval options
+ * @return {Promise<Nilable<Format>>} Module format, `null`, or `undefined`
+ * @throws {NodeError<TypeError>}
+ */
+const getFormat = async (
+  id: ModuleId,
+  options: GetFormatOptions = {}
+): Promise<Nilable<Format>> => {
+  const {
+    base,
+    experimental_json_modules = true,
+    experimental_network_imports = false,
+    experimental_wasm_modules = false,
+    extension_format_map = EXTENSION_FORMAT_MAP,
+    ignore_errors = false,
+    req
+  } = options
+
+  /**
+   * Module {@linkcode id} as {@linkcode URL}.
+   *
+   * @const {URL} url
+   */
+  const url: URL = toURL(id, base)
+
+  /**
+   * Extracts a [MIME type][1] from a {@linkcode URL} href, {@linkcode URL}
+   * pathname, or [`Content-Type`][2] header and converts it to a module format.
+   *
+   * [1]: https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/MIME_types
+   * [2]: https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Type
+   *
+   * @param {Nullable<string>} value - `URL` component or `content-type` header
+   * @param {boolean} [content_type=false] - `value` is `content-type` header?
+   * @return {Nilable<Format>} Module format, `null`, or `undefined`
+   */
+  const mimeToFormat = (
+    value: Nullable<string>,
+    content_type: boolean = false
+  ): Nilable<Format> => {
+    /**
+     * Module format for {@linkcode value}.
+     *
+     * @var {Nilable<Format>} format
+     */
+    let format: Nilable<Format> = null
+
+    // do nothing if value is empty
+    /* c8 ignore next */ if (!value) return format
+
+    // sanitize content-type header
+    if (content_type) value = value.replace(/;.*/, ',')
+
+    // add data: protocol to value
+    if (!value.startsWith('data:')) value = `data:${value}`
+
+    // get format based on mime type
+    try {
+      switch (parseDataURL(value).mime) {
+        case 'application/javascript':
+        case 'application/typescript':
+        case 'text/javascript':
+          format = Format.MODULE
+          break
+        case 'application/json':
+          format = experimental_json_modules ? Format.JSON : null
+          break
+        case 'application/wasm':
+          format = experimental_wasm_modules ? Format.WASM : null
+          break
+        default:
+          break
+      }
+    } catch {
+      format = ignore_errors ? undefined : null
+    }
+
+    return format
+  }
+
+  /**
+   * Module format for {@linkcode id}.
+   *
+   * @var {Nilable<Format>} format
+   */
+  let format: Nilable<Format> = null
+
+  // get format based on url protocol
+  switch (url.protocol) {
+    case 'data:':
+      format = mimeToFormat(url.href)
+      break
+    case 'file:':
+      /**
+       * File extension of {@linkcode url.pathname}.
+       *
+       * @const {EmptyString | Ext}
+       */
+      const ext: EmptyString | Ext = pathe.extname(url.pathname)
+
+      /**
+       * Package scope result for {@linkcode url}.
+       *
+       * @const {Nullable<PackageScope>} scope
+       */
+      const scope: Nullable<PackageScope> = lookupPackageScope(url)
+
+      switch (true) {
+        // get format based on package type
+        case scope && ext === '.js':
+          format =
+            scope!.pkgjson.type === Format.MODULE
+              ? Format.MODULE
+              : Format.COMMONJS
+          break
+        // get format based on file extension
+        case extension_format_map.has(ext):
+          format = extension_format_map.get(ext)!
+
+          switch (true) {
+            case format === Format.JSON && !experimental_json_modules:
+            case format === Format.WASM && !experimental_wasm_modules:
+              format = ignore_errors ? undefined : null
+              break
+            default:
+              break
+          }
+
+          break
+        // ignore file extension errors
+        case ignore_errors:
+          format = undefined
+          break
+        default:
+          /**
+           * Recommended fix for [`ERR_UNKNOWN_FILE_EXTENSION`][1].
+           *
+           * [1]: https://nodejs.org/api/errors.html#err_unknown_file_extension
+           *
+           * @var {string?} suggestion
+           */
+          let suggestion: string | undefined
+
+          // add recommended fix for ERR_UNKNOWN_FILE_EXTENSION if package is
+          // esm-only and module id does not include file extension
+          if (scope && scope.pkgjson.type === Format.MODULE && ext === '') {
+            const { pkg } = scope
+
+            /**
+             * Basename of {@linkcode url.pathname}
+             *
+             * @const {string} basename
+             */
+            const basename: string = pathe.basename(url.pathname)
+
+            /**
+             * Relative path from {@linkcode pkg} to {@linkcode url.pathname}.
+             *
+             * @const {string} relative
+             */
+            const relative: string = pathe.relative(pkg, url.pathname).slice(1)
+
+            suggestion = `Loading extensionless files is not supported inside of "type":"module" package.json contexts. The package.json file ${pkg} caused this "type":"module" context. Try changing ${url.pathname} to have a file extension. Note the "bin" field of package.json can point to a file with an extension, for example {"type":"module","bin":{"${basename}":"${relative}.js"}}`
+          }
+
+          throw new ERR_UNKNOWN_FILE_EXTENSION(ext, url.pathname, suggestion)
+      }
+
+      break
+    case 'http:':
+    case 'https:':
+      if (experimental_network_imports) {
+        const { default: fetch } = await import('node-fetch')
+        const { headers } = await fetch(url.href, req)
+        format = mimeToFormat(headers.get('content-type'), true)
+      } else {
+        format = ignore_errors ? undefined : null
+      }
+
+      break
+    case 'node:':
+      if (isBuiltin(url)) format = Format.BUILTIN
+      break
+    default:
+      break
+  }
+
+  return format
+}
+
+export default getFormat

package/src/utils/get-source.ts

@@ -0,0 +1,129 @@
+/**
+ * @file getSource
+ * @module mlly/utils/getSource
+ */
+
+import { Format } from '#src/enums'
+import type { GetSourceOptions } from '#src/interfaces'
+import type { ModuleId } from '#src/types'
+import {
+  ERR_UNSUPPORTED_ESM_URL_SCHEME,
+  type NodeError
+} from '@flex-development/errnode'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import type { URL } from 'node:url'
+import util from 'node:util'
+import parseDataURL from './parse-data-url'
+import toURL from './to-url'
+
+/**
+ * Retrieves source code for the given module `id`.
+ *
+ * @see {@linkcode GetSourceOptions}
+ * @see {@linkcode ModuleId}
+ * @see https://nodejs.org/docs/latest-v19.x/api/esm.html#loadurl-context-nextload
+ *
+ * @async
+ *
+ * @param {ModuleId} id - Module id to evaluate
+ * @param {GetSourceOptions?} [options={}] - Source code retrieval options
+ * @return {Promise<Uint8Array | string | undefined>} Source code for `id`
+ * @throws {NodeError} If unsupported URL scheme is encountered
+ */
+const getSource = async (
+  id: ModuleId,
+  options: GetSourceOptions = {}
+): Promise<Uint8Array | string | undefined> => {
+  const {
+    base,
+    experimental_network_imports = false,
+    format,
+    ignore_errors = false,
+    req
+  } = options
+
+  // exit early if format is Format.BUILTIN
+  if (format === Format.BUILTIN) return undefined
+
+  /**
+   * Module {@linkcode id} as {@linkcode URL}.
+   *
+   * @const {URL} url
+   */
+  const url: URL = toURL(id, base)
+
+  /**
+   * [`ERR_UNSUPPORTED_ESM_URL_SCHEME`][1] check.
+   *
+   * [1]: https://nodejs.org/api/errors.html#err_unsupported_esm_url_scheme
+   *
+   * @var {boolean} err
+   */
+  let err: boolean = false
+
+  /**
+   * Source code for {@linkcode id}.
+   *
+   * @var {Uint8Array | string | undefined} source
+   */
+  let source: Uint8Array | string | undefined = ''
+
+  // get source code based on url protocol
+  switch (url.protocol) {
+    case 'data:':
+      const { base64, data } = parseDataURL(url)
+
+      /**
+       * Buffer encoding used to create a {@linkcode Buffer} instance from
+       * {@linkcode data}.
+       *
+       * @const {BufferEncoding} encoding
+       */
+      const encoding: BufferEncoding = base64 ? 'base64' : 'utf8'
+
+      source = Buffer.from(decodeURIComponent(data), encoding).toString()
+      break
+    case 'file:':
+      source = await fs.readFile(url, 'utf8')
+      break
+    case 'http:':
+    case 'https:':
+      if (experimental_network_imports) {
+        const { default: fetch } = await import('node-fetch')
+        source = await (await fetch(url.href, req)).text()
+      } else {
+        err = true
+      }
+
+      break
+    case 'node:':
+      source = undefined
+      break
+    default:
+      err = true
+  }
+
+  // throw if unsupported url scheme was encountered
+  if (!ignore_errors && err) {
+    /**
+     * Supported URL schemes.
+     *
+     * @const {string[]} schemes
+     */
+    const schemes: string[] = ['data', 'file']
+
+    // update supported schemes if support for network based modules is enabled
+    if (experimental_network_imports) schemes.push('http', 'https')
+
+    throw new ERR_UNSUPPORTED_ESM_URL_SCHEME(
+      url,
+      schemes,
+      os.platform() === 'win32'
+    )
+  }
+
+  return format === Format.WASM ? new util.TextEncoder().encode(source) : source
+}
+
+export default getSource

package/src/utils/has-cjs-syntax.ts

@@ -0,0 +1,44 @@
+/**
+ * @file hasCJSSyntax
+ * @module mlly/utils/hasCJSSyntax
+ */
+
+import validateString from '#src/internal/validate-string'
+import type { NodeError } from '@flex-development/errnode'
+
+/**
+ * Detects if `code` contains CommonJS syntax. Ignores matches in comments.
+ *
+ * Syntax patterns:
+ *
+ * - `__dirname`
+ * - `__filename`
+ * - `await import`
+ * - `exports`
+ * - `module.exports`
+ * - `require`
+ * - `require.*`
+ *
+ * @see https://regex101.com/r/Co77SJ
+ *
+ * @param {string} code - Code to evaluate
+ * @return {boolean} `true` if `code` contains cjs syntax, `false` otherwise
+ * @throws {NodeError<TypeError>} If `code` is not a string
+ */
+const hasCJSSyntax = (code: string): boolean => {
+  validateString(code, 'code')
+
+  /**
+   * CommonJS syntax regex.
+   *
+   * @see https://regex101.com/r/Co77SJ
+   *
+   * @const {RegExp} CJS_SYNTAX_REGEX
+   */
+  const CJS_SYNTAX_REGEX: RegExp =
+    /(?<!(?:\/\/|\*).*)((?:module\.)?exports(?:\.\w+|(?<!\s+=))|require(?=\(.)|require\.\w+|__dirname|__filename|await import)/gm
+
+  return !!code.match(CJS_SYNTAX_REGEX)
+}
+
+export default hasCJSSyntax

package/src/utils/has-esm-syntax.ts

@@ -0,0 +1,40 @@
+/**
+ * @file hasESMSyntax
+ * @module mlly/utils/hasESMSyntax
+ */
+
+import validateString from '#src/internal/validate-string'
+import type { NodeError } from '@flex-development/errnode'
+
+/**
+ * Detects if `code` contains ESM syntax. Ignores matches in comments.
+ *
+ * Syntax patterns:
+ *
+ * - `export` (declaration, default, named, star)
+ * - `import` (default, dynamic, named, star)
+ * - `import.meta.(env|resolve|url)`
+ *
+ * @see https://regex101.com/r/xfreyy
+ *
+ * @param {string} code - Code to evaluate
+ * @return {boolean} `true` if `code` contains esm syntax, `false` otherwise
+ * @throws {NodeError<TypeError>} If `code` is not a string
+ */
+const hasESMSyntax = (code: string): boolean => {
+  validateString(code, 'code')
+
+  /**
+   * ESM syntax regex.
+   *
+   * @see https://regex101.com/r/xfreyy
+   *
+   * @const {RegExp} ESM_SYNTAX_REGEX
+   */
+  const ESM_SYNTAX_REGEX: RegExp =
+    /(?<!(?:\/\/|\*).*)((?:export|import)[\s\w*,{}]*(?=\sfrom)|export\b\s*(?:[*{]|async function|(?:abstract\s)?class|const|default|enum|function|interface|let|type|var)|await import|import\.meta\.(?:env(?:\.\w+)?|resolve|url))/gm
+
+  return !!code.match(ESM_SYNTAX_REGEX)
+}
+
+export default hasESMSyntax