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

package/src/interfaces/options-find-subpath.ts

@@ -0,0 +1,56 @@
+/**
+ * @file Interfaces - FindSubpathOptions
+ * @module mlly/interfaces/FindSubpathOptions
+ */
+
+import type { ModuleId } from '#src/types'
+
+/**
+ * Subpath search options.
+ *
+ * @see {@linkcode ModuleId}
+ */
+interface FindSubpathOptions {
+  /**
+   * Export condition to apply.
+   *
+   * @see https://nodejs.org/api/packages.html#conditional-exports
+   *
+   * @default 'default'
+   */
+  condition?: string | undefined
+
+  /**
+   * Export conditions.
+   *
+   * **Note**: Should be sorted by priority.
+   *
+   * @see https://nodejs.org/api/packages.html#conditional-exports
+   *
+   * @default CONDITIONS
+   */
+  conditions?: Set<string> | undefined
+
+  /**
+   * URL of directory containing relevant `package.json` file.
+   */
+  dir: ModuleId
+
+  /**
+   * Package [`imports`][1] hint.
+   *
+   * [1]: https://nodejs.org/api/packages.html#imports
+   *
+   * @default false
+   */
+  internal?: boolean | undefined
+
+  /**
+   * URL of module to resolve from.
+   *
+   * **Note**: Used for error reporting only.
+   */
+  parent: ModuleId
+}
+
+export type { FindSubpathOptions as default }

package/src/interfaces/options-get-format.ts

@@ -0,0 +1,92 @@
+/**
+ * @file Interfaces - GetFormatOptions
+ * @module mlly/interfaces/GetFormatOptions
+ */
+
+import type { Format } from '#src/enums'
+import type { ModuleId } from '#src/types'
+import type { Ext } from '@flex-development/pathe'
+import type { EmptyString } from '@flex-development/tutils'
+import type { RequestInit } from 'node-fetch'
+
+/**
+ * Module format retrieval options.
+ *
+ * @see {@linkcode Ext}
+ * @see {@linkcode Format}
+ * @see {@linkcode ModuleId}
+ * @see {@linkcode RequestInit}
+ */
+interface GetFormatOptions {
+  /**
+   * Base URL to resolve module id against if module id is not absolute.
+   *
+   * @see {@linkcode ModuleId}
+   *
+   * @default undefined
+   */
+  base?: ModuleId | undefined
+
+  /**
+   * Enable support for JSON modules.
+   *
+   * @see https://nodejs.org/docs/latest-v14.x/api/esm.html#esm_json_modules
+   *
+   * @default true
+   */
+  experimental_json_modules?: boolean | undefined
+
+  /**
+   * Enable support for network based modules.
+   *
+   * **Note**: Requires [`node-fetch`][1].
+   *
+   * [1]: https://github.com/node-fetch/node-fetch
+   *
+   * @see https://nodejs.org/docs/latest-v16.x/api/esm.html#https-and-http-imports
+   *
+   * @default false
+   */
+  experimental_network_imports?: boolean | undefined
+
+  /**
+   * Enable support for WebAssembly modules.
+   *
+   * @see https://nodejs.org/docs/latest-v14.x/api/esm.html#esm_wasm_modules
+   *
+   * @default false
+   */
+  experimental_wasm_modules?: boolean | undefined
+
+  /**
+   * Map file extensions to module formats.
+   *
+   * @default EXTENSION_FORMAT_MAP
+   */
+  extension_format_map?: Map<EmptyString | Ext, Format> | undefined
+
+  /**
+   * Return `undefined` when module format is not found, rather than `null`.
+   *
+   * An explicit `undefined` return value indicates [`load`][1] hooks should
+   * re-run module format checks.
+   *
+   * [1]: https://nodejs.org/docs/latest-v16.x/api/esm.html#loadurl-context-nextload
+   *
+   * @default false
+   */
+  ignore_errors?: boolean | undefined
+
+  /**
+   * Request options for network based modules.
+   *
+   * Only applicable if {@linkcode experimental_network_imports} is enabled.
+   *
+   * @see {@linkcode RequestInit}
+   *
+   * @default undefined
+   */
+  req?: RequestInit | undefined
+}
+
+export type { GetFormatOptions as default }

package/src/interfaces/options-get-source.ts

@@ -0,0 +1,70 @@
+/**
+ * @file Interfaces - GetSourceOptions
+ * @module mlly/interfaces/GetSourceOptions
+ */
+
+import type { Format } from '#src/enums'
+import type { ModuleId } from '#src/types'
+import type { RequestInit } from 'node-fetch'
+
+/**
+ * Source code retrieval options.
+ *
+ * @see {@linkcode Format}
+ * @see {@linkcode ModuleId}
+ * @see {@linkcode RequestInit}
+ */
+interface GetSourceOptions {
+  /**
+   * Base URL to resolve module id against if module id is not absolute.
+   *
+   * @see {@linkcode ModuleId}
+   *
+   * @default undefined
+   */
+  base?: ModuleId | undefined
+
+  /**
+   * Enable support for network based modules.
+   *
+   * **Note**: Requires [`node-fetch`][1].
+   *
+   * [1]: https://github.com/node-fetch/node-fetch
+   *
+   * @see https://nodejs.org/docs/latest-v16.x/api/esm.html#https-and-http-imports
+   *
+   * @default false
+   */
+  experimental_network_imports?: boolean | undefined
+
+  /**
+   * Module format hint.
+   *
+   * @see {@linkcode Format}
+   *
+   * @default undefined
+   */
+  format?: Format | Lowercase<keyof typeof Format> | undefined
+
+  /**
+   * Ignore [`ERR_UNSUPPORTED_ESM_URL_SCHEME`][1] if thrown.
+   *
+   * [1]: https://nodejs.org/api/errors.html#err_unsupported_esm_url_scheme
+   *
+   * @default false
+   */
+  ignore_errors?: boolean | undefined
+
+  /**
+   * Request options for network based modules.
+   *
+   * Only applicable if {@linkcode experimental_network_imports} is enabled.
+   *
+   * @see {@linkcode RequestInit}
+   *
+   * @default undefined
+   */
+  req?: RequestInit | undefined
+}
+
+export type { GetSourceOptions as default }

package/src/interfaces/options-parse-module-id.ts

@@ -0,0 +1,38 @@
+/**
+ * @file Interfaces - ParseModuleIdOptions
+ * @module mlly/interfaces/ParseModuleIdOptions
+ */
+
+import type { ModuleId } from '#src/types'
+
+/**
+ * Module id parsing options.
+ *
+ * @see {@linkcode ModuleId}
+ */
+interface ParseModuleIdOptions {
+  /**
+   * Ensure module id is a valid internal specifier, syntactically.
+   *
+   * @see https://nodejs.org/api/packages.html#subpath-imports
+   *
+   * @default id instanceof URL ? false : id.startsWith('#')
+   */
+  internal?: boolean | undefined
+
+  /**
+   * URL of module to resolve from.
+   *
+   * **Note**: Used for error reporting only.
+   *
+   * @default undefined
+   */
+  parent?: ModuleId | undefined
+
+  /**
+   * Ensure module id begins with a valid package name.
+   */
+  pkgname?: boolean | undefined
+}
+
+export type { ParseModuleIdOptions as default }

package/src/interfaces/options-parse-subpath.ts

@@ -0,0 +1,36 @@
+/**
+ * @file Interfaces - ParseSubpathOptions
+ * @module mlly/interfaces/ParseSubpathOptions
+ */
+
+import type { ModuleId } from '#src/types'
+
+/**
+ * Subpath parsing options.
+ *
+ * @see {@linkcode ModuleId}
+ */
+interface ParseSubpathOptions {
+  /**
+   * URL of directory containing relevant `package.json` file.
+   */
+  dir: ModuleId
+
+  /**
+   * Package [`imports`][1] hint.
+   *
+   * [1]: https://nodejs.org/api/packages.html#imports
+   *
+   * @default specifier.startsWith('#')
+   */
+  internal?: boolean | undefined
+
+  /**
+   * URL of module to resolve from.
+   *
+   * **Note**: Used for error reporting only.
+   */
+  parent: ModuleId
+}
+
+export type { ParseSubpathOptions as default }

package/src/interfaces/options-resolve-alias.ts

@@ -0,0 +1,59 @@
+/**
+ * @file Interfaces - ResolveAliasOptions
+ * @module mlly/interfaces/ResolveAliasOptions
+ */
+
+import type { ModuleId } from '#src/types'
+import type { MapLike, OneOrMany } from '@flex-development/tutils'
+import type ResolveModuleOptions from './options-resolve-module'
+
+/**
+ * Path alias resolution options.
+ *
+ * @see {@linkcode ModuleId}
+ *
+ * @extends {ResolveModuleOptions}
+ */
+interface ResolveAliasOptions extends ResolveModuleOptions {
+  /**
+   * Return resolved module URL as absolute specifier (a [`file:` URL][1]).
+   *
+   * If `false`, return resolved module URL as bare or relative specifier.
+   *
+   * [1]: https://nodejs.org/api/esm.html#file-urls
+   *
+   * @see https://nodejs.org/api/esm.html#terminology
+   *
+   * @default true
+   */
+  absolute?: boolean | undefined
+
+  /**
+   * Path mappings.
+   *
+   * **Note**: Paths should be relative to {@linkcode cwd}.
+   *
+   * @default {}
+   */
+  aliases?: MapLike<OneOrMany<string>> | undefined
+
+  /**
+   * Directory to resolve non-absolute modules from.
+   *
+   * @default pathToFileURL('.')
+   */
+  cwd?: ModuleId | undefined
+
+  /**
+   * Id of module to resolve from.
+   *
+   * **Note**: Should be an absolute path or [`file:` URL][1].
+   *
+   * [1]: https://nodejs.org/api/esm.html#file-urls
+   *
+   * @default import.meta.url
+   */
+  parent?: ModuleId | undefined
+}
+
+export type { ResolveAliasOptions as default }

package/src/interfaces/options-resolve-module.ts

@@ -0,0 +1,72 @@
+/**
+ * @file Interfaces - ResolveModuleOptions
+ * @module mlly/interfaces/ResolveModuleOptions
+ */
+
+import type { ChangeExtFn, ModuleId } from '#src/types'
+import type { Nilable } from '@flex-development/tutils'
+
+/**
+ * Module resolution options.
+ *
+ * @see {@linkcode ChangeExtFn}
+ * @see {@linkcode ModuleId}
+ */
+interface ResolveModuleOptions {
+  /**
+   * Export condition to apply.
+   *
+   * @see https://nodejs.org/api/packages.html#conditional-exports
+   *
+   * @default 'default'
+   */
+  condition?: string | undefined
+
+  /**
+   * Export conditions.
+   *
+   * **Note**: Should be sorted by priority.
+   *
+   * @see https://nodejs.org/api/packages.html#conditional-exports
+   *
+   * @default CONDITIONS
+   */
+  conditions?: Set<string> | string[] | undefined
+
+  /**
+   * Replacement file extension or function that returns a file extension.
+   *
+   * An empty string (`''`) will remove a file extension; `null` or `undefined`
+   * will skip extension replacement.
+   *
+   * @default undefined
+   */
+  ext?: ChangeExtFn | Nilable<string>
+
+  /**
+   * Module extensions to probe for.
+   *
+   * **Note**: Should be sorted by priority.
+   *
+   * @default RESOLVE_EXTENSIONS
+   */
+  extensions?: Set<string> | string[] | undefined
+
+  /**
+   * URL of module to resolve from.
+   *
+   * @see {@linkcode ModuleId}
+   *
+   * @default import.meta.url
+   */
+  parent?: ModuleId | undefined
+
+  /**
+   * Keep symlinks instead of resolving them.
+   *
+   * @default false
+   */
+  preserveSymlinks?: boolean | undefined
+}
+
+export type { ResolveModuleOptions as default }

package/src/interfaces/options-resolve.ts

@@ -0,0 +1,17 @@
+/**
+ * @file Interfaces - ResolveOptions
+ * @module mlly/interfaces/ResolveOptions
+ */
+
+import type ResolveModuleOptions from './options-resolve-module'
+
+/**
+ * Resolution options.
+ *
+ * @see {@linkcode ResolveModuleOptions}
+ *
+ * @extends {ResolveModuleOptions}
+ */
+interface ResolveOptions extends ResolveModuleOptions {}
+
+export type { ResolveOptions as default }

package/src/interfaces/package-scope.ts

@@ -0,0 +1,30 @@
+/**
+ * @file Interfaces - PackageScope
+ * @module mlly/interfaces/PackageScope
+ */
+
+import type { PackageJson } from '@flex-development/pkg-types'
+
+/**
+ * Object representing a package scope.
+ *
+ * @see {@linkcode PackageJson}
+ */
+interface PackageScope {
+  /**
+   * URL of directory containing `package.json` file.
+   */
+  dir: string
+
+  /**
+   * URL of `package.json` file.
+   */
+  pkg: string
+
+  /**
+   * `package.json` object.
+   */
+  pkgjson: PackageJson
+}
+
+export type { PackageScope as default }

package/src/interfaces/parsed-data-url.ts

@@ -0,0 +1,63 @@
+/**
+ * @file Interfaces - ParsedDataUrl
+ * @module mlly/interfaces/ParsedDataUrl
+ */
+
+import type { MimeType, Protocol } from '#src/types'
+import type { EmptyString, LiteralUnion } from '@flex-development/tutils'
+import type { URL } from 'node:url'
+
+/**
+ * Object representing a [`data:` URL][1].
+ *
+ * [1]: https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs
+ *
+ * @see {@linkcode Protocol}
+ * @see {@linkcode MimeType}
+ * @see https://nodejs.org/api/esm.html#data-imports
+ */
+interface ParsedDataUrl {
+  /**
+   * [base64][1] encoding check.
+   *
+   * [1]: https://developer.mozilla.org/docs/Glossary/Base64
+   */
+  base64: boolean
+
+  /**
+   * Data portion of URL.
+   *
+   * If {@linkcode base64} is `true`, `data` is base64-encoded.
+   */
+  data: LiteralUnion<EmptyString, string>
+
+  /**
+   * Serialized `data:` URL.
+   *
+   * @see https://nodejs.org/api/url.html#urlhref
+   */
+  href: URL['href']
+
+  /**
+   * MIME type.
+   *
+   * @see https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/MIME_types
+   */
+  mime: LiteralUnion<MimeType, string>
+
+  /**
+   * Path portion of URL.
+   *
+   * @see https://nodejs.org/api/url.html#urlpathname
+   */
+  pathname: URL['pathname']
+
+  /**
+   * Protocol portion of URL.
+   *
+   * @see https://nodejs.org/api/url.html#urlprotocol
+   */
+  protocol: Extract<Protocol, 'data:'>
+}
+
+export type { ParsedDataUrl as default }

package/src/interfaces/parsed-module-id.ts

@@ -0,0 +1,90 @@
+/**
+ * @file Interfaces - ParsedModuleId
+ * @module mlly/interfaces/ParsedModuleId
+ */
+
+import type { Protocol } from '#src/types'
+import type { SemanticVersion } from '@flex-development/pkg-types'
+import type { EmptyString, LiteralUnion } from '@flex-development/tutils'
+
+/**
+ * Object representing a ECMAScript module id.
+ *
+ * @see {@linkcode Protocol}
+ * @see {@linkcode SemanticVersion}
+ */
+interface ParsedModuleId {
+  /**
+   * Subpath import (internal specifier) check.
+   *
+   * @see https://nodejs.org/api/packages.html#imports
+   * @see https://nodejs.org/api/packages.html#subpath-imports
+   */
+  internal: boolean
+
+  /**
+   * One of the following:
+   *
+   * - Possible [subpath export][1] (includes leading `'.'`)
+   * - Possible [subpath import][2]
+   * - URL [`host`][3], [`pathname`][4], and [`port`][5]
+   * - Raw module id ({@linkcode raw})
+   *
+   * [1]: https://nodejs.org/api/packages.html#subpath-exports
+   * [2]: https://nodejs.org/api/packages.html#subpath-imports
+   * [3]: https://nodejs.org/api/url.html#urlhost
+   * [4]: https://nodejs.org/api/url.html#urlpathname
+   * [5]: https://nodejs.org/api/url.html#urlport
+   */
+  path: string
+
+  /**
+   * Package name if module id begins with valid package name (e.g. is a [bare
+   * specifier][1]).
+   *
+   * If the module id is a bare specifier *and* [internal][2], this value will
+   * instead be the first path segement in the module id (i.e. `'#src'` given
+   * `'#src/foo'`). This **may or may not** be the subpath defined by the
+   * package maintainer.
+   *
+   * [1]: https://nodejs.org/api/esm.html#terminology
+   * [2]: https://nodejs.org/api/packages.html#subpath-imports
+   */
+  pkg: LiteralUnion<EmptyString, string>
+
+  /**
+   * URL scheme if module id is a URL.
+   */
+  protocol: LiteralUnion<EmptyString | Protocol, string>
+
+  /**
+   * Raw module id.
+   */
+  raw: string
+
+  /**
+   * Package scope if module id begins with valid package name (e.g. is a [bare
+   * specifier][1]).
+   *
+   * [1]: https://nodejs.org/api/esm.html#terminology
+   */
+  scope: LiteralUnion<EmptyString, string>
+
+  /**
+   * Package version if specified and module id begins with valid package name
+   * (e.g. is a [bare specifier][1]).
+   *
+   * **Note**: Version follows [Semantic Versioning 2.0.0][2] specification.
+   *
+   * [1]: https://nodejs.org/api/esm.html#terminology
+   * [2]: https://semver.org/spec/v2.0.0.html
+   */
+  version: LiteralUnion<EmptyString | SemanticVersion, string>
+
+  /**
+   * Package {@linkcode version} prefix.
+   */
+  version_prefix: LiteralUnion<EmptyString | 'v', string>
+}
+
+export type { ParsedModuleId as default }

package/src/interfaces/parsed-subpath.ts

@@ -0,0 +1,47 @@
+/**
+ * @file Interfaces - ParsedSubpath
+ * @module mlly/interfaces/ParsedSubpath
+ */
+
+import type { EmptyString, LiteralUnion } from '@flex-development/tutils'
+
+/**
+ * Object representing a package subpath.
+ *
+ * @see https://nodejs.org/api/packages.html#subpath-exports
+ * @see https://nodejs.org/api/packages.html#subpath-imports
+ */
+interface ParsedSubpath {
+  /**
+   * Subpath without entry prefix ({@linkcode key}).
+   */
+  base: LiteralUnion<EmptyString, string>
+
+  /**
+   * Subpath import check.
+   *
+   * @see https://nodejs.org/api/packages.html#imports
+   * @see https://nodejs.org/api/packages.html#subpath-imports
+   */
+  internal: boolean
+
+  /**
+   * Subpath defined in `package.json` file.
+   *
+   * @see https://nodejs.org/api/packages.html#exports
+   * @see https://nodejs.org/api/packages.html#imports
+   */
+  key: string
+
+  /**
+   * Subpath passed by user in module specifier.
+   */
+  raw: string
+
+  /**
+   * Module specifier passed by user.
+   */
+  specifier: string
+}
+
+export type { ParsedSubpath as default }