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

package/dist/lib/root.d.mts

@@ -0,0 +1,11 @@
+/**
+ * @file root
+ * @module mlly/lib/root
+ */
+/**
+ * The URL of the file system root.
+ *
+ * @const {URL} root
+ */
+declare const root: URL;
+export default root;

package/dist/lib/root.mjs

@@ -0,0 +1,12 @@
+/**
+ * @file root
+ * @module mlly/lib/root
+ */
+import { dot, parse, pathToFileURL, resolve } from '@flex-development/pathe';
+/**
+ * The URL of the file system root.
+ *
+ * @const {URL} root
+ */
+const root = pathToFileURL(parse(resolve(dot)).root);
+export default root;

package/dist/lib/to-relative-specifier.d.mts

@@ -0,0 +1,27 @@
+/**
+ * @file toRelativeSpecifier
+ * @module mlly/lib/toRelativeSpecifier
+ */
+import type { ModuleId } from '@flex-development/mlly';
+/**
+ * Turn `url` into a *relative specifier*.
+ *
+ * ::: info
+ * The relative specifier will only have a file extension
+ * if `specifier` also has an extension.
+ * :::
+ *
+ * @see {@linkcode ModuleId}
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @this {void}
+ *
+ * @param {ModuleId} url
+ *  The `file:` URL to convert
+ * @param {ModuleId} parent
+ *  The parent module id
+ * @return {string}
+ *  The relative specifier
+ */
+declare function toRelativeSpecifier(this: void, url: ModuleId, parent: ModuleId): string;
+export default toRelativeSpecifier;

package/dist/lib/to-relative-specifier.mjs

@@ -0,0 +1,63 @@
+/**
+ * @file toRelativeSpecifier
+ * @module mlly/lib/toRelativeSpecifier
+ */
+import pathe from '@flex-development/pathe';
+import { ok } from 'devlop';
+/**
+ * Turn `url` into a *relative specifier*.
+ *
+ * ::: info
+ * The relative specifier will only have a file extension
+ * if `specifier` also has an extension.
+ * :::
+ *
+ * @see {@linkcode ModuleId}
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @this {void}
+ *
+ * @param {ModuleId} url
+ *  The `file:` URL to convert
+ * @param {ModuleId} parent
+ *  The parent module id
+ * @return {string}
+ *  The relative specifier
+ */
+function toRelativeSpecifier(url, parent) {
+    parent = pathe.fileURLToPath(parent);
+    url = pathe.fileURLToPath(url);
+    /**
+     * The directory name of the {@linkcode parent} path.
+     *
+     * @const {string} dirname
+     */
+    const dirname = pathe.dirname(parent);
+    /**
+     * The relative specifier.
+     *
+     * @var {string} specifier
+     */
+    let specifier;
+    if (url.startsWith(parent) && parent.endsWith(pathe.sep)) {
+        // inside same directory as parent
+        specifier = pathe.dot + pathe.sep + url.slice(parent.length);
+    }
+    else if (url === dirname || url.startsWith(dirname + pathe.sep)) {
+        // directory name of parent or inside same directory as parent
+        specifier = pathe.dot + pathe.sep + url.slice(dirname.length + 1);
+    }
+    else {
+        // outside directory of parent
+        specifier = pathe.relative(parent, url);
+        ok(specifier.startsWith(pathe.dot), 'expected result to start with `.`');
+        /* v8 ignore else -- @preserve */
+        if (/(?:\.\.\/){2,}/.test(specifier)) {
+            // remove first '../' segment:
+            // pathe.relative backs out of an extra directory
+            specifier = specifier.slice(specifier.indexOf(pathe.sep) + 1);
+        }
+    }
+    return specifier;
+}
+export default toRelativeSpecifier;

package/dist/lib/to-url.d.mts

@@ -0,0 +1,26 @@
+/**
+ * @file toUrl
+ * @module mlly/lib/toUrl
+ */
+import type { ModuleId } from '@flex-development/mlly';
+/**
+ * Convert `id` to a {@linkcode URL}.
+ *
+ * > 👉 **Note**: If `id` cannot be parsed as a `URL`, and is also not a
+ * > [builtin module][builtin-module], it will be assumed to be a path and
+ * > converted to a [`file:` URL][file-url].
+ *
+ * [builtin-module]: https://nodejs.org/api/esm.html#builtin-modules
+ * [file-url]: https://nodejs.org/api/esm.html#file-urls
+ *
+ * @this {void}
+ *
+ * @param {ModuleId} id
+ *  The module id to convert
+ * @param {ModuleId | null | undefined} [parent]
+ *  The base URL to resolve against if `id` is not absolute
+ * @return {URL}
+ *  The new URL
+ */
+declare function toUrl(this: void, id: ModuleId, parent?: ModuleId | null | undefined): URL;
+export default toUrl;

package/dist/lib/to-url.mjs

@@ -0,0 +1,34 @@
+/**
+ * @file toUrl
+ * @module mlly/lib/toUrl
+ */
+import canParseUrl from '#lib/can-parse-url';
+import { isBuiltin } from '@flex-development/is-builtin';
+import pathe from '@flex-development/pathe';
+/**
+ * Convert `id` to a {@linkcode URL}.
+ *
+ * > 👉 **Note**: If `id` cannot be parsed as a `URL`, and is also not a
+ * > [builtin module][builtin-module], it will be assumed to be a path and
+ * > converted to a [`file:` URL][file-url].
+ *
+ * [builtin-module]: https://nodejs.org/api/esm.html#builtin-modules
+ * [file-url]: https://nodejs.org/api/esm.html#file-urls
+ *
+ * @this {void}
+ *
+ * @param {ModuleId} id
+ *  The module id to convert
+ * @param {ModuleId | null | undefined} [parent]
+ *  The base URL to resolve against if `id` is not absolute
+ * @return {URL}
+ *  The new URL
+ */
+function toUrl(id, parent) {
+    return canParseUrl(id, parent)
+        ? new URL(id, parent ?? undefined)
+        : isBuiltin(id)
+            ? new URL('node:' + String(id))
+            : pathe.pathToFileURL(String(id));
+}
+export default toUrl;

package/dist/types/awaitable.d.mts

@@ -0,0 +1,12 @@
+/**
+ * @file Type Aliases - Awaitable
+ * @module mlly/types/Awaitable
+ */
+/**
+ * Create a union of `T` and `T` as a promise-like object.
+ *
+ * @template {any} T
+ *  The value
+ */
+type Awaitable<T> = PromiseLike<T> | T;
+export type { Awaitable as default };

package/dist/types/change-ext-fn.d.mts

@@ -0,0 +1,29 @@
+/**
+ * @file Type Aliases - ChangeExtFn
+ * @module mlly/types/ChangeExtFn
+ */
+/**
+ * Get a new file extension for `url`.
+ *
+ * Returning an empty string (`''`), `null`, or `undefined` will remove the
+ * current file extension.
+ *
+ * ::: 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 {string | null | undefined} Ext
+ *  The new file extension
+ *
+ * @param {URL} url
+ *  The resolved module URL
+ * @param {string} specifier
+ *  The module specifier being resolved
+ * @return {Ext}
+ *  The new file extension
+ */
+type ChangeExtFn<Ext extends string | null | undefined = string | null | undefined> = (this: void, url: URL, specifier: string) => Ext;
+export type { ChangeExtFn as default };

package/dist/types/condition.d.mts

@@ -0,0 +1,13 @@
+/**
+ * @file Type Aliases - Condition
+ * @module mlly/types/Condition
+ */
+import type { ConditionMap } from '@flex-development/mlly';
+/**
+ * Union of values that can occur where a export/import condition is expected.
+ *
+ * To register new conditions, augment {@linkcode ConditionMap}.
+ * They will be added to this union automatically.
+ */
+type Condition = ConditionMap[keyof ConditionMap];
+export type { Condition as default };

package/dist/types/dot.d.mts

@@ -0,0 +1,9 @@
+/**
+ * @file Type Aliases - Dot
+ * @module mlly/types/Dot
+ */
+/**
+ * A dot character (`'.'`).
+ */
+type Dot = '.';
+export type { Dot as default };

package/dist/types/empty-array.d.mts

@@ -0,0 +1,9 @@
+/**
+ * @file Type Aliases - EmptyArray
+ * @module mlly/types/EmptyArray
+ */
+/**
+ * An empty array.
+ */
+type EmptyArray = [];
+export type { EmptyArray as default };

package/dist/types/empty-object.d.mts

@@ -0,0 +1,19 @@
+/**
+ * @file Type Aliases - EmptyObject
+ * @module mlly/types/EmptyObject
+ */
+/**
+ * The empty object symbol.
+ *
+ * @internal
+ *
+ * @const {symbol} tag
+ */
+export declare const tag: unique symbol;
+/**
+ * An empty object.
+ */
+type EmptyObject = {
+    [tag]?: never;
+};
+export type { EmptyObject as default };

package/dist/types/empty-string.d.mts

@@ -0,0 +1,9 @@
+/**
+ * @file Type Aliases - EmptyString
+ * @module mlly/types/EmptyString
+ */
+/**
+ * An empty string.
+ */
+type EmptyString = '';
+export type { EmptyString as default };

package/dist/types/ext.d.mts

@@ -0,0 +1,12 @@
+/**
+ * @file Type Aliases - Ext
+ * @module mlly/types/Ext
+ */
+import type { Dot } from '@flex-development/mlly';
+/**
+ * A file extension.
+ *
+ * @see {@linkcode Dot}
+ */
+type Ext = `${Dot}${string}`;
+export type { Ext as default };

package/dist/types/get-source-handler.d.mts

@@ -0,0 +1,22 @@
+/**
+ * @file Type Aliases - GetSourceHandler
+ * @module mlly/types/GetSourceHandler
+ */
+import type { Awaitable, GetSourceContext } from '@flex-development/mlly';
+/**
+ * Get the source code for a module.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode GetSourceContext}
+ * @see {@linkcode URL}
+ *
+ * @this {GetSourceContext}
+ *  The retrieval context
+ *
+ * @param {URL} url
+ *  The module URL
+ * @return {Awaitable<Uint8Array | string | null | undefined>}
+ *  The source code
+ */
+type GetSourceHandler = (this: GetSourceContext, url: URL) => Awaitable<Uint8Array | string | null | undefined>;
+export type { GetSourceHandler as default };

package/dist/types/get-source-handlers.d.mts

@@ -0,0 +1,15 @@
+/**
+ * @file Type Aliases - GetSourceHandlers
+ * @module mlly/types/GetSourceHandlers
+ */
+import type { GetSourceHandler, Protocol } from '@flex-development/mlly';
+/**
+ * Record, where key is a URL protocol and each value is a source code handler.
+ *
+ * @see {@linkcode GetSourceHandler}
+ * @see {@linkcode Protocol}
+ */
+type GetSourceHandlers = {
+    [H in Protocol]?: GetSourceHandler | null | undefined;
+};
+export type { GetSourceHandlers as default };

package/dist/types/index.d.mts

@@ -1,13 +1,22 @@
 /**
- * @file Type Definitions
+ * @file Entry Point - Type Aliases
  * @module mlly/types
  */
-export type { default as Declaration } from './declaration.mjs';
-export type { default as ChangeExtFn } from './fn-change-ext.mjs';
-export type { default as MimeType } from './mime-type.mjs';
-export type { default as ModuleId } from './module-id.mjs';
-export type { default as ModuleSpecifierType } from './module-specifier-type.mjs';
-export type { default as Protocol } from './protocol.mjs';
-export type { default as SyntaxKindExport } from './syntax-kind-export.mjs';
-export type { default as SyntaxKindImport } from './syntax-kind-import.mjs';
-export type { default as SyntaxKindRequire } from './syntax-kind-require.mjs';
+export type { default as Awaitable } from '#types/awaitable';
+export type { default as ChangeExtFn } from '#types/change-ext-fn';
+export type { default as Condition } from '#types/condition';
+export type { default as Dot } from '#types/dot';
+export type { default as EmptyArray } from '#types/empty-array';
+export type { default as EmptyObject } from '#types/empty-object';
+export type { default as EmptyString } from '#types/empty-string';
+export type { default as Ext } from '#types/ext';
+export type { default as GetSourceHandler } from '#types/get-source-handler';
+export type { default as GetSourceHandlers } from '#types/get-source-handlers';
+export type { default as List } from '#types/list';
+export type { default as MainField } from '#types/main-field';
+export type { default as ModuleFormat } from '#types/module-format';
+export type { default as ModuleId } from '#types/module-id';
+export type { default as Numeric } from '#types/numeric';
+export type { default as PatternKeyComparison } from '#types/pattern-key-comparison';
+export type { default as PatternMatch } from '#types/pattern-match';
+export type { default as Protocol } from '#types/protocol';

package/dist/types/list.d.mts

@@ -0,0 +1,12 @@
+/**
+ * @file Type Aliases - List
+ * @module mlly/types/List
+ */
+/**
+ * A list.
+ *
+ * @template {any} [T=unknown]
+ *  The list item type
+ */
+type List<T = unknown> = ReadonlySet<T> | readonly T[];
+export type { List as default };

package/dist/types/main-field.d.mts

@@ -0,0 +1,13 @@
+/**
+ * @file Type Aliases - MainField
+ * @module mlly/types/MainField
+ */
+import type { MainFieldMap } from '@flex-development/mlly';
+/**
+ * Union of values that can occur where a main field is expected.
+ *
+ * To register new fields, augment {@linkcode MainFieldMap}.
+ * They will be added to this union automatically.
+ */
+type MainField = MainFieldMap[keyof MainFieldMap];
+export type { MainField as default };

package/dist/types/module-format.d.mts

@@ -0,0 +1,13 @@
+/**
+ * @file Type Aliases - ModuleFormat
+ * @module mlly/types/ModuleFormat
+ */
+import type { ModuleFormatMap } from '@flex-development/mlly';
+/**
+ * Union of values that can occur where a module format is expected.
+ *
+ * To register new formats, augment {@linkcode ModuleFormatMap}.
+ * They will be added to this union automatically.
+ */
+type ModuleFormat = ModuleFormatMap[keyof ModuleFormatMap];
+export type { ModuleFormat as default };

package/dist/types/module-id.d.mts

@@ -1,11 +1,10 @@
 /**
- * @file Type Definitions - ModuleId
+ * @file Type Aliases - ModuleId
  * @module mlly/types/ModuleId
  */
-/// <reference types="node" />
-import type { URL } from 'node:url';
 /**
- * ECMAScript (ES) module identifier.
+ * Union of values that can occur where a
+ * ECMAScript (ES) module identifier is expected.
  *
  * @see {@linkcode URL}
  */

package/dist/types/numeric.d.mts

@@ -0,0 +1,9 @@
+/**
+ * @file Type Aliases - Numeric
+ * @module mlly/types/Numeric
+ */
+/**
+ * String containing only numbers (not including the leading `-` if negative).
+ */
+type Numeric = `${number}`;
+export type { Numeric as default };

package/dist/types/pattern-key-comparison.d.mts

@@ -0,0 +1,14 @@
+/**
+ * @file Type Aliases - PatternKeyComparison
+ * @module mlly/types/PatternKeyComparison
+ */
+import type { PatternKeyComparisonMap } from '@flex-development/mlly';
+/**
+ * Union of values that can occur
+ * where a `PATTERN_KEY_COMPARE` algorithm result is expected.
+ *
+ * To register new results, augment {@linkcode PatternKeyComparisonMap}.
+ * They will be added to this union automatically.
+ */
+type PatternKeyComparison = PatternKeyComparisonMap[keyof PatternKeyComparisonMap];
+export type { PatternKeyComparison as default };

package/dist/types/pattern-match.d.mts

@@ -0,0 +1,10 @@
+/**
+ * @file Type Aliases - PatternMatch
+ * @module mlly/types/PatternMatch
+ */
+/**
+ * List, where the first item is the key of a package `exports` or `imports`
+ * target object, and the last is a subpath pattern match.
+ */
+type PatternMatch = [expansionKey: string, patternMatch: string | null];
+export type { PatternMatch as default };

package/dist/types/protocol.d.mts

@@ -1,14 +1,13 @@
 /**
- * @file Type Definitions - Protocol
+ * @file Type Aliases - Protocol
  * @module mlly/types/Protocol
  */
-import type { LiteralUnion } from '@flex-development/tutils';
+import type { ProtocolMap } from '@flex-development/mlly';
 /**
- * URL protocols.
+ * Union of values that can occur where a URL protocol is expected.
  *
- * @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
+ * To register new protocols, augment {@linkcode ProtocolMap}.
+ * They will be added to this union automatically.
  */
-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}:`>;
+type Protocol = ProtocolMap[keyof ProtocolMap];
 export type { Protocol as default };