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

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

@@ -1,211 +0,0 @@
-/**
- * @file toBareSpecifier
- * @module mlly/utils/toBareSpecifier
- */
-
-import type { PackageScope, ParsedModuleId } from '#src/interfaces'
-import validateSet from '#src/internal/validate-set'
-import validateURLString from '#src/internal/validate-url-string'
-import type { ModuleId } from '#src/types'
-import {
-  ERR_OPERATION_FAILED,
-  ERR_PACKAGE_PATH_NOT_EXPORTED,
-  ErrorCode,
-  type NodeError
-} from '@flex-development/errnode'
-import { isBuiltin } from '@flex-development/is-builtin'
-import pathe from '@flex-development/pathe'
-import {
-  DOT,
-  cast,
-  isNIL,
-  regexp,
-  type Nullable
-} from '@flex-development/tutils'
-import { URL, fileURLToPath, pathToFileURL } from 'node:url'
-import CONDITIONS from './conditions'
-import findSubpath from './find-subpath'
-import isAbsoluteSpecifier from './is-absolute-specifier'
-import isRelativeSpecifier from './is-relative-specifier'
-import lookupPackageScope from './lookup-package-scope'
-import parseModuleId from './parse-module-id'
-import parseSubpath from './parse-subpath'
-import PATTERN_CHARACTER from './pattern-character'
-import toAbsoluteSpecifier from './to-absolute-specifier'
-import toNodeURL from './to-node-url'
-import toURL from './to-url'
-
-/**
- * Converts the given module `specifier` into a bare specifier.
- *
- * The new specifier is **not** guaranteed to resolve to an existing module, nor
- * is it guaranteed to have a file extension, but it *is* guaranteed to be a
- * package path containing a valid [subpath export][1] if the specifier's parent
- * package uses package [`exports`][2]. If the parent package does not use
- * `exports`, the new specifier is only guaranteed to begin with a valid NPM
- * package name or Node.js [builtin module][3] name.
- *
- * The given module `specifier` should be absolute, syntactically bare (i.e. not
- * begin with `'/'` or `'.'`), or relative to the current working directory
- * (e.g. `'./dist/index.mjs'`).
- *
- * ::: warning
- * Internal specifier (i.e. [subpath import][4]; `'#src'`, `'#src/utils'`)
- * conversion is not supported. Converting *_to_* an internal specifier will be
- * supported in the future.
- * :::
- *
- * [1]: https://nodejs.org/api/packages.html#subpath-exports
- * [2]: https://nodejs.org/api/packages.html#exports
- * [3]: https://nodejs.org/api/module.html#modulebuiltinmodules
- * [4]: https://nodejs.org/api/packages.html#subpath-imports
- *
- * @see {@linkcode CONDITIONS}
- * @see {@linkcode ModuleId}
- * @see https://nodejs.org/api/esm.html#terminology
- *
- * @param {ModuleId} specifier - Module specifier to convert
- * @param {ModuleId} parent - URL of module to resolve from
- * @param {Set<string>?} [conditions=CONDITIONS] - Export conditions
- * @return {string} `specifier` as bare specifier
- * @throws {NodeError}
- */
-const toBareSpecifier = (
-  specifier: ModuleId,
-  parent: ModuleId,
-  conditions: Set<string> = CONDITIONS
-): string => {
-  validateURLString(specifier, 'specifier')
-  validateURLString(parent, 'parent')
-  validateSet(conditions, 'conditions')
-
-  // ensure specifier is a string
-  if (specifier instanceof URL) specifier = specifier.href
-
-  // exit early if specifier is builtin module
-  if (isBuiltin(specifier)) return toNodeURL(specifier)
-
-  // ensure specifier is a path
-  if (specifier.startsWith('file:')) specifier = fileURLToPath(specifier)
-
-  // convert relative specifiers to absolute paths
-  if (isRelativeSpecifier(specifier)) {
-    specifier = fileURLToPath(toAbsoluteSpecifier(specifier))
-  }
-
-  /**
-   * Location to begin package scope search for {@linkcode specifier}.
-   *
-   * @const {URL} url
-   */
-  const url: URL = toURL(
-    isAbsoluteSpecifier(specifier) || specifier.startsWith('node_modules')
-      ? specifier
-      : `node_modules/${specifier}`
-  )
-
-  /**
-   * Package scope result for {@linkcode specifier}.
-   *
-   * @const {Nullable<PackageScope>} scope
-   */
-  const scope: Nullable<PackageScope> =
-    lookupPackageScope(url, pathToFileURL(DOT)) ??
-    lookupPackageScope(specifier, pathToFileURL(DOT))
-
-  // throw if package scope was not found
-  if (!scope) {
-    throw new ERR_OPERATION_FAILED(`Package scope for '${specifier}' not found`)
-  }
-
-  // get package exports and name
-  const { exports, main, name = '', types } = scope.pkgjson
-
-  // convert specifier to bare specifier
-  specifier = url.pathname.includes(name)
-    ? name + url.pathname.replace(new RegExp(`.*?${regexp(name)}`), '')
-    : name + specifier.replace(fileURLToPath(scope.dir.replace(/\/$/, '')), '')
-
-  /**
-   * Parsed module specifier.
-   *
-   * Ensures {@linkcode specifier} has become a bare specifier.
-   *
-   * @const {ParsedModuleId} id
-   */
-  const id: ParsedModuleId = parseModuleId(specifier, {
-    internal: false,
-    parent,
-    pkgname: true
-  })
-
-  // exit early if subpath does not need to be validated
-  if (isNIL(exports)) {
-    // set specifier to package name if specifier is main or types entry point
-    if ([main, types].some(ep => ep === id.path || ep === id.path.slice(2))) {
-      specifier = id.pkg
-    }
-
-    // remove '@types/' prefix to avoid 'Cannot import type declaration files.
-    // Consider importing "*" instead of "@types/*"' (TS6137) error
-    specifier = specifier.replace(/^@types\//, '')
-
-    return specifier
-  }
-
-  // check if specifier contains valid subpath export
-  try {
-    parseSubpath(specifier, exports, { dir: scope.dir, parent })
-  } catch (e: unknown) {
-    // try finding defined subpath if specifier is invalid package path
-    if (cast<NodeError>(e).code === ErrorCode.ERR_PACKAGE_PATH_NOT_EXPORTED) {
-      /**
-       * Package target to find defined subpath for.
-       *
-       * @const {string} target
-       */
-      const target: string = specifier.replace(name, DOT)
-
-      /**
-       * Subpath in {@linkcode exports} thats maps to {@linkcode target}, if any
-       * at all.
-       *
-       * @var {Nullable<string>} subpath
-       */
-      let subpath: Nullable<string> = findSubpath(target, exports, {
-        conditions,
-        dir: scope.dir,
-        parent
-      })
-
-      // throw if target was not matched to a subpath
-      if (subpath === null) {
-        throw new ERR_PACKAGE_PATH_NOT_EXPORTED(
-          fileURLToPath(scope.dir),
-          id.path,
-          fileURLToPath(parent)
-        )
-      }
-
-      // replace pattern character in subpath
-      if (subpath.includes(PATTERN_CHARACTER)) {
-        subpath = subpath.slice(0, subpath.indexOf(PATTERN_CHARACTER)).slice(1)
-        subpath = DOT + target.slice(target.indexOf(subpath))
-      }
-
-      // subpath should not include extension if extension is already included
-      // via package target
-      if (pathe.extname(target) === pathe.extname(subpath)) {
-        subpath = pathe.changeExt(subpath, '')
-      }
-
-      return name + subpath.slice(1)
-    } /* c8 ignore next 3 */
-    // throw original error if package path error is not encountered
-    throw e
-  }
-
-  return specifier
-}
-
-export default toBareSpecifier

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

@@ -1,42 +0,0 @@
-/**
- * @file toDataURL
- * @module mlly/utils/toDataURL
- */
-
-import validateString from '#src/internal/validate-string'
-import type { MimeType } from '#src/types'
-import type { NodeError } from '@flex-development/errnode'
-
-/**
- * Converts `code` into a [`data:` URL][1] using `base64` encoding.
- *
- * ::: tip
- * `data:` URLs only resolve [bare specifiers][2] for builtin modules and
- * [absolute specifiers][2].
- *
- * Call [`await resolveModules(code)`][3] to ensure all specifiers are absolute
- * or bare.
- * :::
- *
- * [1]: https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
- * [2]: https://nodejs.org/api/esm.html#terminology
- * [3]: {@link ./resolve-modules.ts}
- *
- * @see {@linkcode MimeType}
- * @see https://nodejs.org/api/esm.html#esm_data_imports
- *
- * @param {string} code - Code to convert
- * @param {MimeType} [mime='text/javascript'] - MIME type
- * @return {string} `code` as `data:` URL
- * @throws {NodeError<TypeError>} If `code` or `mime` is not a string
- */
-const toDataURL = (
-  code: string,
-  mime: MimeType = 'text/javascript'
-): string => {
-  validateString(code, 'code')
-  validateString(mime, 'mime')
-  return `data:${mime};base64,${Buffer.from(code).toString('base64')}`
-}
-
-export default toDataURL

package/src/utils/to-node-url.ts

@@ -1,27 +0,0 @@
-/**
- * @file toNodeURL
- * @module mlly/utils/toNodeURL
- */
-
-import validateString from '#src/internal/validate-string'
-import type { NodeError } from '@flex-development/errnode'
-
-/**
- * Converts the given module `specifier` to a `node:` URL.
- *
- * ::: warning
- * Does not guarantee the new specifier is an existing Node.js builtin module.
- * :::
- *
- * @see https://nodejs.org/api/esm.html#node-imports
- *
- * @param {string} specifier - Module specifier to convert
- * @return {string} `specifier` as `node:` URL
- * @throws {NodeError<TypeError>} If `specifier` is not a string
- */
-const toNodeURL = (specifier: string): string => {
-  validateString(specifier, 'specifier')
-  return specifier.startsWith('node:') ? specifier : `node:${specifier}`
-}
-
-export default toNodeURL

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

@@ -1,55 +0,0 @@
-/**
- * @file toRelativeSpecifier
- * @module mlly/utils/toRelativeSpecifier
- */
-
-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 { DOT } from '@flex-development/tutils'
-import { URL, fileURLToPath } from 'node:url'
-
-/**
- * Converts `specifier` into a relative specifier.
- *
- * ::: info
- * The relative specifier will only include a file extension if `specifier`
- * includes a file extension.
- * :::
- *
- * @see {@linkcode ModuleId}
- * @see https://nodejs.org/api/esm.html#terminology
- *
- * @param {ModuleId} specifier - Module specifier to convert
- * @param {ModuleId} parent - Parent module URL or path to resolve from
- * @return {string} `specifier` as relative specifier
- * @throws {NodeError<TypeError>} If either `specifier` or `parent` is not a
- * string or an instance of {@linkcode URL}
- */
-const toRelativeSpecifier = (specifier: ModuleId, parent: ModuleId): string => {
-  validateURLString(specifier, 'specifier')
-  validateURLString(parent, 'parent')
-
-  // convert file url objects to file url strings
-  if (parent instanceof URL) parent = parent.href
-  if (specifier instanceof URL) specifier = specifier.href
-
-  // convert file url strings to paths
-  if (parent.startsWith('file:')) parent = fileURLToPath(parent)
-  if (specifier.startsWith('file:')) specifier = fileURLToPath(specifier)
-
-  // convert specifier to relative specifier
-  specifier = pathe
-    .relative(pathe.resolve(parent), pathe.resolve(specifier))
-    .replace(/^\.\.\/?/, '')
-    .replace(/^(\w)/, './$1')
-
-  // set specifier to dot character if empty string
-  // this occurs when specifier is a directory, but is not fully specified
-  if (!specifier) specifier = DOT
-
-  return specifier
-}
-
-export default toRelativeSpecifier

package/src/utils/to-url.ts

@@ -1,30 +0,0 @@
-/**
- * @file toURL
- * @module mlly/utils/toURL
- */
-
-import validateURLString from '#src/internal/validate-url-string'
-import type { ModuleId } from '#src/types'
-import type { NodeError } from '@flex-development/errnode'
-import { URL, pathToFileURL } from 'node:url'
-
-/**
- * Converts the given module `id` to an instance of [`URL`][1].
- *
- * [1]: https://nodejs.org/api/url.html#class-url
- *
- * @see {@linkcode ModuleId}
- *
- * @param {ModuleId} id - Module id to evaluate
- * @param {ModuleId?} [base=pathToFileURL('./')] - Base URL to resolve against
- * @return {URL} `id` as instance of {@linkcode URL}
- * @throws {NodeError<TypeError>} If either `id` or `base` is not a string or an
- * instance of {@linkcode URL}
- */
-const toURL = (id: ModuleId, base: ModuleId = pathToFileURL('./')): URL => {
-  validateURLString(id, 'id')
-  validateURLString(base, 'base')
-  return id instanceof URL ? id : new URL(id, base)
-}
-
-export default toURL

package/src/utils/validate-assertions.ts

@@ -1,126 +0,0 @@
-/**
- * @file validateAssertions
- * @module mlly/utils/validateAssertions
- */
-
-import { AssertType, type Format } from '#src/enums'
-import type { ImportAssertions } from '#src/interfaces'
-import FORMAT_TYPE_MAP from '#src/internal/format-type-map'
-import validateObject from '#src/internal/validate-object'
-import validateString from '#src/internal/validate-string'
-import validateURLString from '#src/internal/validate-url-string'
-import type { ModuleId } from '#src/types'
-import {
-  ERR_IMPORT_ASSERTION_TYPE_FAILED,
-  ERR_IMPORT_ASSERTION_TYPE_MISSING,
-  ERR_IMPORT_ASSERTION_TYPE_UNSUPPORTED,
-  type NodeError
-} from '@flex-development/errnode'
-import {
-  cast,
-  hasOwn,
-  includes,
-  type LiteralUnion,
-  type Optional
-} from '@flex-development/tutils'
-import { URL } from 'node:url'
-
-/**
- * Test a module's `import` assertions.
- *
- * @see {@linkcode Format}
- * @see {@linkcode ImportAssertions}
- * @see {@linkcode ModuleId}
- *
- * @param {ModuleId} url - Module URL of imported module (for error reporting)
- * @param {LiteralUnion<Format, string>} format - Module format
- * @param {ImportAssertions} [assertions={}] - `import` assertions
- * @return {true} `true` if `assertions` are valid
- * @throws {NodeError<TypeError>}
- */
-const validateAssertions = (
-  url: ModuleId,
-  format: LiteralUnion<Format, string>,
-  assertions: ImportAssertions = {}
-): true => {
-  validateURLString(url, 'url')
-  validateString(format, 'format')
-  validateObject(assertions, 'assertions')
-
-  // ensure url is a string
-  if (url instanceof URL) url = url.href
-
-  /**
-   * `type` property check for {@linkcode assertions}.
-   *
-   * @const {boolean} has_type
-   */
-  const has_type: boolean = hasOwn(assertions, 'type')
-
-  /**
-   * `import` assertion type.
-   *
-   * @const {Optional<AssertType>} type
-   */
-  const type: Optional<AssertType> = FORMAT_TYPE_MAP.get(cast(format))
-
-  /**
-   * `import` assertion error check.
-   *
-   * @var {boolean} err
-   */
-  let err: boolean = false
-
-  // validate import assertions
-  switch (type) {
-    case undefined:
-      // ignore assertions for unrecognized module formats to allow for new
-      // formats in the future
-      break
-    case AssertType.IMPLICIT:
-      // format doesn't allow an import assertion type, so the `type` property
-      // must not be set on the import assertions object
-      if (has_type) err = true
-      break
-    case assertions.type:
-      // asserted type is compatible with format
-      break
-    default:
-      // format has an expected type, but asserted type is not compatible
-      err = true
-  }
-
-  // throw if error was encountered
-  if (err) {
-    // import assertion type was not specified
-    if (!has_type) throw new ERR_IMPORT_ASSERTION_TYPE_MISSING(url, type!)
-
-    // import assertion type may have not been a string
-    validateString(assertions.type, 'assertions.type')
-
-    /**
-     * Supported `import` assertion types.
-     *
-     * @const {AssertType[]} supported
-     */
-    const supported: AssertType[] = []
-
-    // get supported import assertion types
-    for (const [, type] of FORMAT_TYPE_MAP) {
-      if (type === AssertType.IMPLICIT) continue
-      supported.push(type)
-    }
-
-    // throw if asserted type is not supported
-    if (!includes(supported, assertions.type)) {
-      throw new ERR_IMPORT_ASSERTION_TYPE_UNSUPPORTED(assertions.type!)
-    }
-
-    // unknown error
-    throw new ERR_IMPORT_ASSERTION_TYPE_FAILED(url, assertions.type!)
-  }
-
-  return true
-}
-
-export default validateAssertions

package/src/utils/validate-exports.ts

@@ -1,131 +0,0 @@
-/**
- * @file validateExports
- * @module mlly/utils/validateExports
- */
-
-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 type { Exports } from '@flex-development/pkg-types'
-import {
-  DOT,
-  at,
-  cast,
-  isArray,
-  isArrayIndex,
-  isNIL,
-  isObjectCurly,
-  isString,
-  type Optional
-} from '@flex-development/tutils'
-import { URL, fileURLToPath } from 'node:url'
-
-/**
- * Validates the given package [`exports`][1] configuration and schema.
- *
- * [1]: https://nodejs.org/api/packages.html#exports
- *
- * @see {@linkcode Exports}
- * @see {@linkcode ModuleId}
- *
- * @param {Optional<Exports>} exports - Package `exports`
- * @param {ModuleId} pkg - URL of relevant `package.json` file
- * @param {ModuleId} parent - URL of module to resolve from
- * @return {true} `true` if `exports` configuration and schema are valid
- * @throws {NodeError<Error | TypeError>} If either `pkg` or `parent` is not a
- * string or an instance of {@linkcode URL}, or if `exports` configuration or
- * schema is invalid
- */
-const validateExports = (
-  exports: Optional<Exports>,
-  pkg: ModuleId,
-  parent: ModuleId
-): true => {
-  validateURLString(pkg, 'pkg')
-  validateURLString(parent, 'parent')
-
-  switch (true) {
-    case isArray(exports):
-      for (const item of cast<unknown[]>(exports)) {
-        switch (true) {
-          case !isObjectCurly(item) && !isString(item):
-            throw new ERR_INVALID_PACKAGE_CONFIG(
-              fileURLToPath(pkg),
-              fileURLToPath(parent),
-              'The "exports" array must contain either objects of package subpath keys, objects of condition name keys, or strings'
-            )
-          default:
-            validateExports(
-              cast<Record<string, Exports> | string>(item),
-              pkg,
-              parent
-            )
-            break
-        }
-      }
-
-      break
-    case isNIL(exports):
-    case isString(exports):
-      break
-    case !isObjectCurly(exports):
-      throw new ERR_INVALID_PACKAGE_CONFIG(
-        fileURLToPath(pkg),
-        fileURLToPath(parent),
-        '"exports" must be null, undefined, a string, an object of package subpath keys or condition name keys, or an array containing objects of package subpath keys, objects of condition name keys, or strings'
-      )
-    default:
-      exports = cast<Record<string, Exports>>(exports)
-
-      /**
-       * Keys defined in {@linkcode exports}.
-       *
-       * @const {string[]} keys
-       */
-      const keys: string[] = Object.getOwnPropertyNames(exports)
-
-      // validate keys
-      for (const [index, key] of keys.entries()) {
-        // ensure key is not an array index
-        if (isArrayIndex(key)) {
-          throw new ERR_INVALID_PACKAGE_CONFIG(
-            fileURLToPath(new URL(DOT, pkg)),
-            fileURLToPath(parent),
-            '"exports" cannot contain numeric property keys'
-          )
-        }
-
-        // if more than one key in keys, ensure all keys are either syntactical
-        // export conditions or subpath exports
-        if (index) {
-          /**
-           * Key before {@linkcode key} in {@linkcode keys}.
-           *
-           * @const {string} prev
-           */
-          const prev: string = at(keys, index - 1)
-
-          // ensure keys are syntactical export conditions or subpath exports
-          if (
-            (!key.startsWith(DOT) && prev.startsWith(DOT)) ||
-            (key.startsWith(DOT) && !prev.startsWith(DOT))
-          ) {
-            throw new ERR_INVALID_PACKAGE_CONFIG(
-              fileURLToPath(pkg),
-              fileURLToPath(parent),
-              '"exports" cannot contain some keys starting with \'.\' and some not. The exports object must either be an object of package subpath keys or an object of main entry condition name keys only.'
-            )
-          }
-        }
-      }
-
-      break
-  }
-
-  return true
-}
-
-export default validateExports