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

package/src/interfaces/statement-export.ts

@@ -0,0 +1,52 @@
+/**
+ * @file Interfaces - ExportStatement
+ * @module mlly/interfaces/ExportStatement
+ */
+
+import type { StatementKind } from '#src/enums'
+import type { Declaration, SyntaxKindExport } from '#src/types'
+import type { Nullable } from '@flex-development/tutils'
+import type Statement from './statement'
+
+/**
+ * Export statement object.
+ *
+ * @see {@linkcode Declaration}
+ * @see {@linkcode Statement}
+ * @see {@linkcode SyntaxKindExport}
+ *
+ * @extends {Statement}
+ */
+interface ExportStatement extends Statement {
+  /**
+   * Export declaration, if any.
+   */
+  declaration: Nullable<Declaration>
+
+  /**
+   * Export names.
+   */
+  exports: string[]
+
+  /**
+   * Statement kind.
+   */
+  kind: StatementKind.EXPORT
+
+  /**
+   * Modifier keywords.
+   */
+  modifiers: string[]
+
+  /**
+   * Statement syntax kind.
+   */
+  syntax: SyntaxKindExport
+
+  /**
+   * Type-only export statement check.
+   */
+  type: boolean
+}
+
+export type { ExportStatement as default }

package/src/interfaces/statement-import.ts

@@ -0,0 +1,45 @@
+/**
+ * @file Interfaces - ImportStatement
+ * @module mlly/interfaces/ImportStatement
+ */
+
+import type { StatementKind } from '#src/enums'
+import type { SyntaxKindImport } from '#src/types'
+import type Statement from './statement'
+
+/**
+ * Import statement object.
+ *
+ * @see {@linkcode Statement}
+ * @see {@linkcode SyntaxKindImport}
+ *
+ * @extends {Statement}
+ */
+interface ImportStatement extends Statement {
+  /**
+   * Import names.
+   */
+  imports: string[]
+
+  /**
+   * Statement kind.
+   */
+  kind: StatementKind.IMPORT
+
+  /**
+   * Module specifier.
+   */
+  specifier: NonNullable<Statement['specifier']>
+
+  /**
+   * Module specifier syntax type.
+   */
+  specifier_syntax: NonNullable<Statement['specifier_syntax']>
+
+  /**
+   * Statement syntax kind.
+   */
+  syntax: SyntaxKindImport
+}
+
+export type { ImportStatement as default }

package/src/interfaces/statement-require.ts

@@ -0,0 +1,45 @@
+/**
+ * @file Interfaces - RequireStatement
+ * @module mlly/interfaces/RequireStatement
+ */
+
+import type { StatementKind } from '#src/enums'
+import type { SyntaxKindRequire } from '#src/types'
+import type Statement from './statement'
+
+/**
+ * Require statement object.
+ *
+ * @see {@linkcode Statement}
+ * @see {@linkcode SyntaxKindRequire}
+ *
+ * @extends {Statement}
+ */
+interface RequireStatement extends Statement {
+  /**
+   * Import names.
+   */
+  imports: string[]
+
+  /**
+   * Statement kind.
+   */
+  kind: StatementKind.REQUIRE
+
+  /**
+   * Module specifier.
+   */
+  specifier: NonNullable<Statement['specifier']>
+
+  /**
+   * Module specifier syntax type.
+   */
+  specifier_syntax: NonNullable<Statement['specifier_syntax']>
+
+  /**
+   * Statement syntax kind.
+   */
+  syntax: SyntaxKindRequire
+}
+
+export type { RequireStatement as default }

package/src/interfaces/statement.ts

@@ -0,0 +1,64 @@
+/**
+ * @file Interfaces - Statement
+ * @module mlly/interfaces/Statement
+ */
+
+import type {
+  SpecifierKind,
+  SpecifierSyntaxKind,
+  StatementKind,
+  StatementSyntaxKind
+} from '#src/enums'
+import type { Nullable } from '@flex-development/tutils'
+
+/**
+ * CommonJS or ESM statement object.
+ *
+ * @see {@linkcode SpecifierKind}
+ * @see {@linkcode SpecifierSyntaxKind}
+ * @see {@linkcode StatementKind}
+ * @see {@linkcode StatementSyntaxKind}
+ */
+interface Statement {
+  /**
+   * Statement snippet.
+   */
+  code: string
+
+  /**
+   * End index of {@linkcode code} in source content.
+   */
+  end: number
+
+  /**
+   * Statement kind.
+   */
+  kind: StatementKind
+
+  /**
+   * Module specifier.
+   */
+  specifier: Nullable<string>
+
+  /**
+   * Module specifier type.
+   */
+  specifier_kind: Nullable<SpecifierKind>
+
+  /**
+   * Module specifier syntax type.
+   */
+  specifier_syntax: Nullable<SpecifierSyntaxKind>
+
+  /**
+   * Start index of {@linkcode code} in source content.
+   */
+  start: number
+
+  /**
+   * Statement syntax kind.
+   */
+  syntax: StatementSyntaxKind
+}
+
+export type { Statement as default }

package/src/internal/escape-reg-exp.ts

@@ -0,0 +1,24 @@
+/**
+ * @file Internal - escapeRegExp
+ * @module mlly/internal/escapeRegExp
+ */
+
+import type { NodeError } from '@flex-development/errnode'
+import validateString from './validate-string'
+
+/**
+ * Escapes special characters in the given regex `pattern`.
+ *
+ * A backslash escape (`\\`) is used when valid. A `\x2d` escape is used when
+ * the former would be disallowed by stricter Unicode pattern grammar.
+ *
+ * @param {string} pattern - Regex pattern to escape
+ * @return {string} `pattern` with special characters escaped
+ * @throws {NodeError<TypeError>} If `pattern` is not a string
+ */
+const escapeRegExp = (pattern: string): string => {
+  validateString(pattern, 'pattern')
+  return pattern.replace(/[$()*+.?[\\\]^{|}]/g, '\\$&').replace(/-/g, '\\x2d')
+}
+
+export default escapeRegExp

package/src/internal/format-type-map.ts

@@ -0,0 +1,26 @@
+/**
+ * @file Internal - FORMAT_TYPE_MAP
+ * @module mlly/internal/FORMAT_TYPE_MAP
+ */
+
+import { AssertType, Format } from '#src/enums'
+
+/**
+ * Module format to `import` assertion type map.
+ *
+ * **Note**:  It's unclear whether or not the HTML spec will require assertion
+ * types for WebAssembly modules.
+ *
+ * @see https://github.com/WebAssembly/esm-integration/issues/42
+ *
+ * @const {Map<Format, AssertType>} FORMAT_TYPE_MAP
+ */
+const FORMAT_TYPE_MAP: Map<Format, AssertType> = new Map<Format, AssertType>([
+  [Format.BUILTIN, AssertType.IMPLICIT],
+  [Format.COMMONJS, AssertType.IMPLICIT],
+  [Format.JSON, AssertType.JSON],
+  [Format.MODULE, AssertType.IMPLICIT],
+  [Format.WASM, AssertType.IMPLICIT]
+])
+
+export default FORMAT_TYPE_MAP

package/src/internal/get-specifier-kind.ts

@@ -0,0 +1,38 @@
+/**
+ * @file Internal - getSpecifierKind
+ * @module mlly/internal/getSpecifierKind
+ */
+
+import { SpecifierKind } from '#src/enums'
+import validateString from '#src/internal/validate-string'
+import isAbsoluteSpecifier from '#src/utils/is-absolute-specifier'
+import isRelativeSpecifier from '#src/utils/is-relative-specifier'
+import type { NodeError } from '@flex-development/errnode'
+import type { Nullable } from '@flex-development/tutils'
+
+/**
+ * Determines a specifier type for the given module `specifier`.
+ *
+ * @see {@linkcode SpecifierKind}
+ *
+ * @param {string} specifier - Module specifier to evaluate
+ * @return {Nullable<SpecifierKind>} Module `specifier` type or `null`
+ * @throws {NodeError<TypeError>} If `specifier` is not a string
+ */
+const getSpecifierKind = (specifier: string): Nullable<SpecifierKind> => {
+  validateString(specifier, 'specifier')
+
+  // trim specifier and remove quotes (quotes could lead to a specifier being
+  // classified as 'bare' when it is actually absolute or relative)
+  specifier = specifier.trim().replace(/^["']|["']$/g, '')
+
+  return specifier
+    ? isAbsoluteSpecifier(specifier)
+      ? SpecifierKind.ABSOLUTE
+      : isRelativeSpecifier(specifier)
+      ? SpecifierKind.RELATIVE
+      : SpecifierKind.BARE
+    : null
+}
+
+export default getSpecifierKind

package/src/internal/get-subpaths.ts

@@ -0,0 +1,41 @@
+/**
+ * @file Internal - getSubpaths
+ * @module mlly/internal/getSubpaths
+ */
+
+import type { ModuleId } from '#src/types'
+import isExportsSugar from '#src/utils/is-exports-sugar'
+import type { Exports, Imports } from '@flex-development/pkg-types'
+import { isNIL } from '@flex-development/tutils'
+
+/**
+ * Returns an array containing subpaths defined in the given package `context`,
+ * a `package.json` [`exports`][1] or [`imports`][2] field.
+ *
+ * If `context` is using [exports sugar][3], the array will contain a single
+ * subpath, `'.'`.
+ *
+ * [1]: https://nodejs.org/api/packages.html#exports
+ * [2]: https://nodejs.org/api/packages.html#imports
+ * [3]: https://nodejs.org/api/packages.html#exports-sugar
+ *
+ * @param {Exports | Imports | undefined} context - Package context
+ * @param {boolean} internal - Package `imports` hint
+ * @param {ModuleId} pkg - URL of relevant `package.json` file
+ * @param {ModuleId} parent - URL of module to resolve from
+ * @return {string[]} Subpaths defined in `context`
+ */
+const getSubpaths = (
+  context: Exports | Imports | undefined,
+  internal: boolean,
+  pkg: ModuleId,
+  parent: ModuleId
+): string[] => {
+  return isNIL(context)
+    ? []
+    : !internal && isExportsSugar(context, pkg, parent)
+    ? ['.']
+    : Object.keys(context as Imports | Record<string, Exports>)
+}
+
+export default getSubpaths

package/src/internal/is-array-index.ts

@@ -0,0 +1,28 @@
+/**
+ * @file Internals - isArrayIndex
+ * @module mlly/internal/isArrayIndex
+ */
+
+import type { Numeric } from '@flex-development/tutils'
+
+/**
+ * Checks if if the given `key` is a numeric property key as defined in ECMA-262
+ * [6.1.7 Array Index][1].
+ *
+ * [1]: https://tc39.es/ecma262/#integer-index
+ *
+ * @param {string} key - Property key to evaluate
+ * @return {key is Numeric} `true` if `key` is numeric property key
+ */
+const isArrayIndex = (key: string): key is Numeric => {
+  /**
+   * {@linkcode key} as number.
+   *
+   * @const {number} num
+   */
+  const num: number = +key
+
+  return `${num}` !== key ? false : num >= 0 && num < 0xffff_ffff
+}
+
+export default isArrayIndex

package/src/internal/is-directory.ts

@@ -0,0 +1,25 @@
+/**
+ * @file Internal - isDirectory
+ * @module mlly/internal/isDirectory
+ */
+
+import type { ModuleId } from '#src/types'
+import fs from 'node:fs'
+import validateURLString from './validate-url-string'
+
+/**
+ * Checks if a directory exists at the given module `id`.
+ *
+ * @param {ModuleId} id - Module id to evaluate
+ * @return {boolean} `true` if directory exists at `id`
+ */
+const isDirectory = (id: ModuleId): boolean => {
+  try {
+    validateURLString(id, 'id')
+    return fs.statSync(id, { throwIfNoEntry: false })?.isDirectory() ?? false
+  } catch {
+    return false
+  }
+}
+
+export default isDirectory

package/src/internal/is-file.ts

@@ -0,0 +1,25 @@
+/**
+ * @file Internal - isFile
+ * @module mlly/internal/isFile
+ */
+
+import type { ModuleId } from '#src/types'
+import fs from 'node:fs'
+import validateURLString from './validate-url-string'
+
+/**
+ * Checks if a file exists at the given module `id`.
+ *
+ * @param {ModuleId} id - Module id to evaluate
+ * @return {boolean} `true` if file exists at `id`
+ */
+const isFile = (id: ModuleId): boolean => {
+  try {
+    validateURLString(id, 'id')
+    return fs.statSync(id, { throwIfNoEntry: false })?.isFile() ?? false
+  } catch {
+    return false
+  }
+}
+
+export default isFile

package/src/internal/is-function.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Internal - isFunction
+ * @module mlly/internal/isFunction
+ */
+
+/**
+ * Checks if the given `value` is a function.
+ *
+ * @param {unknown} value - Value to check
+ * @return {value is (...args: any[]) => any} `true` if `value` is a unction
+ */
+const isFunction = (value: unknown): value is (...args: any[]) => any => {
+  return typeof value === 'function'
+}
+
+export default isFunction

package/src/internal/regex-encoded-sep.ts

@@ -0,0 +1,15 @@
+/**
+ * @file Internal - ENCODED_SEP_REGEX
+ * @module mlly/internal/ENCODED_SEP_REGEX
+ */
+
+/**
+ * Regex pattern matching encoded path separators (e.g `/`, `\\`).
+ *
+ * @see https://regex101.com/r/XV7HzM
+ *
+ * @const {RegExp} ENCODED_SEP_REGEX
+ */
+const ENCODED_SEP_REGEX: RegExp = /%2f|%5c/i
+
+export default ENCODED_SEP_REGEX

package/src/internal/regex-internal-specifier.ts

@@ -0,0 +1,17 @@
+/**
+ * @file Internal - INTERNAL_SPECIFIER_REGEX
+ * @module mlly/internal/INTERNAL_SPECIFIER_REGEX
+ */
+
+/**
+ * Regex pattern matching subpath imports.
+ *
+ * @see https://regex101.com/r/ppVRw7
+ * @see https://nodejs.org/api/packages.html#subpath-imports
+ *
+ * @const {RegExp} INTERNAL_SPECIFIER_REGEX
+ */
+const INTERNAL_SPECIFIER_REGEX: RegExp =
+  /^(?!.*(?:%2[Ff]|%5[Cc]))(?<root>#[^\s/]+?(?=\s|$|\/))(?<path>\/.+[^/](?=\s|$))?(?!\/)/
+
+export default INTERNAL_SPECIFIER_REGEX

package/src/internal/regex-package-name.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Internal - PACKAGE_NAME_REGEX
+ * @module mlly/internal/PACKAGE_NAME_REGEX
+ */
+
+/**
+ * Regex pattern matching package names.
+ *
+ * @see https://regex101.com/r/BHcJfc
+ *
+ * @const {RegExp} PACKAGE_NAME_REGEX
+ */
+const PACKAGE_NAME_REGEX: RegExp =
+  /^(?:(?<scope>@[\d*a-z~-][\w*.~-]*)\/)?[\da-z~-][\w.~-]*$/
+
+export default PACKAGE_NAME_REGEX

package/src/internal/regex-package-path.ts

@@ -0,0 +1,18 @@
+/**
+ * @file Internal - PACKAGE_PATH_REGEX
+ * @module mlly/internal/PACKAGE_PATH_REGEX
+ */
+
+/**
+ * Regex pattern matching bare specifiers beginning with valid package names.
+ *
+ * **Note**: Does **not** match specifiers beginning with `'node_modules'`.
+ *
+ * @see https://regex101.com/r/z0MPgj
+ *
+ * @const {RegExp} PACKAGE_PATH_REGEX
+ */
+const PACKAGE_PATH_REGEX: RegExp =
+  /^(?!\S+:|node_modules)(?<pkg>(?:(?:(?<scope>@[\d*a-z~-][\w*.~-]*)\/)?[\da-z~-][\w.~-]*))@?(?<version_prefix>v)?(?<version>(?:(?:0|[1-9]\d*)\.){2}(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[a-z-][\da-z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-z-][\da-z-]*))*)?(?:\+[\da-z-]+(?:\.[\da-z-]+)*)?)?(?<subpath>\/.*)?(?<!.*(?:%2[Ff]|%5[Cc]))/
+
+export default PACKAGE_PATH_REGEX