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

package/src/internal/validate-boolean.ts

@@ -0,0 +1,27 @@
+/**
+ * @file Internal - validateBoolean
+ * @module mlly/internal/validateBoolean
+ */
+
+import { ERR_INVALID_ARG_TYPE, type NodeError } from '@flex-development/errnode'
+
+/**
+ * Checks if given `value` is a boolean.
+ *
+ * Throws [`ERR_INVALID_ARG_TYPE`][1] if the `value` is not a boolean.
+ *
+ * [1]: https://nodejs.org/api/errors.html#err_invalid_arg_value
+ *
+ * @see {@linkcode ERR_INVALID_ARG_TYPE}
+ *
+ * @param {unknown} value - Value supplied by user
+ * @param {string} name - Name of invalid argument or property
+ * @return {value is boolean} `true` if `value` is a boolean
+ * @throws {NodeError<TypeError>} If `value` is not a boolean
+ */
+const validateBoolean = (value: unknown, name: string): value is boolean => {
+  if (typeof value === 'boolean') return true
+  throw new ERR_INVALID_ARG_TYPE(name, 'boolean', value)
+}
+
+export default validateBoolean

package/src/internal/validate-object.ts

@@ -0,0 +1,30 @@
+/**
+ * @file Internal - validateObject
+ * @module mlly/internal/validateObject
+ */
+
+import { ERR_INVALID_ARG_TYPE, type NodeError } from '@flex-development/errnode'
+import type { ObjectPlain } from '@flex-development/tutils'
+
+/**
+ * Checks if given `value` is an object.
+ *
+ * **Note**: Array values are not considered objects.
+ *
+ * Throws [`ERR_INVALID_ARG_TYPE`][1] if the `value` is not an object.
+ *
+ * [1]: https://nodejs.org/api/errors.html#err_invalid_arg_value
+ *
+ * @see {@linkcode ERR_INVALID_ARG_TYPE}
+ *
+ * @param {unknown} value - Value supplied by user
+ * @param {string} name - Name of invalid argument or property
+ * @return {value is ObjectPlain} `true` if `value` is an object
+ * @throws {NodeError<TypeError>} If `value` is not an object
+ */
+const validateObject = (value: unknown, name: string): value is ObjectPlain => {
+  if (typeof value === 'object' && value && !Array.isArray(value)) return true
+  throw new ERR_INVALID_ARG_TYPE(name, 'object', value)
+}
+
+export default validateObject

package/src/internal/validate-set.ts

@@ -0,0 +1,33 @@
+/**
+ * @file Internal - validateSet
+ * @module mlly/internal/validateSet
+ */
+
+import { ERR_INVALID_ARG_TYPE, type NodeError } from '@flex-development/errnode'
+
+/**
+ * Checks if given `value` is an instance of {@linkcode Set}.
+ *
+ * Throws [`ERR_INVALID_ARG_TYPE`][1] if the `value` is not a {@linkcode Set}
+ * instance.
+ *
+ * [1]: https://nodejs.org/api/errors.html#err_invalid_arg_value
+ *
+ * @see {@linkcode ERR_INVALID_ARG_TYPE}
+ *
+ * @template T - Item type(s)
+ *
+ * @param {unknown} value - Value supplied by user
+ * @param {string} name - Name of invalid argument or property
+ * @return {value is Set} `true` if `value` is instance of {@linkcode Set}
+ * @throws {NodeError<TypeError>} If `value` is an instance of {@linkcode Set}
+ */
+function validateSet<T = unknown>(
+  value: unknown,
+  name: string
+): value is Set<T> {
+  if (value instanceof Set) return true
+  throw new ERR_INVALID_ARG_TYPE(name, ['Set'], value)
+}
+
+export default validateSet

package/src/internal/validate-string.ts

@@ -0,0 +1,27 @@
+/**
+ * @file Internal - validateString
+ * @module mlly/internal/validateString
+ */
+
+import { ERR_INVALID_ARG_TYPE, type NodeError } from '@flex-development/errnode'
+
+/**
+ * Checks if given `value` is a string.
+ *
+ * Throws [`ERR_INVALID_ARG_TYPE`][1] if the `value` is not a string.
+ *
+ * [1]: https://nodejs.org/api/errors.html#err_invalid_arg_value
+ *
+ * @see {@linkcode ERR_INVALID_ARG_TYPE}
+ *
+ * @param {unknown} value - Value supplied by user
+ * @param {string} name - Name of invalid argument or property
+ * @return {value is string} `true` if `value` is a string
+ * @throws {NodeError<TypeError>} If `value` is not a string
+ */
+const validateString = (value: unknown, name: string): value is string => {
+  if (typeof value === 'string') return true
+  throw new ERR_INVALID_ARG_TYPE(name, 'string', value)
+}
+
+export default validateString

package/src/internal/validate-url-string.ts

@@ -0,0 +1,31 @@
+/**
+ * @file Internal - validateURLString
+ * @module mlly/internal/validateURLString
+ */
+
+import { ERR_INVALID_ARG_TYPE, type NodeError } from '@flex-development/errnode'
+import { URL } from 'node:url'
+
+/**
+ * Checks if given `value` is an instance of {@linkcode URL} or a string.
+ *
+ * Throws [`ERR_INVALID_ARG_TYPE`][1] if the `value` is of neither type.
+ *
+ * [1]: https://nodejs.org/api/errors.html#err_invalid_arg_value
+ *
+ * @see {@linkcode ERR_INVALID_ARG_TYPE}
+ *
+ * @param {unknown} value - Value supplied by user
+ * @param {string} name - Name of invalid argument or property
+ * @return {value is URL | string} `true` if `value` is `URL` instance or string
+ * @throws {NodeError<TypeError>} If `value` is not `URL` instance or string
+ */
+const validateURLString = (
+  value: unknown,
+  name: string
+): value is URL | string => {
+  if (value instanceof URL || typeof value === 'string') return true
+  throw new ERR_INVALID_ARG_TYPE(name, ['URL', 'string'], value)
+}
+
+export default validateURLString

package/src/types/declaration.ts

@@ -0,0 +1,22 @@
+/**
+ * @file Type Definitions - Declaration
+ * @module mlly/types/Declaration
+ */
+
+/**
+ * Export declaration kinds.
+ */
+type Declaration =
+  | 'class'
+  | 'const enum'
+  | 'const'
+  | 'enum'
+  | 'function'
+  | 'function*'
+  | 'interface'
+  | 'let'
+  | 'namespace'
+  | 'type'
+  | 'var'
+
+export type { Declaration as default }

package/src/types/fn-change-ext.ts

@@ -0,0 +1,33 @@
+/**
+ * @file Type Definitions - ChangeExtFn
+ * @module mlly/types/ChangeExtFn
+ */
+
+import type { Nilable } from '@flex-development/tutils'
+import type { URL } from 'node:url'
+
+/**
+ * Function that returns a new file extension for the given module `specifier`.
+ *
+ * Returning an empty string (`''`) will remove the original file extension;
+ * returning `null` or `undefined` will skip extension replacement.
+ *
+ * ::: info
+ * The new file extension need not begin with a dot character (`'.'`).
+ * :::
+ *
+ * @see {@linkcode URL}
+ * @see https://github.com/flex-development/pathe/tree/1.0.3#changeextpath-string-ext-nullablestring-string
+ *
+ * @template Ext - File extension type(s)
+ *
+ * @param {string} specifier - Original module specifier
+ * @param {URL} url - Resolved module URL
+ * @return {Ext | PromiseLike<Ext>} New file extension, `null`, or `undefined`
+ */
+type ChangeExtFn<Ext extends Nilable<string> = Nilable<string>> = (
+  specifier: string,
+  url: URL
+) => Ext | PromiseLike<Ext>
+
+export type { ChangeExtFn as default }

package/src/types/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @file Type Definitions
+ * @module mlly/types
+ */
+
+export type { default as Declaration } from './declaration'
+export type { default as ChangeExtFn } from './fn-change-ext'
+export type { default as MimeType } from './mime-type'
+export type { default as ModuleId } from './module-id'
+export type { default as ModuleSpecifierType } from './module-specifier-type'
+export type { default as Protocol } from './protocol'
+export type { default as SyntaxKindExport } from './syntax-kind-export'
+export type { default as SyntaxKindImport } from './syntax-kind-import'
+export type { default as SyntaxKindRequire } from './syntax-kind-require'

package/src/types/mime-type.ts

@@ -0,0 +1,19 @@
+/**
+ * @file Type Definitions - MimeType
+ * @module mlly/types/MimeType
+ */
+
+/**
+ * Supported [MIME types][1].
+ *
+ * [1]: https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/MIME_types
+ *
+ * @see https://nodejs.org/api/esm.html#esm_data_imports
+ */
+type MimeType =
+  | 'application/json'
+  | 'application/typescript'
+  | 'application/wasm'
+  | 'text/javascript'
+
+export type { MimeType as default }

package/src/types/module-id.ts

@@ -0,0 +1,15 @@
+/**
+ * @file Type Definitions - ModuleId
+ * @module mlly/types/ModuleId
+ */
+
+import type { URL } from 'node:url'
+
+/**
+ * ECMAScript (ES) module identifier.
+ *
+ * @see {@linkcode URL}
+ */
+type ModuleId = URL | string
+
+export type { ModuleId as default }

package/src/types/module-specifier-type.ts

@@ -0,0 +1,13 @@
+/**
+ * @file Type Definitions - ModuleSpecifierType
+ * @module mlly/types/ModuleSpecifierType
+ */
+
+/**
+ * Module specifier types.
+ *
+ * @see https://nodejs.org/api/esm.html#terminology
+ */
+type ModuleSpecifierType = 'absolute' | 'bare' | 'relative'
+
+export type { ModuleSpecifierType as default }

package/src/types/protocol.ts

@@ -0,0 +1,40 @@
+/**
+ * @file Type Definitions - Protocol
+ * @module mlly/types/Protocol
+ */
+
+import type { LiteralUnion } from '@flex-development/tutils'
+
+/**
+ * URL protocols.
+ *
+ * @see https://nodejs.org/api/url.html#urlprotocol
+ * @see https://iana.org/assignments/uri-schemes/uri-schemes.xhtml
+ * @see https://url.spec.whatwg.org/#special-scheme
+ */
+type Protocol = LiteralUnion<
+  `${
+    | 'blob'
+    | 'content'
+    | 'cvs'
+    | 'data'
+    | 'dns'
+    | 'file'
+    | 'fish'
+    | 'ftp'
+    | 'git'
+    | 'http'
+    | 'https'
+    | 'mvn'
+    | 'redis'
+    | 'sftp'
+    | 'ssh'
+    | 'svn'
+    | 'urn'
+    | 'view-source'
+    | 'ws'
+    | 'wss'}:`,
+  `${string}:`
+>
+
+export type { Protocol as default }

package/src/types/syntax-kind-export.ts

@@ -0,0 +1,20 @@
+/**
+ * @file Type Definitions - SyntaxKindExport
+ * @module mlly/types/SyntaxKindExport
+ */
+
+import type { StatementSyntaxKind } from '#src/enums'
+
+/**
+ * `export` statement syntax kinds.
+ *
+ * @see {@linkcode StatementSyntaxKind}
+ */
+type SyntaxKindExport =
+  | StatementSyntaxKind.DECLARATION
+  | StatementSyntaxKind.DEFAULT
+  | StatementSyntaxKind.LIST
+  | StatementSyntaxKind.NAMED
+  | StatementSyntaxKind.NAMESPACE
+
+export type { SyntaxKindExport as default }

package/src/types/syntax-kind-import.ts

@@ -0,0 +1,22 @@
+/**
+ * @file Type Definitions - SyntaxKindImport
+ * @module mlly/types/SyntaxKindImport
+ */
+
+import type { StatementSyntaxKind } from '#src/enums'
+
+/**
+ * `import` statement syntax kinds.
+ *
+ * @see {@linkcode StatementSyntaxKind}
+ */
+type SyntaxKindImport =
+  | StatementSyntaxKind.DEFAULT
+  | StatementSyntaxKind.DEFAULT_WITH_NAMED
+  | StatementSyntaxKind.DEFAULT_WITH_NAMESPACE
+  | StatementSyntaxKind.DYNAMIC
+  | StatementSyntaxKind.NAMED
+  | StatementSyntaxKind.NAMESPACE
+  | StatementSyntaxKind.SIDE_EFFECT
+
+export type { SyntaxKindImport as default }

package/src/types/syntax-kind-require.ts

@@ -0,0 +1,15 @@
+/**
+ * @file Type Definitions - SyntaxKindRequire
+ * @module mlly/types/SyntaxKindRequire
+ */
+
+import type { StatementSyntaxKind } from '#src/enums'
+
+/**
+ * `require` statement syntax kinds.
+ *
+ * @see {@linkcode StatementSyntaxKind}
+ */
+type SyntaxKindRequire = StatementSyntaxKind.REQUIRE
+
+export type { SyntaxKindRequire as default }

package/src/utils/compare-subpaths.ts

@@ -0,0 +1,100 @@
+/**
+ * @file compareSubpaths
+ * @module mlly/utils/compareSubpaths
+ */
+
+import validateString from '#src/internal/validate-string'
+import type { NodeError } from '@flex-development/errnode'
+import { CompareResult } from '@flex-development/tutils'
+import assert from 'node:assert'
+import PATTERN_CHARACTER from './pattern-character'
+
+/**
+ * Returns a number indicating if a subpath pattern is equal to, greater than,
+ * or less than another subpath pattern.
+ *
+ * - `-1`: `subpath2` is less than `subpath1`
+ * - `0`: `subpath2` is equal to `subpath1`
+ * - `1`: `subpath2` is greater than `subpath1`
+ *
+ * Implements the `PATTERN_KEY_COMPARE` algorithm.
+ *
+ * @see https://nodejs.org/api/esm.html#resolution-algorithm
+ *
+ * @param {string} subpath1 - Subpath to be compared
+ * @param {string} subpath2 - Subpath to compare `subpath1` to
+ * @return {CompareResult} Comparsion result
+ * @throws {NodeError<Error | TypeError>} If either either subpath contains more
+ * than pattern character (`'*'`) or is not a string
+ */
+const compareSubpaths = (subpath1: string, subpath2: string): CompareResult => {
+  validateString(subpath1, 'subpath1')
+  validateString(subpath2, 'subpath2')
+
+  /**
+   * Index of {@linkcode pattern_char} in {@linkcode subpath1}.
+   *
+   * @const {number} pattern1
+   */
+  let pattern1: number = -1
+
+  /**
+   * Index of {@linkcode pattern_char} in {@linkcode subpath2}.
+   *
+   * @const {number} pattern2
+   */
+  let pattern2: number = -1
+
+  // ensure subpaths contain a single '*'
+  for (const [index, subpath] of [subpath1, subpath2].entries()) {
+    /**
+     * Error message thrown if {@linkcode subpath} contains more than one `'*'`.
+     *
+     * @const {string} message
+     */
+    const message: string = `'${subpath}' is expected to contain a single '*'`
+
+    /**
+     * Index of {@linkcode PATTERN_CHARACTER} in {@linkcode subpath}.
+     *
+     * @const {number} pattern
+     */
+    const pattern_index: number = subpath.indexOf(PATTERN_CHARACTER)
+
+    // ensure respective subpath contains no more than one '*'
+    assert(pattern_index === subpath.lastIndexOf(PATTERN_CHARACTER), message)
+
+    // set index of pattern character in respective subpath
+    index === 0 ? (pattern1 = pattern_index) : (pattern2 = pattern_index)
+  }
+
+  /**
+   * Base length of {@linkcode subpath1}.
+   *
+   * @const {number} length1
+   */
+  const length1: number = pattern1 === -1 ? subpath1.length : pattern1 + 1
+
+  /**
+   * Base length of {@linkcode subpath2}.
+   *
+   * @const {number} length2
+   */
+  const length2: number = pattern2 === -1 ? subpath2.length : pattern2 + 1
+
+  return length1 > length2
+    ? CompareResult.LESS_THAN
+    : length2 > length1
+    ? CompareResult.GREATER_THAN
+    : pattern1 === -1
+    ? CompareResult.GREATER_THAN
+    : pattern2 === -1
+    ? CompareResult.LESS_THAN
+    : subpath1.length > subpath2.length
+    ? CompareResult.LESS_THAN
+    : subpath2.length > subpath1.length
+    ? CompareResult.GREATER_THAN
+    : CompareResult.EQUAL
+}
+
+export default compareSubpaths

package/src/utils/conditions.ts

@@ -0,0 +1,15 @@
+/**
+ * @file CONDITIONS
+ * @module mlly/utils/CONDITIONS
+ */
+
+/**
+ * Default export conditions.
+ *
+ * @see https://nodejs.org/api/packages.html#conditional-exports
+ *
+ * @const {Set<string>} CONDITIONS
+ */
+const CONDITIONS: Set<string> = new Set(['node', 'import'])
+
+export default CONDITIONS

package/src/utils/detect-syntax.ts

@@ -0,0 +1,40 @@
+/**
+ * @file detectSyntax
+ * @module mlly/utils/detectSyntax
+ */
+
+import hasCJSSyntax from './has-cjs-syntax'
+import hasESMSyntax from './has-esm-syntax'
+
+/**
+ * Detects if `code` contains CommonJS syntax, ESM syntax, or a mixture of both.
+ *
+ * Ignores matches in comments.
+ *
+ * @see {@linkcode hasCJSSyntax}
+ * @see {@linkcode hasESMSyntax}
+ *
+ * @param {string} code - Code to evaluate
+ * @return {{ cjs: boolean; esm: boolean; mixed: boolean }} Detection result
+ */
+const detectSyntax = (
+  code: string
+): { cjs: boolean; esm: boolean; mixed: boolean } => {
+  /**
+   * CommonJS syntax check.
+   *
+   * @const {boolean} cjs
+   */
+  const cjs: boolean = hasCJSSyntax(code)
+
+  /**
+   * ESM syntax check.
+   *
+   * @const {boolean} esm
+   */
+  const esm: boolean = hasESMSyntax(code)
+
+  return { cjs, esm, mixed: cjs && esm }
+}
+
+export default detectSyntax

package/src/utils/extension-format-map.ts

@@ -0,0 +1,34 @@
+/**
+ * @file EXTENSION_FORMAT_MAP
+ * @module mlly/utils/EXTENSION_FORMAT_MAP
+ */
+
+import { Format } from '#src/enums'
+import type { Ext } from '@flex-development/pathe'
+
+/**
+ * Default file extension to module formats map.
+ *
+ * @see {@linkcode Ext}
+ * @see {@linkcode Format}
+ *
+ * @const {Map<Ext, Format>} EXTENSION_FORMAT_MAP
+ */
+const EXTENSION_FORMAT_MAP: Map<Ext, Format> = new Map<Ext, Format>([
+  ['.cjs', Format.COMMONJS],
+  ['.cts', Format.COMMONJS],
+  ['.d.cts', Format.COMMONJS],
+  ['.d.mts', Format.MODULE],
+  ['.d.ts', Format.MODULE],
+  ['.js', Format.MODULE],
+  ['.json', Format.JSON],
+  ['.jsx', Format.MODULE],
+  ['.mjs', Format.MODULE],
+  ['.mts', Format.MODULE],
+  ['.node', Format.COMMONJS],
+  ['.ts', Format.MODULE],
+  ['.tsx', Format.MODULE],
+  ['.wasm', Format.WASM]
+])
+
+export default EXTENSION_FORMAT_MAP

package/src/utils/extract-statements.ts

@@ -0,0 +1,42 @@
+/**
+ * @file extractStatements
+ * @module mlly/utils/extractStatements
+ */
+
+import type { Statement } from '#src/interfaces'
+import validateString from '#src/internal/validate-string'
+import type { NodeError } from '@flex-development/errnode'
+import findDynamicImports from './find-dynamic-imports'
+import findExports from './find-exports'
+import findRequires from './find-requires'
+import findStaticImports from './find-static-imports'
+
+/**
+ * Finds all `export`, `import`, and/or  `require` statements in `code`.
+ *
+ * Ignores matches in comments.
+ *
+ * @see {@linkcode findDynamicImports}
+ * @see {@linkcode findExports}
+ * @see {@linkcode findRequires}
+ * @see {@linkcode findStaticImports}
+ *
+ * @param {string} [code=''] - Code to evaluate
+ * @return {Statement[]} Extracted statements
+ * @throws {NodeError<TypeError>} If `code` is not a string
+ */
+const extractStatements = (code: string = ''): Statement[] => {
+  validateString(code, 'code')
+
+  // code shorter than first shortest keyword => no possible matches
+  if (code.trim().length < 'export'.length) return []
+
+  return [
+    ...findDynamicImports(code),
+    ...findExports(code),
+    ...findRequires(code),
+    ...findStaticImports(code)
+  ]
+}
+
+export default extractStatements