@flex-development/mlly 1.0.0-alpha.9 → 1.0.0-beta.2

package/dist/index.d.mts

@@ -2,7 +2,6 @@
  * @file Package Entry Point
  * @module mlly
  */
-export * from './enums/index.mjs';
-export * from './interfaces/index.mjs';
-export * from './types/index.mjs';
-export * from './utils/index.mjs';
+export type * from '#interfaces/index';
+export * from '#lib/index';
+export type * from '#types/index';

package/dist/index.mjs

@@ -1,5 +1,5 @@
-export * from "./enums/index.mjs";
-export * from "./interfaces/index.mjs";
-export * from "./types/index.mjs";
-export * from "./utils/index.mjs";
-//# sourceMappingURL=index.mjs.map
+/**
+ * @file Package Entry Point
+ * @module mlly
+ */
+export * from '#lib/index';

package/dist/interfaces/aliases.d.mts

@@ -0,0 +1,21 @@
+/**
+ * @file Interfaces - Aliases
+ * @module mlly/interfaces/Aliases
+ */
+/**
+ * Record, where each key is a path alias or pattern and each value
+ * is a path mapping configuration.
+ *
+ * This interface can be augmented to register custom aliases.
+ *
+ * @example
+ *  declare module '@flex-development/mlly' {
+ *    interface Aliases {
+ *      custom?: string[] | string | null
+ *    }
+ *  }
+ */
+interface Aliases {
+    [alias: string]: (string | null | undefined)[] | string | null | undefined;
+}
+export type { Aliases as default };

package/dist/interfaces/condition-map.d.mts

@@ -0,0 +1,24 @@
+/**
+ * @file Interfaces - ConditionMap
+ * @module mlly/interfaces/ConditionMap
+ */
+import type * as pkgTypes from '@flex-development/pkg-types';
+/**
+ * Registry of export/import conditions.
+ *
+ * This interface can be augmented to register custom conditions.
+ *
+ * @see {@linkcode pkgTypes.ConditionMap}
+ *
+ * @example
+ *  declare module '@flex-development/mlly' {
+ *    interface ConditionMap {
+ *      custom: 'custom'
+ *    }
+ *  }
+ *
+ * @extends {pkgTypes.ConditionMap}
+ */
+interface ConditionMap extends pkgTypes.ConditionMap {
+}
+export type { ConditionMap as default };

package/dist/interfaces/file-system.d.mts

@@ -0,0 +1,29 @@
+/**
+ * @file Interfaces - FileSystem
+ * @module mlly/interfaces/FileSystem
+ */
+import type { ReadFile, Realpath, Stat } from '@flex-development/mlly';
+/**
+ * The file system API.
+ */
+interface FileSystem {
+    /**
+     * Read the entire contents of a file.
+     *
+     * @see {@linkcode ReadFile}
+     */
+    readFile: ReadFile;
+    /**
+     * Compute a canonical pathname by resolving `.`, `..`, and symbolic links.
+     *
+     * @see {@linkcode Realpath}
+     */
+    realpath: Realpath;
+    /**
+     * Get information about a directory or file.
+     *
+     * @see {@linkcode Stat}
+     */
+    stat: Stat;
+}
+export type { FileSystem as default };

package/dist/interfaces/get-source-context.d.mts

@@ -0,0 +1,44 @@
+/**
+ * @file Interfaces - GetSourceContext
+ * @module mlly/interfaces/GetSourceContext
+ */
+import type { FileSystem, GetSourceHandlers, GetSourceOptions } from '@flex-development/mlly';
+/**
+ * Source code retrieval context.
+ *
+ * @see {@linkcode GetSourceOptions}
+ *
+ * @extends {GetSourceOptions}
+ */
+interface GetSourceContext extends GetSourceOptions {
+    /**
+     * The file system API.
+     *
+     * @see {@linkcode FileSystem}
+     *
+     * @override
+     */
+    fs: FileSystem;
+    /**
+     * Record, where each key is a URL protocol
+     * and each value is a source code handler.
+     *
+     * @see {@linkcode GetSourceHandlers}
+     *
+     * @override
+     */
+    handlers: GetSourceHandlers;
+    /**
+     * Request options for network based modules.
+     *
+     * @override
+     */
+    req: RequestInit;
+    /**
+     * The list of supported URL schemes.
+     *
+     * @override
+     */
+    schemes: Set<string>;
+}
+export type { GetSourceContext as default };

package/dist/interfaces/get-source-options.d.mts

@@ -0,0 +1,48 @@
+/**
+ * @file Interfaces - GetSourceOptions
+ * @module mlly/interfaces/GetSourceOptions
+ */
+import type { FileSystem, GetSourceHandlers, List, ModuleFormat } from '@flex-development/mlly';
+/**
+ * Options for retrieving source code.
+ */
+interface GetSourceOptions {
+    /**
+     * The module format hint.
+     *
+     * @see {@linkcode ModuleFormat}
+     */
+    format?: ModuleFormat | null | undefined;
+    /**
+     * The file system API.
+     *
+     * @see {@linkcode FileSystem}
+     */
+    fs?: FileSystem | null | undefined;
+    /**
+     * Record, where each key is a URL protocol
+     * and each value is a source code handler.
+     *
+     * @see {@linkcode GetSourceHandlers}
+     */
+    handlers?: GetSourceHandlers | null | undefined;
+    /**
+     * Whether to ignore [`ERR_UNSUPPORTED_ESM_URL_SCHEME`][err] if thrown.
+     *
+     * [err]: https://nodejs.org/api/errors.html#err_unsupported_esm_url_scheme
+     */
+    ignoreErrors?: boolean | null | undefined;
+    /**
+     * Request options for network based modules.
+     */
+    req?: RequestInit | null | undefined;
+    /**
+     * The list of supported URL schemes.
+     *
+     * @see {@linkcode List}
+     *
+     * @default ['data','file','http','https','node']
+     */
+    schemes?: List<string> | null | undefined;
+}
+export type { GetSourceOptions as default };

package/dist/interfaces/index.d.mts

@@ -1,24 +1,21 @@
 /**
- * @file Interfaces
+ * @file Entry Point - Interfaces
  * @module mlly/interfaces
  */
-export type { default as ImportAssertions } from './import-assertions.mjs';
-export type { default as DynamicImport } from './import-dynamic.mjs';
-export type { default as StaticImport } from './import-static.mjs';
-export type { default as FillModuleOptions } from './options-fill-module.mjs';
-export type { default as FindSubpathOptions } from './options-find-subpath.mjs';
-export type { default as GetFormatOptions } from './options-get-format.mjs';
-export type { default as GetSourceOptions } from './options-get-source.mjs';
-export type { default as ParseModuleIdOptions } from './options-parse-module-id.mjs';
-export type { default as ParseSubpathOptions } from './options-parse-subpath.mjs';
-export type { default as ResolveOptions } from './options-resolve.mjs';
-export type { default as ResolveAliasOptions } from './options-resolve-alias.mjs';
-export type { default as ResolveModuleOptions } from './options-resolve-module.mjs';
-export type { default as PackageScope } from './package-scope.mjs';
-export type { default as ParsedDataUrl } from './parsed-data-url.mjs';
-export type { default as ParsedModuleId } from './parsed-module-id.mjs';
-export type { default as ParsedSubpath } from './parsed-subpath.mjs';
-export type { default as Statement } from './statement.mjs';
-export type { default as ExportStatement } from './statement-export.mjs';
-export type { default as ImportStatement } from './statement-import.mjs';
-export type { default as RequireStatement } from './statement-require.mjs';
+export type { default as Aliases } from '#interfaces/aliases';
+export type { default as ConditionMap } from '#interfaces/condition-map';
+export type { default as FileSystem } from '#interfaces/file-system';
+export type { default as GetSourceContext } from '#interfaces/get-source-context';
+export type { default as GetSourceOptions } from '#interfaces/get-source-options';
+export type { default as IsDirectory } from '#interfaces/is-directory';
+export type { default as IsFile } from '#interfaces/is-file';
+export type { default as MainFieldMap } from '#interfaces/main-field-map';
+export type { default as ModuleFormatMap } from '#interfaces/module-format-map';
+export type { default as PatternKeyComparisonMap } from '#interfaces/pattern-key-comparison-map';
+export type { default as ProtocolMap } from '#interfaces/protocol-map';
+export type { default as ReadFile } from '#interfaces/read-file';
+export type { default as Realpath } from '#interfaces/realpath';
+export type { default as ResolveAliasOptions } from '#interfaces/resolve-alias-options';
+export type { default as ResolveModuleOptions } from '#interfaces/resolve-module-options';
+export type { default as Stat } from '#interfaces/stat';
+export type { default as Stats } from '#interfaces/stats';

package/dist/interfaces/is-directory.d.mts

@@ -0,0 +1,17 @@
+/**
+ * @file Interfaces - IsDirectory
+ * @module mlly/interfaces/IsDirectory
+ */
+/**
+ * Check if a stats object describes a directory.
+ */
+interface IsDirectory {
+    /**
+     * @this {void}
+     *
+     * @return {boolean}
+     *  `true` if stats describes directory, `false` otherwise
+     */
+    (this: void): boolean;
+}
+export type { IsDirectory as default };

package/dist/interfaces/is-file.d.mts

@@ -0,0 +1,17 @@
+/**
+ * @file Interfaces - IsFile
+ * @module mlly/interfaces/IsFile
+ */
+/**
+ * Check if a stats object describes a file.
+ */
+interface IsFile {
+    /**
+     * @this {void}
+     *
+     * @return {boolean}
+     *  `true` if stats object describes regular file, `false` otherwise
+     */
+    (this: void): boolean;
+}
+export type { IsFile as default };

package/dist/interfaces/main-field-map.d.mts

@@ -0,0 +1,22 @@
+/**
+ * @file Interfaces - MainFieldMap
+ * @module mlly/interfaces/MainFieldMap
+ */
+/**
+ * Registry of main fields.
+ *
+ * This interface can be augmented to register custom main fields.
+ *
+ * @example
+ *  declare module '@flex-development/mlly' {
+ *    interface MainFieldMap {
+ *      unpkg: 'unpkg'
+ *    }
+ *  }
+ */
+interface MainFieldMap {
+    main: 'main';
+    module: 'module';
+    types: 'types';
+}
+export type { MainFieldMap as default };

package/dist/interfaces/module-format-map.d.mts

@@ -0,0 +1,26 @@
+/**
+ * @file Interfaces - ModuleFormatMap
+ * @module mlly/interfaces/ModuleFormatMap
+ */
+/**
+ * Registry of module formats.
+ *
+ * This interface can be augmented to register custom module formats.
+ *
+ * @example
+ *  declare module '@flex-development/mlly' {
+ *    interface ModuleFormatMap {
+ *      custom: 'custom'
+ *    }
+ *  }
+ */
+interface ModuleFormatMap {
+    builtin: 'builtin';
+    commonjs: 'commonjs';
+    cts: 'commonjs-typescript';
+    json: 'json';
+    module: 'module';
+    mts: 'module-typescript';
+    wasm: 'wasm';
+}
+export type { ModuleFormatMap as default };

package/dist/interfaces/pattern-key-comparison-map.d.mts

@@ -0,0 +1,31 @@
+/**
+ * @file Interfaces - PatternKeyComparisonMap
+ * @module mlly/interfaces/PatternKeyComparisonMap
+ */
+/**
+ * Registry of `PATTERN_KEY_COMPARE` algorithm results.
+ *
+ * This interface can be augmented to register custom results.
+ *
+ * @example
+ *  declare module '@flex-development/mlly' {
+ *    interface PatternKeyComparisonMap {
+ *      afterThree: 3
+ *    }
+ *  }
+ */
+interface PatternKeyComparisonMap {
+    /**
+     * `a` should come after `b`.
+     */
+    after: 1;
+    /**
+     * `a` should come before `b`.
+     */
+    before: -1;
+    /**
+     * `a` and `b` are equal.
+     */
+    equal: 0;
+}
+export type { PatternKeyComparisonMap as default };

package/dist/interfaces/protocol-map.d.mts

@@ -0,0 +1,44 @@
+/**
+ * @file Interfaces - ProtocolMap
+ * @module mlly/interfaces/ProtocolMap
+ */
+/**
+ * Registry of URL protocols.
+ *
+ * This interface can be augmented to register custom 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
+ *
+ * @example
+ *  declare module '@flex-development/mlly' {
+ *    interface ProtocolMap {
+ *      custom: 'custom:'
+ *    }
+ *  }
+ */
+interface ProtocolMap {
+    blob: 'blob:';
+    content: 'content:';
+    cvs: 'cvs:';
+    data: 'data:';
+    dns: 'dns:';
+    file: 'file:';
+    fish: 'fish:';
+    ftp: 'ftp:';
+    git: 'git:';
+    http: 'http:';
+    https: 'https:';
+    mvn: 'mvn:';
+    node: 'node:';
+    redis: 'redis:';
+    sftp: 'sftp:';
+    ssh: 'ssh:';
+    svn: 'svn:';
+    urn: 'urn:';
+    viewSource: 'view-source:';
+    ws: 'ws:';
+    wss: 'wss:';
+}
+export type { ProtocolMap as default };

package/dist/interfaces/read-file.d.mts

@@ -0,0 +1,28 @@
+/**
+ * @file Interfaces - ReadFile
+ * @module mlly/interfaces/ReadFile
+ */
+import type { Awaitable, ModuleId } from '@flex-development/mlly';
+/**
+ * Read the entire contents of a file.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode Buffer}
+ *
+ * @template {Awaitable<Buffer | string>} [T]
+ *  The file contents
+ */
+interface ReadFile<T extends Awaitable<Buffer | string> = Awaitable<Buffer | string>> {
+    /**
+     * @see {@linkcode ModuleId}
+     *
+     * @this {void}
+     *
+     * @param {ModuleId} id
+     *  The module id
+     * @return {T}
+     *  The file contents
+     */
+    (this: void, id: ModuleId): T;
+}
+export type { ReadFile as default };

package/dist/interfaces/realpath.d.mts

@@ -0,0 +1,30 @@
+/**
+ * @file Interfaces - Realpath
+ * @module mlly/interfaces/Realpath
+ */
+import type { Awaitable, ModuleId } from '@flex-development/mlly';
+/**
+ * Compute a canonical pathname by resolving `.`, `..`, and symbolic links.
+ *
+ * > 👉 **Note**: A canonical pathname is not necessarily unique.
+ * > Hard links and bind mounts can expose an entity through many pathnames.
+ *
+ * @see {@linkcode Awaitable}
+ *
+ * @template {Awaitable<string>} [T]
+ *  The canonical pathname
+ */
+interface Realpath<T extends Awaitable<string> = Awaitable<string>> {
+    /**
+     * @see {@linkcode ModuleId}
+     *
+     * @this {void}
+     *
+     * @param {ModuleId} id
+     *  The module id
+     * @return {T}
+     *  The canonical pathname
+     */
+    (this: void, id: ModuleId): T;
+}
+export type { Realpath as default };

package/dist/interfaces/resolve-alias-options.d.mts

@@ -0,0 +1,43 @@
+/**
+ * @file Interfaces - ResolveAliasOptions
+ * @module mlly/interfaces/ResolveAliasOptions
+ */
+import type { Aliases, ModuleId } from '@flex-development/mlly';
+/**
+ * Options for path alias resolution.
+ */
+interface ResolveAliasOptions {
+    /**
+     * Whether the resolved specifier should be absolute.
+     *
+     * If `true`, the resolved specifier will be a [`file:` URL][file-url].
+     *
+     * [file-url]: https://nodejs.org/api/esm.html#file-urls
+     *
+     * @see https://nodejs.org/api/esm.html#terminology
+     */
+    absolute?: boolean | null | undefined;
+    /**
+     * The path mappings dictionary.
+     *
+     * > 👉 **Note**: Paths should be relative to {@linkcode cwd}.
+     *
+     * @see {@linkcode Aliases}
+     */
+    aliases?: Aliases | null | undefined;
+    /**
+     * The URL of the directory to resolve non-absolute modules from.
+     *
+     * @see {@linkcode ModuleId}
+     *
+     * @default cwd()
+     */
+    cwd?: ModuleId | null | undefined;
+    /**
+     * The URL of the parent module.
+     *
+     * @see {@linkcode ModuleId}
+     */
+    parent?: ModuleId | null | undefined;
+}
+export type { ResolveAliasOptions as default };

package/dist/interfaces/resolve-module-options.d.mts

@@ -0,0 +1,79 @@
+/**
+ * @file Interfaces - ResolveModuleOptions
+ * @module mlly/interfaces/ResolveModuleOptions
+ */
+import type { Aliases, ChangeExtFn, Condition, FileSystem, List, MainField, ModuleId } from '@flex-development/mlly';
+/**
+ * Module resolution options.
+ */
+interface ResolveModuleOptions {
+    /**
+     * The path mappings dictionary.
+     *
+     * > 👉 **Note**: Paths should be relative to {@linkcode cwd}.
+     *
+     * @see {@linkcode Aliases}
+     */
+    aliases?: Aliases | null | undefined;
+    /**
+     * The list of export/import conditions.
+     *
+     * > 👉 **Note**: Should be sorted by priority.
+     *
+     * @see {@linkcode Condition}
+     * @see {@linkcode List}
+     * @see https://nodejs.org/api/packages.html#conditional-exports
+     *
+     * @default defaultConditions
+     */
+    conditions?: List<Condition> | null | undefined;
+    /**
+     * The URL of the directory to resolve path {@linkcode aliases} from.
+     *
+     * @see {@linkcode ModuleId}
+     *
+     * @default cwd()
+     */
+    cwd?: ModuleId | null | undefined;
+    /**
+     * A replacement file extension or a function that returns a file extension.
+     *
+     * > 👉 **Note**: An empty string (`''`) or `null` will
+     * > remove a file extension.
+     *
+     * @see {@linkcode ChangeExtFn}
+     */
+    ext?: ChangeExtFn | string | null | undefined;
+    /**
+     * The module extensions to probe for.
+     *
+     * > 👉 **Note**: Should be sorted by priority.
+     *
+     * @see {@linkcode List}
+     *
+     * @default defaultExtensions
+     */
+    extensions?: List<string> | null | undefined;
+    /**
+     * The file system API.
+     *
+     * @see {@linkcode FileSystem}
+     */
+    fs?: FileSystem | null | undefined;
+    /**
+     * The list of legacy `main` fields.
+     *
+     * > 👉 **Note**: Should be sorted by priority.
+     *
+     * @see {@linkcode List}
+     * @see {@linkcode MainField}
+     *
+     * @default defaultMainFields
+     */
+    mainFields?: List<MainField> | null | undefined;
+    /**
+     * Whether to keep symlinks instead of resolving them.
+     */
+    preserveSymlinks?: boolean | null | undefined;
+}
+export type { ResolveModuleOptions as default };

package/dist/interfaces/stat.d.mts

@@ -0,0 +1,28 @@
+/**
+ * @file Interfaces - Stat
+ * @module mlly/interfaces/Stat
+ */
+import type { Awaitable, ModuleId, Stats } from '@flex-development/mlly';
+/**
+ * Get information about a directory or file.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode Stats}
+ *
+ * @template {Awaitable<Stats>} [T]
+ *  The info
+ */
+interface Stat<T extends Awaitable<Stats> = Awaitable<Stats>> {
+    /**
+     * @see {@linkcode ModuleId}
+     *
+     * @this {void}
+     *
+     * @param {ModuleId} id
+     *  The module id
+     * @return {T}
+     *  The info
+     */
+    (this: void, id: ModuleId): T;
+}
+export type { Stat as default };

package/dist/interfaces/stats.d.mts

@@ -0,0 +1,23 @@
+/**
+ * @file Interfaces - Stats
+ * @module mlly/interfaces/Stats
+ */
+import type { IsDirectory, IsFile } from '@flex-development/mlly';
+/**
+ * An object describing a directory or file.
+ */
+interface Stats {
+    /**
+     * Check if the stats object describes a directory.
+     *
+     * @see {@linkcode IsDirectory}
+     */
+    isDirectory: IsDirectory;
+    /**
+     * Check if the stats object describes a file.
+     *
+     * @see {@linkcode IsFile}
+     */
+    isFile: IsFile;
+}
+export type { Stats as default };

package/dist/internal/chain-or-call.mjs

@@ -0,0 +1,34 @@
+/**
+ * @file Internal - chainOrCall
+ * @module mlly/internal/chainOrCall
+ */
+import isPromise from '#internal/is-promise';
+export default chainOrCall;
+/**
+ * Chain a callback, calling the function after `promise` is resolved,
+ * otherwise synchronously call `fn`.
+ *
+ * @internal
+ *
+ * @see {@linkcode Awaitable}
+ *
+ * @this {void}
+ *
+ * @param {unknown} promise
+ *  The promise to chain or the resolved value
+ * @param {(...params: any[]) => unknown} fn
+ *  The function to call
+ * @param {(e: unknown) => unknown} [reject]
+ *  The callback to fire when a promise is rejected
+ * @param {unknown} [self]
+ *  The `this` context of `fn`
+ * @param {unknown[]} params
+ *  The arguments to pass to `fn`
+ * @return {unknown}
+ *  A new promise to resolve or the result of `fn`
+ */
+function chainOrCall(promise, fn, reject, self, ...params) {
+    return isPromise(promise) // already have a promise, chain callback.
+        ? promise.then(resolved => fn.call(self, ...params, resolved), reject)
+        : fn.call(self, ...params);
+}