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

package/src/utils/index.ts

@@ -0,0 +1,43 @@
+/**
+ * @file Utilities
+ * @module mlly/utils
+ */
+
+export { default as compareSubpaths } from './compare-subpaths'
+export { default as CONDITIONS } from './conditions'
+export { default as detectSyntax } from './detect-syntax'
+export { default as EXTENSION_FORMAT_MAP } from './extension-format-map'
+export { default as extractStatements } from './extract-statements'
+export { default as fillModules } from './fill-modules'
+export { default as findDynamicImports } from './find-dynamic-imports'
+export { default as findExports } from './find-exports'
+export { default as findRequires } from './find-requires'
+export { default as findStaticImports } from './find-static-imports'
+export { default as findSubpath } from './find-subpath'
+export { default as getFormat } from './get-format'
+export { default as getSource } from './get-source'
+export { default as hasCJSSyntax } from './has-cjs-syntax'
+export { default as hasESMSyntax } from './has-esm-syntax'
+export { default as isAbsoluteSpecifier } from './is-absolute-specifier'
+export { default as isBareSpecifier } from './is-bare-specifier'
+export { default as isExportsSugar } from './is-exports-sugar'
+export { default as isRelativeSpecifier } from './is-relative-specifier'
+export { default as lookupPackageScope } from './lookup-package-scope'
+export { default as parseDataURL } from './parse-data-url'
+export { default as parseModuleId } from './parse-module-id'
+export { default as parseSubpath } from './parse-subpath'
+export { default as PATTERN_CHARACTER } from './pattern-character'
+export { default as readPackageJson } from './read-package-json'
+export { default as resolveAlias } from './resolve-alias'
+export { default as resolveAliases } from './resolve-aliases'
+export { default as RESOLVE_EXTENSIONS } from './resolve-extensions'
+export { default as resolveModule } from './resolve-module'
+export { default as resolveModules } from './resolve-modules'
+export { default as toAbsoluteSpecifier } from './to-absolute-specifier'
+export { default as toBareSpecifier } from './to-bare-specifier'
+export { default as toDataURL } from './to-data-url'
+export { default as toNodeURL } from './to-node-url'
+export { default as toRelativeSpecifier } from './to-relative-specifier'
+export { default as toURL } from './to-url'
+export { default as validateAssertions } from './validate-assertions'
+export { default as validateExports } from './validate-exports'

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

@@ -0,0 +1,48 @@
+/**
+ * @file isAbsoluteSpecifier
+ * @module mlly/utils/isAbsoluteSpecifier
+ */
+
+import pathe from '@flex-development/pathe'
+import { URL } from 'node:url'
+
+/**
+ * Checks if the given `specifier` is an absolute specifier.
+ *
+ * ::: warning
+ * Only checks specifier syntax. Does **not** guarantee the specifier references
+ * a file that exists.
+ * :::
+ *
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @param {string} specifier - Specifier to evaluate
+ * @return {boolean} `true` if `specifier` is absolute specifier
+ */
+const isAbsoluteSpecifier = (specifier: string): boolean => {
+  /**
+   * Absolute specifier check.
+   *
+   * @var {string} absolute
+   */
+  let absolute: boolean = false
+
+  // check if specifier is absolute path or valid file url
+  switch (true) {
+    case pathe.isAbsolute(specifier):
+      absolute = true
+      break
+    case specifier.startsWith('file:'):
+      try {
+        new URL(specifier)
+        absolute = true
+      } /* c8 ignore next */ catch {}
+      break
+    default:
+      absolute = false
+  }
+
+  return absolute
+}
+
+export default isAbsoluteSpecifier

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

@@ -0,0 +1,30 @@
+/**
+ * @file isBareSpecifier
+ * @module mlly/utils/isBareSpecifier
+ */
+
+import isAbsoluteSpecifier from './is-absolute-specifier'
+import isRelativeSpecifier from './is-relative-specifier'
+
+/**
+ * Checks if the given `specifier` is a bare specifier.
+ *
+ * ::: warning
+ * Only checks specifier syntax. Does **not** guarantee the specifier references
+ * a file that exists.
+ * :::
+ *
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @param {string} specifier - Specifier to evaluate
+ * @return {boolean} `true` if `specifier` is bare specifier
+ */
+const isBareSpecifier = (specifier: string): boolean => {
+  return (
+    specifier.trim().length > 0 &&
+    !isAbsoluteSpecifier(specifier) &&
+    !isRelativeSpecifier(specifier)
+  )
+}
+
+export default isBareSpecifier

package/src/utils/is-exports-sugar.ts

@@ -0,0 +1,74 @@
+/**
+ * @file isExportsSugar
+ * @module mlly/utils/isExportsSugar
+ */
+
+import type { ModuleId } from '#src/types'
+import type { NodeError } from '@flex-development/errnode'
+import type { Exports } from '@flex-development/pkg-types'
+import { isNIL } from '@flex-development/tutils'
+import validateExports from './validate-exports'
+
+/**
+ * Checks if the given package [`exports`][1] value is using [exports sugar][2].
+ *
+ * [1]: https://nodejs.org/api/packages.html#exports
+ * [2]: https://nodejs.org/api/packages.html#exports-sugar
+ *
+ * @see {@linkcode Exports}
+ * @see {@linkcode ModuleId}
+ *
+ * @param {Exports | undefined} exports - Package `exports`
+ * @param {ModuleId} pkg - URL of relevant `package.json` file
+ * @param {ModuleId} parent - URL of module to resolve from
+ * @return {boolean} `true` if `exports` is using exports sugar
+ * @throws {NodeError<Error | TypeError>} If either `pkg` or `parent` is not an
+ * instance of {@linkcode URL} or a string, or if `exports` configuration or
+ * schema is invalid
+ */
+const isExportsSugar = (
+  exports: Exports | undefined,
+  pkg: ModuleId,
+  parent: ModuleId
+): boolean => {
+  /**
+   * [Exports sugar][1] check.
+   *
+   * [1]: https://nodejs.org/api/packages.html#exports-sugar
+   *
+   * @var {boolean} sugar
+   */
+  let sugar: boolean = false
+
+  // check if exports sugar is being used
+  switch (true) {
+    case Array.isArray(exports):
+    case typeof exports === 'string':
+      sugar = true
+      break
+    case isNIL(exports):
+    case typeof exports !== 'object':
+      sugar = false
+      break
+    default:
+      exports = exports as Record<string, Exports>
+
+      /*
+       * Validate exports object configuration.
+       *
+       * This ensures the exports object is either an object of package subpath
+       * keys (i.e. keys starting with '.') or an object of main entry condition
+       * name keys (i.e. keys not starting with '.') only. An error will be
+       * thrown otherwise. This also means only the first key in `keys` needs to
+       * be checked for exports sugar usage.
+       */
+      validateExports(exports, pkg, parent)
+
+      // check for exports sugar
+      sugar = !Object.getOwnPropertyNames(exports)[0]?.startsWith('.')
+  }
+
+  return sugar
+}
+
+export default isExportsSugar

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

@@ -0,0 +1,34 @@
+/**
+ * @file isRelativeSpecifier
+ * @module mlly/utils/isRelativeSpecifier
+ */
+
+import validateString from '#src/internal/validate-string'
+import type { NodeError } from '@flex-development/errnode'
+import pathe from '@flex-development/pathe'
+
+/**
+ * Checks if the given `specifier` is a relative specifier.
+ *
+ * ::: warning
+ * Only checks specifier syntax. Does **not** guarantee the specifier references
+ * a file that exists.
+ * :::
+ *
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @param {string} specifier - Specifier to evaluate
+ * @return {boolean} `true` if `specifier` is relative specifier
+ * @throws {NodeError<TypeError>} If `specifier` is not a string
+ */
+const isRelativeSpecifier = (specifier: string): boolean => {
+  validateString(specifier, 'specifier')
+  return specifier.startsWith('.')
+    ? specifier.length === 1 || specifier[1] === pathe.sep
+      ? true
+      : specifier[1] === '.' &&
+        (specifier.length === 2 || specifier[2] === pathe.sep)
+    : false
+}
+
+export default isRelativeSpecifier

package/src/utils/lookup-package-scope.ts

@@ -0,0 +1,97 @@
+/**
+ * @file lookupPackageScope
+ * @module mlly/utils/lookupPackageScope
+ */
+
+import type { PackageScope } from '#src/interfaces'
+import validateURLString from '#src/internal/validate-url-string'
+import type { ModuleId } from '#src/types'
+import type { NodeError } from '@flex-development/errnode'
+import pathe from '@flex-development/pathe'
+import type { PackageJson } from '@flex-development/pkg-types'
+import type { Nullable } from '@flex-development/tutils'
+import { pathToFileURL } from 'node:url'
+import readPackageJson from './read-package-json'
+import toURL from './to-url'
+
+/**
+ * Finds a `package.json` file for the given module `id`. Ends the search at the
+ * given end point **after** checking for a `package.json` file.
+ *
+ * Returns `null` if a `package.json` file is not found.
+ *
+ * @see {@linkcode ModuleId}
+ * @see {@linkcode PackageScope}
+ *
+ * @param {ModuleId} id - Id of module to get package scope for
+ * @param {ModuleId?} [stopdir=pathe.sep] - Directory to end search
+ * @param {string?} [specifier] - Module specifier passed by user
+ * @param {ModuleId?} [parent] - Id of module to resolve from
+ * @return {?PackageScope} Package scope result or `null`
+ * @throws {NodeError<TypeError>} If either `id` or `stopdir` is not an instance
+ * of {@linkcode URL} or a string
+ */
+const lookupPackageScope = (
+  id: ModuleId,
+  stopdir: ModuleId = pathe.sep,
+  specifier?: string,
+  parent?: ModuleId
+): Nullable<PackageScope> => {
+  validateURLString(id, 'id')
+  validateURLString(stopdir, 'stopdir')
+
+  // ensure search endpoint is a path
+  stopdir = toURL(stopdir).pathname
+
+  /**
+   * Path to directory containing `package.json` file.
+   *
+   * @var {string} dir
+   */
+  let dir: string = toURL(id).pathname
+
+  /**
+   * Package scope result.
+   *
+   * @var {Nullable<PackageScope>} scope
+   */
+  let scope: Nullable<PackageScope> = null
+
+  // search for package.json
+  while (dir && !dir.endsWith('node_modules')) {
+    // stop search if outside of endpoint
+    if (pathe.relative(stopdir, dir).startsWith('../')) break
+
+    /**
+     * Possible `package.json` object.
+     *
+     * @const {Nullable<PackageJson>} pkgjson
+     */
+    const pkgjson: Nullable<PackageJson> = readPackageJson(
+      dir,
+      specifier,
+      parent
+    )
+
+    // stop search if package.json has been found
+    if (pkgjson) {
+      scope = {
+        dir: pathToFileURL((dir = pathe.resolve(process.cwd(), dir))).href,
+        pkg: pathToFileURL(pathe.join(dir, 'package.json')).href,
+        pkgjson
+      }
+
+      break
+    }
+
+    // stop search if endpoint has been reached
+    if (dir === stopdir.replace(/\/$/, '')) break
+
+    // continue searching for package.json
+    dir = pathe.dirname(dir)
+  }
+
+  return scope
+}
+
+export default lookupPackageScope

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

@@ -0,0 +1,71 @@
+/**
+ * @file parseDataURL
+ * @module mlly/utils/parseDataURL
+ */
+
+import type { ParsedDataUrl } from '#src/interfaces'
+import {
+  ERR_INVALID_URL,
+  type ErrInvalidUrl,
+  type NodeError
+} from '@flex-development/errnode'
+import type { Nullable } from '@flex-development/tutils'
+import type { URL } from 'node:url'
+import toURL from './to-url'
+
+/**
+ * Parses a [`data:` URL][1].
+ *
+ * If valid, returns an object representing the given `url`.
+ *
+ * **Note**: A [MIME type][2] string is required.
+ *
+ * [1]: https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs
+ * [2]: https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/MIME_types
+ *
+ * @see https://nodejs.org/api/esm.html#data-imports
+ *
+ * @param {URL | string} url - URL to evaluate
+ * @return {ParsedDataUrl} Object representing `url`
+ * @throws {ErrInvalidUrl | NodeError<TypeError>} If `url` is not a string or
+ * instance of {@linkcode URL}, or if `url` not a valid `data:` URL
+ */
+const parseDataURL = (url: URL | string): ParsedDataUrl => {
+  // ensure url is an instance of URL
+  url = toURL(url)
+
+  /**
+   * Regex to extract `data:` URL components.
+   *
+   * @see https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs
+   * @see https://regex101.com/r/Ie8Doq
+   *
+   * @const {RegExp} regex
+   */
+  const regex: RegExp =
+    /^(?<protocol>data:)(?<mime>[^/]+\/[^,;]+)[^,]*?(?:;(?<base64>base64))?,(?<data>[\S\s]*?)$/
+
+  /**
+   * `data:` URL match.
+   *
+   * @const {Nullable<RegExpExecArray>} match
+   */
+  const match: Nullable<RegExpExecArray> = regex.exec(url.href)
+
+  // throw if url is not data url
+  if (!match) throw new ERR_INVALID_URL(url.href)
+
+  // get data url components
+  const [, , mime = '', base64, data = ''] = match
+
+  return {
+    base64: !!base64,
+    data: data.trim(),
+    href: url.href,
+    mime,
+    pathname: url.pathname,
+    protocol: url.protocol as ParsedDataUrl['protocol']
+  }
+}
+
+export default parseDataURL

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

@@ -0,0 +1,186 @@
+/**
+ * @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 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 { 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>} If `id` is not an instance of {@linkcode URL}
+ * or a string, if `id` includes encoded path separators, or if `id` is invalid
+ * according to `options.internal` or `options.pkgname`
+ */
+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 id a string without leading and trailing spaces
+  id = id instanceof URL ? id.href : id.trim()
+
+  /**
+   * Reason for [`ERR_INVALID_MODULE_SPECIFIER`][1], if any.
+   *
+   * [1]: https://nodejs.org/api/errors.html#err_invalid_module_specifier
+   *
+   * @const {string | undefined} error
+   */
+  let error: string | undefined
+
+  /**
+   * 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: '.' + 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(id as string):
+    case isRelativeSpecifier(id as string):
+    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 (error !== undefined) {
+    let { parent } = options
+
+    if (parent !== undefined) {
+      validateURLString(parent, 'options.parent')
+      parent = fileURLToPath(parent)
+    }
+
+    throw new ERR_INVALID_MODULE_SPECIFIER(id, error, parent)
+  }
+
+  return parsed
+}
+
+export default parseModuleId