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

package/src/utils/parse-module-id.ts

@@ -1,197 +0,0 @@
-/**
- * @file parseModuleId
- * @module mlly/lib/parseModuleId
- */
-
-import type { ParseModuleIdOptions, ParsedModuleId } from '#src/interfaces'
-import ENCODED_SEP_REGEX from '#src/internal/regex-encoded-sep'
-import INTERNAL_SPECIFIER_REGEX from '#src/internal/regex-internal-specifier'
-import PACKAGE_PATH_REGEX from '#src/internal/regex-package-path'
-import validateBoolean from '#src/internal/validate-boolean'
-import validateURLString from '#src/internal/validate-url-string'
-import type { ModuleId } from '#src/types'
-import {
-  ERR_INVALID_MODULE_SPECIFIER,
-  type NodeError
-} from '@flex-development/errnode'
-import { isBuiltin } from '@flex-development/is-builtin'
-import pathe from '@flex-development/pathe'
-import {
-  DOT,
-  cast,
-  isString,
-  isUndefined,
-  trim,
-  type Optional
-} from '@flex-development/tutils'
-import { URL, fileURLToPath } from 'node:url'
-import isBareSpecifier from './is-bare-specifier'
-import isRelativeSpecifier from './is-relative-specifier'
-import toNodeURL from './to-node-url'
-
-/**
- * Creates an object representation the given module `id`.
- *
- * @see {@linkcode ModuleId}
- * @see {@linkcode ParseModuleIdOptions}
- * @see {@linkcode ParsedModuleId}
- *
- * @param {ModuleId} id - Module id to parse
- * @param {ParseModuleIdOptions?} [options={}] - Parsing options
- * @return {ParsedModuleId} Object representing `id`
- * @throws {NodeError<TypeError>}
- */
-const parseModuleId = (
-  id: ModuleId,
-  options: ParseModuleIdOptions = {}
-): ParsedModuleId => {
-  const {
-    internal = id instanceof URL ? false : id.startsWith('#'),
-    pkgname = false
-  } = options
-
-  // ensure id is an instance of URL or a string
-  validateURLString(id, 'id')
-
-  // ensure option schemas
-  validateBoolean(internal, 'options.internal')
-  validateBoolean(pkgname, 'options.pkgname')
-
-  // ensure id a string without leading and trailing spaces
-  id = id instanceof URL ? id.href : trim(id)
-
-  /**
-   * Reason for [`ERR_INVALID_MODULE_SPECIFIER`][1], if any.
-   *
-   * [1]: https://nodejs.org/api/errors.html#err_invalid_module_specifier
-   *
-   * @const {Optional<string>} error
-   */
-  let error: Optional<string>
-
-  /**
-   * Object representing `id`.
-   *
-   * @var {ParsedModuleId} parsed
-   */
-  let parsed: ParsedModuleId = {
-    internal: false,
-    path: id,
-    pkg: '',
-    protocol: '',
-    raw: id,
-    scope: '',
-    version: '',
-    version_prefix: ''
-  }
-
-  // try parsing module id
-  switch (true) {
-    case ENCODED_SEP_REGEX.test(id):
-      error = `must not include encoded '${pathe.sep}' or '\\' characters`
-      break
-    case isBuiltin(id):
-      const { href, protocol, pathname } = new URL(toNodeURL(id))
-
-      parsed = {
-        internal: false,
-        path: pathname.replace(/^\S+?(?=\/|$)/, ''),
-        pkg: href.replace(/\/.*$/, ''),
-        protocol: id.startsWith('node:') ? protocol : '',
-        raw: id,
-        scope: '',
-        version: '',
-        version_prefix: ''
-      }
-
-      break
-    case INTERNAL_SPECIFIER_REGEX.test(id):
-      const [, root = ''] = INTERNAL_SPECIFIER_REGEX.exec(id)!
-
-      parsed = {
-        internal: true,
-        path: id,
-        pkg: root,
-        protocol: '',
-        raw: id,
-        scope: '',
-        version: '',
-        version_prefix: ''
-      }
-
-      break
-    case PACKAGE_PATH_REGEX.test(id):
-      const [
-        ,
-        pkg = '',
-        scope = '',
-        version_prefix = '',
-        version = '',
-        subpath = ''
-      ] = PACKAGE_PATH_REGEX.exec(id)!
-
-      parsed = {
-        internal: false,
-        path: DOT + subpath,
-        pkg,
-        protocol: '',
-        raw: id,
-        scope,
-        version,
-        version_prefix
-      }
-
-      break
-    case /^[\w-]{2,}:/.test(id):
-      try {
-        const { host, protocol, pathname } = new URL(id)
-
-        parsed = {
-          internal: false,
-          path: host + pathname,
-          pkg: '',
-          protocol,
-          raw: id,
-          scope: '',
-          version: '',
-          version_prefix: ''
-        }
-      } catch {
-        error = 'is not a valid URL'
-      }
-
-      break
-    case isBareSpecifier(cast(id)):
-    case isRelativeSpecifier(cast(id)):
-    case pathe.isAbsolute(id):
-      break
-    default:
-      error = ''
-      break
-  }
-
-  // reset error reason
-  error = ENCODED_SEP_REGEX.test(id)
-    ? error
-    : internal && !INTERNAL_SPECIFIER_REGEX.test(id)
-    ? 'is not a valid internal imports specifier name'
-    : pkgname && !PACKAGE_PATH_REGEX.test(id)
-    ? 'does not start with a valid package name'
-    : error
-
-  // throw if module specifier is invalid
-  if (isString(error)) {
-    let { parent } = options
-
-    if (!isUndefined(parent)) {
-      validateURLString(parent, 'options.parent')
-      parent = fileURLToPath(parent)
-    }
-
-    throw new ERR_INVALID_MODULE_SPECIFIER(id, error, parent)
-  }
-
-  return parsed
-}
-
-export default parseModuleId

package/src/utils/parse-subpath.ts

@@ -1,331 +0,0 @@
-/**
- * @file parseSubpath
- * @module mlly/utils/parseSubpath
- */
-
-import type {
-  ParseSubpathOptions,
-  ParsedModuleId,
-  ParsedSubpath
-} from '#src/interfaces'
-import getSubpaths from '#src/internal/get-subpaths'
-import invalidSegmentRegex from '#src/internal/regex-invalid-segment'
-import PACKAGE_NAME_REGEX from '#src/internal/regex-package-name'
-import validateArraySet from '#src/internal/validate-array-set'
-import validateBoolean from '#src/internal/validate-boolean'
-import validateString from '#src/internal/validate-string'
-import validateURLString from '#src/internal/validate-url-string'
-import {
-  ERR_INVALID_PACKAGE_CONFIG,
-  ERR_INVALID_PACKAGE_TARGET,
-  ERR_PACKAGE_IMPORT_NOT_DEFINED,
-  ERR_PACKAGE_PATH_NOT_EXPORTED,
-  ErrorCode,
-  type NodeError
-} from '@flex-development/errnode'
-import pathe from '@flex-development/pathe'
-import type { Exports, Imports } from '@flex-development/pkg-types'
-import {
-  CompareResult,
-  DOT,
-  cast,
-  get,
-  isArray,
-  isArrayIndex,
-  isNIL,
-  isNull,
-  isObjectCurly,
-  isString,
-  type Dot,
-  type Nullable,
-  type Optional
-} from '@flex-development/tutils'
-import { URL, fileURLToPath, pathToFileURL } from 'node:url'
-import compareSubpaths from './compare-subpaths'
-import CONDITIONS from './conditions'
-import isExportsSugar from './is-exports-sugar'
-import parseModuleId from './parse-module-id'
-import PATTERN_CHARACTER from './pattern-character'
-
-/**
- * Creates an object representation of a subpath export or import from the given
- * module `specifier` after ensuring the subpath defined in `specifier` is also
- * defined in the given package `context`, a `package.json` [`exports`][1] or
- * [`imports`][2] field.
- *
- * ::: warning
- * Does **not** guarantee `specifier` resolves to an existing module.
- * :::
- *
- * [1]: https://nodejs.org/api/packages.html#exports
- * [2]: https://nodejs.org/api/packages.html#imports
- *
- * @see {@linkcode Exports}
- * @see {@linkcode Imports}
- * @see {@linkcode ParseSubpathOptions}
- * @see {@linkcode ParsedSubpath}
- * @see https://nodejs.org/api/packages.html#subpath-exports
- * @see https://nodejs.org/api/packages.html#subpath-imports
- *
- * @param {string} specifier - Module specifier to evaluate
- * @param {Optional<Exports | Imports>} context - Package context
- * @param {ParseSubpathOptions} options - Parsing options
- * @return {ParsedSubpath} Object representing package subpath
- * @throws {NodeError<Error | TypeError>}
- */
-const parseSubpath = (
-  specifier: string,
-  context: Optional<Exports | Imports>,
-  options: ParseSubpathOptions
-): ParsedSubpath => {
-  const {
-    condition = 'default',
-    conditions = CONDITIONS,
-    dir,
-    internal = specifier.startsWith('#'),
-    parent
-  } = options
-
-  // ensure specifier is a string
-  validateString(specifier, 'specifier')
-
-  // ensure option schemas
-  validateString(condition, 'options.condition')
-  validateArraySet(conditions, 'options.conditions')
-  validateURLString(dir, 'options.dir')
-  validateBoolean(internal, 'options.internal')
-  validateURLString(parent, 'options.parent')
-
-  /**
-   * Parsed module id.
-   *
-   * **Note**: Ensures {@linkcode specifier} begins with a valid package name or
-   * is a valid [subpath import][1].
-   *
-   * [1]: https://nodejs.org/api/packages.html#subpath-imports
-   *
-   * @const {ParsedModuleId} id
-   */
-  const id: ParsedModuleId = parseModuleId(specifier, {
-    internal,
-    parent,
-    pkgname: !internal
-  })
-
-  /**
-   * Absolute path to directory containing relevant `package.json` file.
-   *
-   * @const {string} pkgdir
-   */
-  const pkgdir: string = fileURLToPath(dir).replace(/\/$/, '') + pathe.sep
-
-  /**
-   * URL of relevant `package.json` file.
-   *
-   * @const {URL} pkg
-   */
-  const pkg: URL = new URL('package.json', pathToFileURL(pkgdir))
-
-  /**
-   * Subpaths defined in {@linkcode context}.
-   *
-   * @const {string[]} keys
-   */
-  const keys: string[] = getSubpaths(context, id.internal, pkg, parent)
-
-  /**
-   * Subpath defined in {@linkcode context} that maps to {@linkcode specifier}.
-   *
-   * @var {Nullable<string>} key
-   */
-  let key: Nullable<string> = null
-
-  /**
-   * Subpath without entry prefix ({@linkcode key}).
-   *
-   * @var {string} base
-   */
-  let base: string = ''
-
-  // match specifier to subpath defined in context
-  for (const pkgsubpath of keys) {
-    /**
-     * Index of {@linkcode PATTERN_CHARACTER} in {@linkcode pkgsubpath}.
-     *
-     * @const {number} pattern
-     */
-    const pattern: number = pkgsubpath.indexOf(PATTERN_CHARACTER)
-
-    // no pattern character => subpath must be exact match
-    if (pattern === -1 && pkgsubpath === id.path) {
-      key = pkgsubpath
-      break
-    }
-
-    // pattern character => try finding best match for subpath
-    if (pattern !== -1 && id.path.startsWith(pkgsubpath.slice(0, pattern))) {
-      /**
-       * Everything after pattern character (`*`) in {@linkcode pkgsubpath}.
-       *
-       * @const {string} trailer
-       */
-      const trailer: string = pkgsubpath.slice(pattern + 1)
-
-      // best match found => reset key and base of subpath
-      if (
-        id.path.length >= pkgsubpath.length &&
-        id.path.endsWith(trailer) &&
-        compareSubpaths(key ?? '', pkgsubpath) === CompareResult.GREATER_THAN &&
-        pkgsubpath.lastIndexOf(PATTERN_CHARACTER) === pattern
-      ) {
-        key = pkgsubpath
-        base = id.path.slice(pattern, id.path.length - trailer.length)
-      }
-    }
-  }
-
-  // throw if defined subpath was not found
-  if (isNull(key)) {
-    let { parent } = options
-
-    // ensure parent is a path
-    parent = fileURLToPath(parent)
-
-    throw internal
-      ? new ERR_PACKAGE_IMPORT_NOT_DEFINED(id.path, parent, pkgdir)
-      : new ERR_PACKAGE_PATH_NOT_EXPORTED(pkgdir, id.path, parent)
-  }
-
-  /**
-   * Finds the package target string specified by {@linkcode key}.
-   *
-   * @param {Optional<Exports>} data - Initial package target
-   * @return {Nullable<string>} Package target string or `null`
-   * @throws {NodeError<Error | TypeError>}
-   */
-  const findPackageTarget = (data: Optional<Exports>): Nullable<string> => {
-    /**
-     * Package target.
-     *
-     * @var {Nullable<string>} target
-     */
-    let target: Nullable<string> = null
-
-    switch (true) {
-      case isNIL(data):
-        target = null
-        break
-      case isArray(data):
-        /**
-         * Possible package target search error.
-         *
-         * @var {Optional<NodeError>} error
-         */
-        let error: Optional<NodeError>
-
-        // try finding package target based on first match in search context
-        for (const item of cast<string[]>(data)) {
-          try {
-            target = findPackageTarget(item)
-          } catch (e: unknown) {
-            error = cast<NodeError>(e)
-
-            /* c8 ignore next */
-            if (error.code !== ErrorCode.ERR_INVALID_PACKAGE_TARGET) throw error
-
-            continue
-          }
-
-          // stop search attempts if target was found
-          if (target) {
-            error = undefined
-            break
-          }
-        }
-
-        // throw if error was encountered
-        if (error) throw error
-
-        break
-      case isObjectCurly(data):
-        data = cast<Record<string, Exports>>(data)
-
-        // try finding package target based on condition
-        for (const property of Object.getOwnPropertyNames(data)) {
-          if (isArrayIndex(property)) {
-            throw new ERR_INVALID_PACKAGE_CONFIG(
-              fileURLToPath(pkg),
-              fileURLToPath(parent),
-              '"exports" cannot contain numeric property keys'
-            )
-          }
-
-          // check conditions
-          if (property === condition || new Set(conditions).has(property)) {
-            target = findPackageTarget(data[property])
-            if (target) break
-          }
-        }
-
-        break
-      case isString(data):
-        target = cast<string>(data)
-
-        switch (true) {
-          case internal && PACKAGE_NAME_REGEX.test(target):
-            break
-          case target.startsWith(DOT + pathe.sep):
-            // check target for invalid segments
-            if (invalidSegmentRegex().test(target.slice(2))) {
-              if (invalidSegmentRegex('deprecated').test(target.slice(2))) {
-                throw new ERR_INVALID_PACKAGE_TARGET(
-                  fileURLToPath(dir),
-                  key!,
-                  target,
-                  internal,
-                  fileURLToPath(parent)
-                )
-              }
-            }
-
-            break
-          default:
-            throw new ERR_INVALID_PACKAGE_TARGET(
-              fileURLToPath(dir),
-              key!,
-              target,
-              internal,
-              fileURLToPath(parent)
-            )
-        }
-
-        break
-      default:
-        throw new ERR_INVALID_PACKAGE_TARGET(
-          fileURLToPath(dir),
-          key!,
-          data,
-          internal,
-          fileURLToPath(parent)
-        )
-    }
-
-    return target
-  }
-
-  // convert exports to object if using exports main sugar
-  if (!internal && isExportsSugar(context, pkg, parent)) {
-    context = cast<Record<Dot, Exports>>({ [DOT]: context })
-  }
-
-  return {
-    base,
-    internal,
-    key,
-    raw: id.path,
-    specifier: id.raw,
-    target: findPackageTarget(get(context, key))
-  }
-}
-
-export default parseSubpath

package/src/utils/pattern-character.ts

@@ -1,13 +0,0 @@
-/**
- * @file PATTERN_CHARACTER
- * @module mlly/utils/PATTERN_CHARACTER
- */
-
-/**
- * Character representing a subpath pattern.
- *
- * @const {string} PATTERN_CHARACTER
- */
-const PATTERN_CHARACTER: string = '*'
-
-export default PATTERN_CHARACTER

package/src/utils/read-package-json.ts

@@ -1,113 +0,0 @@
-/**
- * @file readPackageJson
- * @module mlly/utils/readPackageJson
- */
-
-import validateString from '#src/internal/validate-string'
-import validateURLString from '#src/internal/validate-url-string'
-import type { ModuleId } from '#src/types'
-import {
-  ERR_INVALID_PACKAGE_CONFIG,
-  type NodeError
-} from '@flex-development/errnode'
-import pathe from '@flex-development/pathe'
-import type { PackageJson } from '@flex-development/pkg-types'
-import {
-  DOT,
-  cast,
-  isEmptyString,
-  isNIL,
-  isUndefined,
-  type Nullable,
-  type Optional
-} from '@flex-development/tutils'
-import fs from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import isFile from './is-file'
-import toURL from './to-url'
-
-/**
- * Reads a `package.json` file from the given directory.
- *
- * Returns `null` if a file is not found.
- *
- * @see {@linkcode ModuleId}
- * @see {@linkcode PackageJson}
- *
- * @param {ModuleId} [dir='.'] - Id of directory containing `package.json` file
- * @param {string?} [specifier] - Module specifier passed by user to initiate
- * reading of `package.json` file
- * @param {ModuleId?} [parent] - Id of module to resolve from
- * @return {?PackageJson} `package.json` object or `null` if file is not found
- * @throws {NodeError<Error | TypeError>} If `dir` is not a string or instance
- * of {@linkcode URL}, if `specifier` is not a string, if `parent` is not a
- * string, or if a `package.json` is file found and does not contain valid JSON
- */
-const readPackageJson = (
-  dir: ModuleId = DOT,
-  specifier?: string,
-  parent?: ModuleId
-): Nullable<PackageJson> => {
-  // ensure dir is an instance of URL or a string
-  validateURLString(dir, 'dir')
-
-  // ensure specifier is a string
-  !isUndefined(specifier) && validateString(specifier, 'specifier')
-
-  // ensure parent is an instance of URL or a string
-  !isUndefined(parent) && validateURLString(parent, 'parent')
-
-  // ensure dir is a path
-  dir = fileURLToPath(toURL(dir))
-
-  /**
-   * Absolute path to `package.json` file.
-   *
-   * @const {string} path
-   */
-  const path: string = pathe.toNamespacedPath(pathe.join(dir, 'package.json'))
-
-  // return null if package.json file does not exist
-  if (!isFile(path)) return null
-
-  /**
-   * Possible `package.json` object.
-   *
-   * @var {PackageJson} pkg
-   */
-  let pkg: PackageJson
-
-  // try parsing package.json file
-  try {
-    pkg = JSON.parse(fs.readFileSync(path, 'utf8'))
-  } catch (e: unknown) {
-    /**
-     * String containing module specifier passed by user to initiate reading of
-     * `package.json` file and the location the module specifier was imported
-     * from.
-     *
-     * @var {Optional<string>} base
-     */
-    let base: Optional<string>
-
-    // get base
-    switch (true) {
-      case specifier && !isNIL(parent) && !isEmptyString(parent):
-        base = `'${specifier}' from ${fileURLToPath(toURL(parent!))}`
-        break
-      case specifier?.startsWith('file:'):
-        base = fileURLToPath(specifier!)
-        break
-    }
-
-    throw new ERR_INVALID_PACKAGE_CONFIG(
-      path,
-      base,
-      cast<SyntaxError>(e).message
-    )
-  }
-
-  return pkg
-}
-
-export default readPackageJson