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

package/src/utils/parse-subpath.ts

@@ -0,0 +1,173 @@
+/**
+ * @file parseSubpath
+ * @module mlly/utils/parseSubpath
+ */
+
+import type {
+  ParseSubpathOptions,
+  ParsedModuleId,
+  ParsedSubpath
+} from '#src/interfaces'
+import getSubpaths from '#src/internal/get-subpaths'
+import validateString from '#src/internal/validate-string'
+import validateURLString from '#src/internal/validate-url-string'
+import {
+  ERR_PACKAGE_IMPORT_NOT_DEFINED,
+  ERR_PACKAGE_PATH_NOT_EXPORTED,
+  type NodeError
+} from '@flex-development/errnode'
+import pathe from '@flex-development/pathe'
+import type { Exports, Imports } from '@flex-development/pkg-types'
+import { CompareResult, type Nullable } from '@flex-development/tutils'
+import { URL, fileURLToPath, pathToFileURL } from 'node:url'
+import compareSubpaths from './compare-subpaths'
+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 {Exports | Imports | undefined} context - Package context
+ * @param {ParseSubpathOptions} options - Parsing options
+ * @return {ParsedSubpath} Object representing package subpath
+ * @throws {NodeError<Error | TypeError>} If `specifier` is not a string or the
+ * subpath defined in `specifier` is not defined in `context`
+ */
+const parseSubpath = (
+  specifier: string,
+  context: Exports | Imports | undefined,
+  options: ParseSubpathOptions
+): ParsedSubpath => {
+  const { dir, internal = specifier.startsWith('#'), parent } = options
+
+  // ensure specifier is a string
+  validateString(specifier, 'specifier')
+
+  // ensure dir is an instance of URL or a string
+  validateURLString(dir, 'options.dir')
+
+  /**
+   * 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 (key === null) {
+    let { parent } = options
+
+    // ensure parent is an instance of URL or a string
+    validateURLString(parent, 'options.parent')
+
+    // 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)
+  }
+
+  return { base, internal, key, raw: id.path, specifier: id.raw }
+}
+
+export default parseSubpath

package/src/utils/pattern-character.ts

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

@@ -0,0 +1,101 @@
+/**
+ * @file readPackageJson
+ * @module mlly/utils/readPackageJson
+ */
+
+import isFile from '#src/internal/is-file'
+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 { isEmptyString, isNIL, type Nullable } from '@flex-development/tutils'
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+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 = '.',
+  specifier?: string,
+  parent?: ModuleId
+): Nullable<PackageJson> => {
+  // ensure dir is an instance of URL or a string
+  validateURLString(dir, 'dir')
+
+  // ensure specifier is a string
+  if (specifier !== undefined) validateString(specifier, 'specifier')
+
+  // ensure parent is an instance of URL or a string
+  if (parent !== undefined) 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 {string | undefined} base
+     */
+    let base: string | undefined
+
+    // 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, (e as SyntaxError).message)
+  }
+
+  return pkg
+}
+
+export default readPackageJson

package/src/utils/resolve-alias.ts

@@ -0,0 +1,219 @@
+/**
+ * @file resolveAlias
+ * @module mlly/utils/resolveAlias
+ */
+
+import type { ParsedModuleId, ResolveAliasOptions } from '#src/interfaces'
+import regexp from '#src/internal/escape-reg-exp'
+import validateBoolean from '#src/internal/validate-boolean'
+import validateObject from '#src/internal/validate-object'
+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 { CompareResult, isNIL, type Nullable } from '@flex-development/tutils'
+import { URL, pathToFileURL } from 'node:url'
+import compareSubpaths from './compare-subpaths'
+import CONDITIONS from './conditions'
+import parseModuleId from './parse-module-id'
+import PATTERN_CHARACTER from './pattern-character'
+import RESOLVE_EXTENSIONS from './resolve-extensions'
+import resolveModule from './resolve-module'
+import toBareSpecifier from './to-bare-specifier'
+import toRelativeSpecifier from './to-relative-specifier'
+import toURL from './to-url'
+
+/**
+ * Resolves a path alias in the given module `specifier`; does nothing if a path
+ * match isn't found.
+ *
+ * @see {@linkcode ResolveAliasOptions}
+ *
+ * @async
+ *
+ * @param {string} specifier - Module specifier to evaluate
+ * @param {ResolveAliasOptions} [options={}] - Resolution options
+ * @return {Promise<string>} Resolved specifier or original module specifier
+ * @throws {NodeError}
+ */
+const resolveAlias = async (
+  specifier: string,
+  options: ResolveAliasOptions = {}
+): Promise<string> => {
+  const {
+    absolute = true,
+    aliases = {},
+    condition = 'default',
+    conditions = CONDITIONS,
+    cwd = pathToFileURL('.'),
+    ext,
+    extensions = RESOLVE_EXTENSIONS,
+    parent = import.meta.url,
+    preserveSymlinks = false
+  } = options
+
+  // ensure specifier is a string
+  validateString(specifier, 'specifier')
+
+  // ensure option schemas
+  validateBoolean(absolute, 'options.absolute')
+  validateObject(aliases, 'options.aliases')
+  validateString(condition, 'options.condition')
+  validateURLString(cwd, 'options.cwd')
+  validateSet(extensions, 'options.extensions')
+  validateURLString(parent, 'options.parent')
+  validateBoolean(preserveSymlinks, 'options.preserveSymlinks')
+
+  /**
+   * Parsed module id.
+   *
+   * **Note**: Ensures {@linkcode specifier} is a valid module specifier.
+   *
+   * @const {ParsedModuleId} id
+   */
+  const id: ParsedModuleId = parseModuleId(specifier, {
+    parent: toURL(parent),
+    pkgname: false
+  })
+
+  /**
+   * Path aliases defined in {@linkcode aliases}.
+   *
+   * @const {string[]} keys
+   */
+  const keys: string[] = Object.keys(aliases).sort(compareSubpaths)
+
+  /**
+   * Path alias in {@linkcode aliases} that maps to {@linkcode specifier}.
+   *
+   * @var {Nullable<string>} key
+   */
+  let alias: Nullable<string> = null
+
+  /**
+   * Everything after {@linkcode alias} in {@linkcode specifier}.
+   *
+   * @var {string} trail
+   */
+  let trail: string = ''
+
+  // match specifier to alias
+  for (const key of keys) {
+    /**
+     * Index of {@linkcode PATTERN_CHARACTER} in {@linkcode key}.
+     *
+     * @const {number} p
+     */
+    const pattern: number = key.indexOf(PATTERN_CHARACTER)
+
+    // no pattern character => need exact match for alias
+    if (pattern === -1 && key === id.raw) {
+      alias = key
+      break
+    }
+
+    // pattern character => need best match for alias
+    if (pattern !== -1 && id.raw.startsWith(key.slice(0, pattern))) {
+      /**
+       * Everything after pattern character (`*`) in {@linkcode key}.
+       *
+       * @const {string} trailer
+       */
+      const trailer: string = key.slice(pattern + 1)
+
+      // best match found => reset key and base
+      if (
+        id.raw.length >= key.length &&
+        id.raw.endsWith(trailer) &&
+        compareSubpaths(alias ?? '', key) === CompareResult.GREATER_THAN &&
+        key.lastIndexOf(PATTERN_CHARACTER) === pattern
+      ) {
+        alias = key
+        trail = id.raw.slice(pattern, id.raw.length - trailer.length)
+      }
+    }
+  }
+
+  // exit early if alias was not found or alias does not map any paths
+  if (alias === null || isNIL(aliases[alias])) return specifier
+
+  /**
+   * URL of directory to resolve non-absolute modules from.
+   *
+   * @const {string} base
+   */
+  const base: string = toURL(cwd).href.replace(/\/$/, '') + pathe.sep
+
+  /**
+   * Resolved module URL.
+   *
+   * @var {Nullable<URL>} url
+   */
+  let url: Nullable<URL> = null
+
+  // try resolving path alias
+  for (let segment of [aliases[alias]!].flat()) {
+    // replace pattern character in segment with trail of specifier
+    if (segment.includes(PATTERN_CHARACTER)) {
+      segment = segment.replace(
+        new RegExp(`${regexp(PATTERN_CHARACTER)}$`),
+        trail
+      )
+    }
+
+    /**
+     * Absolute paths to modules to try resolving.
+     *
+     * @var {Set<string>} tries
+     */
+    let tries: Set<string> = new Set(
+      [
+        '',
+        ...[...extensions].map(ext => pathe.formatExt(ext)),
+        ...[...extensions].map(ext => '/index' + pathe.formatExt(ext))
+      ]
+        .map((suffix: string) => segment + suffix)
+        .filter((segment: string) => segment.length > 0)
+        .map((segment: string) => new URL(segment, base).pathname)
+    )
+
+    // add attempt to resolve possible package export
+    if (segment.startsWith('node_modules')) {
+      const [trypath = ''] = [...tries]
+      tries = new Set([trypath.replace(/.*\/node_modules\//, ''), ...tries])
+    }
+
+    // find first resolvable module
+    for (const trypath of tries) {
+      try {
+        url = await resolveModule(trypath, {
+          condition,
+          conditions,
+          ext,
+          extensions,
+          parent: toURL(parent),
+          preserveSymlinks
+        })
+
+        // exit if module was resolved
+        break
+      } catch {
+        continue
+      }
+    }
+
+    // stop checking path segments if path alias was resolved
+    if (url) break
+  }
+
+  return url
+    ? absolute
+      ? url.href
+      : /\/node_modules\//.test(url.href)
+      ? toBareSpecifier(url, toURL(parent), new Set(conditions))
+      : toRelativeSpecifier(url, toURL(parent))
+    : specifier
+}
+
+export default resolveAlias

package/src/utils/resolve-aliases.ts

@@ -0,0 +1,58 @@
+/**
+ * @file resolveAliases
+ * @module mlly/utils/resolveAliases
+ */
+
+import { SpecifierSyntaxKind } from '#src/enums'
+import type { ResolveAliasOptions } from '#src/interfaces'
+import regexp from '#src/internal/escape-reg-exp'
+import extractStatements from './extract-statements'
+import resolveAlias from './resolve-alias'
+
+/**
+ * Resolves path aliases in the given piece of source `code`.
+ *
+ * @see {@linkcode ResolveAliasOptions}
+ * @see {@linkcode resolveAlias}
+ *
+ * @async
+ *
+ * @param {string} code - Code to evaluate
+ * @param {ResolveAliasOptions} [options={}] - Resolve alias options
+ * @return {Promise<string>} `code` unmodified or with path aliases resolved
+ */
+const resolveAliases = async (
+  code: string,
+  options: ResolveAliasOptions = {}
+): 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 specifier.
+     *
+     * @const {string} specifier
+     */
+    const specifier: string = await resolveAlias(statement.specifier, options)
+
+    // do nothing if original specifier did not contain path alias
+    if (specifier === statement.specifier) continue
+
+    // replace path alias
+    code = code.replace(
+      statement.code,
+      statement.code.replace(
+        new RegExp(`(?<=["'])${regexp(statement.specifier)}(?=["'])`),
+        specifier
+      )
+    )
+  }
+
+  return code
+}
+
+export default resolveAliases

package/src/utils/resolve-extensions.ts

@@ -0,0 +1,33 @@
+/**
+ * @file RESOLVE_EXTENSIONS
+ * @module mlly/utils/RESOLVE_EXTENSIONS
+ */
+
+import type { Ext } from '@flex-development/pathe'
+
+/**
+ * Default resolvable file extensions.
+ *
+ * @see {@linkcode Ext}
+ *
+ * @const {Set<Ext>} RESOLVE_EXTENSIONS
+ */
+const RESOLVE_EXTENSIONS: Set<Ext> = new Set([
+  '.mjs',
+  '.mts',
+  '.cjs',
+  '.cts',
+  '.js',
+  '.ts',
+  '.jsx',
+  '.tsx',
+  '.css',
+  '.json',
+  '.node',
+  '.wasm',
+  '.d.mts',
+  '.d.cts',
+  '.d.ts'
+])
+
+export default RESOLVE_EXTENSIONS