@flex-development/mlly 1.0.0-alpha.16 → 1.0.0-alpha.17

package/src/utils/find-subpath.ts

@@ -1,251 +0,0 @@
-/**
- * @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 {
-  DOT,
-  cast,
-  isArray,
-  isNIL,
-  isObjectCurly,
-  isString,
-  sort,
-  type Nilable,
-  type Nullable,
-  type Optional
-} 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 and targets without explicit `'/index'` usage.
- * 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 {Nilable<Exports | Imports>} 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: Nilable<Exports | Imports>,
-  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 (isString(context)) {
-    if (target === context || target === pathe.changeExt(context, '')) {
-      return DOT
-    }
-  }
-
-  // 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 {Nilable<Exports | Imports>} context - Package context
-   * @param {string} [key=DOT] - Subpath in `context` being checked
-   * @return {Nullable<string>} Subpath defined in `context` or `null`
-   */
-  const find = (
-    target: string,
-    context: Nilable<Exports | Imports>,
-    key: string = DOT
-  ): 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
-    if (isArray(context) || isObjectCurly(context) || isString(context)) {
-      /**
-       * 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 = cast<Record<string, Exports>>({ [key]: context })
-      }
-
-      // context is now an object
-      context = cast<Record<string, Exports>>(context)
-
-      /**
-       * Subpaths defined in {@linkcode context}.
-       *
-       * **Note**: Sorted from least to greatest.
-       *
-       * @see {@linkcode compareSubpaths}
-       *
-       * @const {string[]} keys
-       */
-      const subpaths: string[] = sort(
-        getSubpaths(context, internal, pkg, parent),
-        (s1, s2) => compareSubpaths(s1, s2) * -1
-      )
-
-      // match target to subpath defined in context
-      for (const pkgsubpath of subpaths) {
-        /**
-         * Current package target being checked.
-         *
-         * @var {Optional<Exports>} tar
-         */
-        let tar: Optional<Exports> = context[pkgsubpath]
-
-        // find subpath
-        switch (true) {
-          case isArray(tar):
-            // try matching target based first match in target array
-            for (const item of cast<string[]>(tar)) {
-              subpath = find(target, item, pkgsubpath)
-              if (subpath) break
-            }
-
-            break
-          case isObjectCurly(tar):
-            tar = cast<Record<string, Exports>>(tar)
-
-            // try matching target based on export conditions
-            for (const property of Object.getOwnPropertyNames(tar)) {
-              if (property === condition || conditions.has(property)) {
-                subpath = find(target, tar[property], pkgsubpath)
-                if (subpath) break
-              }
-            }
-
-            break
-          case isString(tar):
-            tar = cast<string>(tar)
-
-            /**
-             * {@linkcode tar} without file extension.
-             *
-             * @const {string} tar_ne
-             */
-            const tar_ne: string = pathe.changeExt(tar, '')
-
-            /**
-             * {@linkcode tar_ne} without `'/index'`.
-             *
-             * @const {string} tar_ni
-             */
-            const tar_ni: string = tar_ne.replace(/\/index$/, '')
-
-            /**
-             * 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 target === tar_ni && tar_ne.endsWith('/index'):
-              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
-      }
-    }
-
-    return subpath
-  }
-
-  return find(target, context)
-}
-
-export default findSubpath

package/src/utils/get-format.ts

@@ -1,249 +0,0 @@
-/**
- * @file getFormat
- * @module mlly/utils/getFormat
- */
-
-import { Format } from '#src/enums'
-import type { GetFormatOptions, PackageScope } from '#src/interfaces'
-import validateBoolean from '#src/internal/validate-boolean'
-import validateMap from '#src/internal/validate-map'
-import validateObject from '#src/internal/validate-object'
-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 {
-  isEmptyString,
-  isUndefined,
-  type EmptyString,
-  type Nilable,
-  type Nullable,
-  type Optional
-} 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`.
- *
- * ::: tip
- * The given module `id` should be absolute (i.e. a [`file:` URL][1] or absolute
- * specifier).
- * :::
- *
- * [1]: https://nodejs.org/api/esm.html#file-urls
- *
- * @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 {
-    experimental_json_modules: json_modules = true,
-    experimental_network_imports: network_imports = false,
-    experimental_wasm_modules: wasm_modules = false,
-    extension_format_map = EXTENSION_FORMAT_MAP,
-    ignore_errors = false,
-    req = {}
-  } = options
-
-  validateBoolean(json_modules, 'options.experimental_json_modules')
-  validateBoolean(network_imports, 'options.experimental_network_imports')
-  validateBoolean(wasm_modules, 'options.experimental_wasm_modules')
-  validateBoolean(ignore_errors, 'options.ignore_errors')
-  validateMap(extension_format_map, 'options.extension_format_map')
-  !isUndefined(req) && validateObject(req, 'options.req')
-
-  /**
-   * Module {@linkcode id} as {@linkcode URL}.
-   *
-   * @const {URL} url
-   */
-  const url: URL = toURL(id)
-
-  /**
-   * 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 = json_modules ? Format.JSON : null
-          break
-        case 'application/wasm':
-          format = 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 && !json_modules:
-            case format === Format.WASM && !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 {Optional<string>} suggestion
-           */
-          let suggestion: Optional<string>
-
-          // 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) {
-            if (isEmptyString(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 (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

@@ -1,144 +0,0 @@
-/**
- * @file getSource
- * @module mlly/utils/getSource
- */
-
-import { Format } from '#src/enums'
-import type { GetSourceOptions } from '#src/interfaces'
-import validateBoolean from '#src/internal/validate-boolean'
-import validateObject from '#src/internal/validate-object'
-import validateString from '#src/internal/validate-string'
-import type { ModuleId } from '#src/types'
-import {
-  ERR_UNSUPPORTED_ESM_URL_SCHEME,
-  type NodeError
-} from '@flex-development/errnode'
-import { isUndefined, type Optional } from '@flex-development/tutils'
-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`.
- *
- * ::: tip
- * The given module `id` should be absolute (i.e. a [`file:` URL][1] or absolute
- * specifier).
- * :::
- *
- * [1]: https://nodejs.org/api/esm.html#file-urls
- *
- * @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<Optional<Uint8Array | string>>} Source code for `id`
- * @throws {NodeError} If unsupported URL scheme is encountered
- */
-const getSource = async (
-  id: ModuleId,
-  options: GetSourceOptions = {}
-): Promise<Optional<Uint8Array | string>> => {
-  const {
-    experimental_network_imports: network_imports = false,
-    format,
-    ignore_errors = false,
-    req = {}
-  } = options
-
-  validateBoolean(network_imports, 'options.experimental_network_imports')
-  !isUndefined(format) && validateString(format, 'options.format')
-  validateBoolean(ignore_errors, 'options.ignore_errors')
-  !isUndefined(req) && validateObject(req, 'options.req')
-
-  // 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)
-
-  /**
-   * [`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 {Optional<Uint8Array | string>} source
-   */
-  let source: Optional<Uint8Array | string> = ''
-
-  // 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 (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 (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

@@ -1,44 +0,0 @@
-/**
- * @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