@flex-development/mlly 1.0.0-alpha.8 → 1.0.0-beta.1

package/dist/lib/get-source.mjs

@@ -0,0 +1,156 @@
+/**
+ * @file getSource
+ * @module mlly/lib/getSource
+ */
+import chainOrCall from '#internal/chain-or-call';
+import fs from '#internal/fs';
+import isPromise from '#internal/is-promise';
+import process from '#internal/process';
+import isFile from '#lib/is-file';
+import isModuleId from '#lib/is-module-id';
+import toUrl from '#lib/to-url';
+import { ERR_UNSUPPORTED_ESM_URL_SCHEME } from '@flex-development/errnode';
+import { ok } from 'devlop';
+export default getSource;
+/**
+ * Get the source code for a module.
+ *
+ * > 👉 **Note**: Returns a promise if the handler for `id` is async.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode ErrUnsupportedEsmUrlScheme}
+ * @see {@linkcode GetSourceOptions}
+ * @see {@linkcode ModuleId}
+ *
+ * @this {void}
+ *
+ * @param {ModuleId | null | undefined} id
+ *  The module id
+ * @param {GetSourceOptions | null | undefined} [options]
+ *  Source code retrieval options
+ * @return {Awaitable<string | null | undefined>}
+ *  The module source code
+ * @throws {ErrUnsupportedEsmUrlScheme}
+ */
+function getSource(id, options) {
+    if (!isModuleId(id))
+        return null;
+    /**
+     * The source code retrieval context.
+     *
+     * @const {GetSourceContext} context
+     */
+    const context = {
+        ...options,
+        fs: options?.fs ?? fs,
+        handlers: {
+            'data:': data,
+            'file:': file,
+            'http:': https,
+            'https:': https,
+            'node:': node,
+            ...options?.handlers
+        },
+        req: { ...options?.req },
+        schemes: new Set(options?.schemes
+            ? [...options.schemes]
+            : ['data', 'file', 'http', 'https', 'node'])
+    };
+    /**
+     * The module url.
+     *
+     * @const {URL} url
+     */
+    const url = toUrl(id);
+    /**
+     * The source code handler for {@linkcode url}.
+     *
+     * @var {GetSourceHandler | null | undefined} handle
+     */
+    let handle;
+    // get source code handler.
+    handle = context.handlers[url.protocol];
+    // handle unsupported url scheme.
+    if (typeof handle !== 'function') {
+        if (context.ignoreErrors)
+            return undefined;
+        throw new ERR_UNSUPPORTED_ESM_URL_SCHEME(url, [...context.schemes], process.platform === 'win32');
+    }
+    /**
+     * The source code.
+     *
+     * @var {Awaitable<Uint8Array | string | null | undefined>} code
+     */
+    let code = handle.call(context, url);
+    // resolve source code.
+    if (isPromise(code)) {
+        void code.then(resolved => (code = resolved));
+    }
+    return chainOrCall(code, () => {
+        ok(!isPromise(code), 'expected `code` to be resolved');
+        if (code !== null && code !== undefined)
+            code = String(code);
+        return code;
+    });
+}
+/**
+ * @this {GetSourceContext}
+ *
+ * @param {URL} url
+ *  The module URL
+ * @return {Buffer}
+ *  The source code buffer
+ */
+function data(url) {
+    const [mime, data = ''] = url.pathname.split(',');
+    ok(url.protocol === 'data:', 'expected `data:` URL');
+    ok(mime !== undefined, 'expected `mime` to be a string');
+    return Buffer.from(decodeURIComponent(data), mime.endsWith('base64') ? 'base64' : 'utf8');
+}
+/**
+ * > 👉 **Note**: Returns a promise if `this.fs.readFile` or `this.fs.stat`
+ * > is async.
+ *
+ * @this {GetSourceContext}
+ *
+ * @param {URL} url
+ *  The module URL
+ * @return {Awaitable<Buffer | string | null>}
+ *  The source code
+ */
+function file(url) {
+    ok(url.protocol === 'file:', 'expected `file:` URL');
+    /**
+     * Whether the file exists.
+     *
+     * @const {Awaitable<boolean>} exists
+     */
+    const exists = isFile(url, this.fs);
+    return chainOrCall(exists, isFile => {
+        return isFile ?? exists ? this.fs.readFile(url) : null;
+    });
+}
+/**
+ * @async
+ *
+ * @this {GetSourceContext}
+ *
+ * @param {URL} url
+ *  The module URL
+ * @return {Promise<string>}
+ *  The source code
+ */
+async function https(url) {
+    ok(/^https?:$/.test(url.protocol), 'expected `http:` or `https:` URL');
+    return (await fetch(url.href, this.req)).text();
+}
+/**
+ * @this {GetSourceContext}
+ *
+ * @param {URL} url
+ *  The module URL
+ * @return {undefined}
+ */
+function node(url) {
+    return void ok(url.protocol === 'node:', 'expected `node:` URL');
+}

package/dist/lib/index.d.mts

@@ -0,0 +1,41 @@
+/**
+ * @file Entry Point - Library
+ * @module mlly/lib
+ *
+ * @todo `detectModuleSyntax` (esast integration)
+ * @todo `findDynamicImports` (esast integration)
+ * @todo `findExports` (esast integration)
+ * @todo `findImports` (esast integration)
+ * @todo `findRequires` (esast integration)
+ * @todo `findSpecifiers` (esast integration)
+ * @todo `findStaticImports` (esast integration)
+ * @todo `resolveAliases` (esast integration)
+ * @todo `resolveModules` (esast integration)
+ */
+export { default as canParseUrl } from '#lib/can-parse-url';
+export { default as cwd } from '#lib/cwd';
+export { default as defaultConditions } from '#lib/default-conditions';
+export { default as defaultExtensions } from '#lib/default-extensions';
+export { default as defaultMainFields } from '#lib/default-main-fields';
+export { default as extensionFormatMap } from '#lib/extension-format-map';
+export { default as formats } from '#lib/formats';
+export { default as getSource } from '#lib/get-source';
+export { default as isAbsoluteSpecifier } from '#lib/is-absolute-specifier';
+export { default as isArrayIndex } from '#lib/is-array-index';
+export { default as isBareSpecifier } from '#lib/is-bare-specifier';
+export { default as isDirectory } from '#lib/is-directory';
+export { default as isFile } from '#lib/is-file';
+export { default as isImportsSubpath } from '#lib/is-imports-subpath';
+export { default as isModuleId } from '#lib/is-module-id';
+export { default as isRelativeSpecifier } from '#lib/is-relative-specifier';
+export { default as lookupPackageScope } from '#lib/lookup-package-scope';
+export { default as patternKeyCompare } from '#lib/pattern-key-compare';
+export { default as patternMatch } from '#lib/pattern-match';
+export { default as readPackageJson } from '#lib/read-package-json';
+export { default as resolveAlias } from '#lib/resolve-alias';
+export { default as resolveModule } from '#lib/resolve-module';
+export * from '#lib/resolver';
+export * as resolver from '#lib/resolver';
+export { default as root } from '#lib/root';
+export { default as toRelativeSpecifier } from '#lib/to-relative-specifier';
+export { default as toUrl } from '#lib/to-url';

package/dist/lib/index.mjs

@@ -0,0 +1,41 @@
+/**
+ * @file Entry Point - Library
+ * @module mlly/lib
+ *
+ * @todo `detectModuleSyntax` (esast integration)
+ * @todo `findDynamicImports` (esast integration)
+ * @todo `findExports` (esast integration)
+ * @todo `findImports` (esast integration)
+ * @todo `findRequires` (esast integration)
+ * @todo `findSpecifiers` (esast integration)
+ * @todo `findStaticImports` (esast integration)
+ * @todo `resolveAliases` (esast integration)
+ * @todo `resolveModules` (esast integration)
+ */
+export { default as canParseUrl } from '#lib/can-parse-url';
+export { default as cwd } from '#lib/cwd';
+export { default as defaultConditions } from '#lib/default-conditions';
+export { default as defaultExtensions } from '#lib/default-extensions';
+export { default as defaultMainFields } from '#lib/default-main-fields';
+export { default as extensionFormatMap } from '#lib/extension-format-map';
+export { default as formats } from '#lib/formats';
+export { default as getSource } from '#lib/get-source';
+export { default as isAbsoluteSpecifier } from '#lib/is-absolute-specifier';
+export { default as isArrayIndex } from '#lib/is-array-index';
+export { default as isBareSpecifier } from '#lib/is-bare-specifier';
+export { default as isDirectory } from '#lib/is-directory';
+export { default as isFile } from '#lib/is-file';
+export { default as isImportsSubpath } from '#lib/is-imports-subpath';
+export { default as isModuleId } from '#lib/is-module-id';
+export { default as isRelativeSpecifier } from '#lib/is-relative-specifier';
+export { default as lookupPackageScope } from '#lib/lookup-package-scope';
+export { default as patternKeyCompare } from '#lib/pattern-key-compare';
+export { default as patternMatch } from '#lib/pattern-match';
+export { default as readPackageJson } from '#lib/read-package-json';
+export { default as resolveAlias } from '#lib/resolve-alias';
+export { default as resolveModule } from '#lib/resolve-module';
+export * from '#lib/resolver';
+export * as resolver from '#lib/resolver';
+export { default as root } from '#lib/root';
+export { default as toRelativeSpecifier } from '#lib/to-relative-specifier';
+export { default as toUrl } from '#lib/to-url';

package/dist/lib/is-absolute-specifier.d.mts

@@ -0,0 +1,23 @@
+/**
+ * @file isAbsoluteSpecifier
+ * @module mlly/lib/isAbsoluteSpecifier
+ */
+/**
+ * Check if `value` is an *absolute specifier*.
+ *
+ * ::: warning
+ * Only checks specifier syntax.
+ * Does **not** guarantee the specifier references an existing module.
+ * :::
+ *
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The value to check
+ * @return {boolean}
+ *  `true` if `value` is absolute specifier, `false` otherwise
+ */
+declare function isAbsoluteSpecifier(this: void, value: unknown): boolean;
+export default isAbsoluteSpecifier;

package/dist/lib/is-absolute-specifier.mjs

@@ -0,0 +1,34 @@
+/**
+ * @file isAbsoluteSpecifier
+ * @module mlly/lib/isAbsoluteSpecifier
+ */
+import canParseUrl from '#lib/can-parse-url';
+import isModuleId from '#lib/is-module-id';
+import pathe from '@flex-development/pathe';
+/**
+ * Check if `value` is an *absolute specifier*.
+ *
+ * ::: warning
+ * Only checks specifier syntax.
+ * Does **not** guarantee the specifier references an existing module.
+ * :::
+ *
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The value to check
+ * @return {boolean}
+ *  `true` if `value` is absolute specifier, `false` otherwise
+ */
+function isAbsoluteSpecifier(value) {
+    return (!isModuleId(value)
+        ? false
+        : typeof value === 'string'
+            ? value.startsWith('file:')
+                ? canParseUrl(value)
+                : pathe.isAbsolute(value)
+            : value.protocol === 'file:' && canParseUrl(value));
+}
+export default isAbsoluteSpecifier;

package/dist/lib/is-array-index.d.mts

@@ -0,0 +1,19 @@
+/**
+ * @file isArrayIndex
+ * @module mlly/lib/isArrayIndex
+ */
+import type { Numeric } from '@flex-development/mlly';
+/**
+ * Check if `value` is a valid array index.
+ *
+ * @see {@linkcode Numeric}
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The value to check
+ * @return {value is Numeric}
+ *  `true` if `value` is valid array index, `false` otherwise
+ */
+declare function isArrayIndex(this: void, value: unknown): value is Numeric;
+export default isArrayIndex;

package/dist/lib/is-array-index.mjs

@@ -0,0 +1,28 @@
+/**
+ * @file isArrayIndex
+ * @module mlly/lib/isArrayIndex
+ */
+/**
+ * Check if `value` is a valid array index.
+ *
+ * @see {@linkcode Numeric}
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The value to check
+ * @return {value is Numeric}
+ *  `true` if `value` is valid array index, `false` otherwise
+ */
+function isArrayIndex(value) {
+    if (typeof value !== 'string')
+        return false;
+    /**
+     * The {@linkcode value} as number.
+     *
+     * @const {number} num
+     */
+    const num = +value;
+    return value === `${num}` && num >= 0 && num < 0xFFFF_FFFF;
+}
+export default isArrayIndex;

package/dist/lib/is-bare-specifier.d.mts

@@ -0,0 +1,23 @@
+/**
+ * @file isBareSpecifier
+ * @module mlly/lib/isBareSpecifier
+ */
+/**
+ * Check if `value` is a *bare specifier*.
+ *
+ * ::: warning
+ * Only checks specifier syntax.
+ * Does **not** guarantee the specifier references an existing module.
+ * :::
+ *
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The value to check
+ * @return {boolean}
+ *  `true` if `value` is bare specifier, `false` otherwise
+ */
+declare function isBareSpecifier(this: void, value: unknown): boolean;
+export default isBareSpecifier;

package/dist/lib/is-bare-specifier.mjs

@@ -0,0 +1,33 @@
+/**
+ * @file isBareSpecifier
+ * @module mlly/lib/isBareSpecifier
+ */
+import isAbsoluteSpecifier from '#lib/is-absolute-specifier';
+import isRelativeSpecifier from '#lib/is-relative-specifier';
+import { isBuiltin } from '@flex-development/is-builtin';
+/**
+ * Check if `value` is a *bare specifier*.
+ *
+ * ::: warning
+ * Only checks specifier syntax.
+ * Does **not** guarantee the specifier references an existing module.
+ * :::
+ *
+ * @see https://nodejs.org/api/esm.html#terminology
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The value to check
+ * @return {boolean}
+ *  `true` if `value` is bare specifier, `false` otherwise
+ */
+function isBareSpecifier(value) {
+    if (isBuiltin(value))
+        return true;
+    return (typeof value === 'string' &&
+        !!value.length &&
+        !isAbsoluteSpecifier(value) &&
+        !isRelativeSpecifier(value));
+}
+export default isBareSpecifier;

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

@@ -0,0 +1,27 @@
+/**
+ * @file isDirectory
+ * @module mlly/lib/isDirectory
+ */
+import type { Awaitable, FileSystem } from '@flex-development/mlly';
+export default isDirectory;
+/**
+ * Check if a directory exists.
+ *
+ * > 👉 **Note**: Returns a promise if `fs.stat` is async.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode FileSystem}
+ *
+ * @template {Awaitable<boolean>} T
+ *  The result of the check
+ *
+ * @this {void}
+ *
+ * @param {unknown} id
+ *  The module id to check
+ * @param {FileSystem | null | undefined} fs
+ *  The file system API
+ * @return {T}
+ *  `true` if directory exists at `id`, `false` otherwise
+ */
+declare function isDirectory<T extends Awaitable<boolean>>(this: void, id: unknown, fs?: FileSystem | null | undefined): T;

package/dist/lib/is-directory.mjs

@@ -0,0 +1,54 @@
+/**
+ * @file isDirectory
+ * @module mlly/lib/isDirectory
+ */
+import chainOrCall from '#internal/chain-or-call';
+import constant from '#internal/constant';
+import dfs from '#internal/fs';
+import identity from '#internal/identity';
+import isPromise from '#internal/is-promise';
+import isModuleId from '#lib/is-module-id';
+export default isDirectory;
+/**
+ * Check if a directory exists.
+ *
+ * > 👉 **Note**: Returns a promise if `fs.stat` is async.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode FileSystem}
+ *
+ * @this {void}
+ *
+ * @param {unknown} id
+ *  The module id to check
+ * @param {FileSystem | null | undefined} fs
+ *  The file system API
+ * @return {Awaitable<boolean>}
+ *  `true` if directory exists at `id`, `false` otherwise
+ */
+function isDirectory(id, fs) {
+    if (isModuleId(id)) {
+        try {
+            if (typeof id === 'string' && id.startsWith('file:'))
+                id = new URL(id);
+            /**
+             * The stats object.
+             *
+             * @var {Awaitable<Stats | null>} stats
+             */
+            let stats = (fs ?? dfs).stat(id);
+            // resolve the stats object.
+            if (isPromise(stats))
+                stats = stats.then(identity, constant(null));
+            return chainOrCall(stats, () => {
+                if (!isPromise(stats))
+                    return stats.isDirectory();
+                return stats.then(stats => stats?.isDirectory() ?? false);
+            });
+        }
+        catch {
+            // swallow error.
+        }
+    }
+    return false;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * @file isFile
+ * @module mlly/lib/isFile
+ */
+import type { Awaitable, FileSystem } from '@flex-development/mlly';
+export default isFile;
+/**
+ * Check if a file exists.
+ *
+ * > 👉 **Note**: Returns a promise if `fs.stat` is async.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode FileSystem}
+ *
+ * @template {Awaitable<boolean>} T
+ *  The result of the check
+ *
+ * @this {void}
+ *
+ * @param {unknown} id
+ *  The module id to check
+ * @param {FileSystem | null | undefined} fs
+ *  The file system API
+ * @return {T}
+ *  `true` if file exists at `id`, `false` otherwise
+ */
+declare function isFile<T extends Awaitable<boolean>>(this: void, id: unknown, fs?: FileSystem | null | undefined): T;

package/dist/lib/is-file.mjs

@@ -0,0 +1,54 @@
+/**
+ * @file isFile
+ * @module mlly/lib/isFile
+ */
+import chainOrCall from '#internal/chain-or-call';
+import constant from '#internal/constant';
+import dfs from '#internal/fs';
+import identity from '#internal/identity';
+import isPromise from '#internal/is-promise';
+import isModuleId from '#lib/is-module-id';
+export default isFile;
+/**
+ * Check if a file exists.
+ *
+ * > 👉 **Note**: Returns a promise if `fs.stat` is async.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode FileSystem}
+ *
+ * @this {void}
+ *
+ * @param {unknown} id
+ *  The module id to check
+ * @param {FileSystem | null | undefined} fs
+ *  The file system API
+ * @return {Awaitable<boolean>}
+ *  `true` if file exists at `id`, `false` otherwise
+ */
+function isFile(id, fs) {
+    if (isModuleId(id)) {
+        try {
+            if (typeof id === 'string' && id.startsWith('file:'))
+                id = new URL(id);
+            /**
+             * The stats object.
+             *
+             * @var {Awaitable<Stats>} stats
+             */
+            let stats = (fs ?? dfs).stat(id);
+            // resolve the stats object.
+            if (isPromise(stats))
+                stats = stats.then(identity, constant(null));
+            return chainOrCall(stats, () => {
+                if (!isPromise(stats))
+                    return stats.isFile();
+                return stats.then(stats => stats?.isFile() ?? false);
+            });
+        }
+        catch {
+            // swallow error.
+        }
+    }
+    return false;
+}

package/dist/lib/is-imports-subpath.d.mts

@@ -0,0 +1,26 @@
+/**
+ * @file isImportsSubpath
+ * @module mlly/lib/isImportsSubpath
+ */
+import type { ImportsSubpath } from '@flex-development/pkg-types';
+/**
+ * Check if `value` is an [`imports`][subpath-imports] subpath.
+ *
+ * ::: warning
+ * Only checks specifier syntax.
+ * Does **not** guarantee the specifier references an existing module.
+ * :::
+ *
+ * [subpath-imports]: https://nodejs.org/api/packages.html#subpath-imports
+ *
+ * @see {@linkcode ImportsSubpath}
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The value to check
+ * @return {value is ImportsSubpath}
+ *  `true` if `value` is `imports` subpath, `false` otherwise
+ */
+declare function isImportsSubpath(this: void, value: unknown): value is ImportsSubpath;
+export default isImportsSubpath;

package/dist/lib/is-imports-subpath.mjs

@@ -0,0 +1,28 @@
+/**
+ * @file isImportsSubpath
+ * @module mlly/lib/isImportsSubpath
+ */
+import chars from '#internal/chars';
+/**
+ * Check if `value` is an [`imports`][subpath-imports] subpath.
+ *
+ * ::: warning
+ * Only checks specifier syntax.
+ * Does **not** guarantee the specifier references an existing module.
+ * :::
+ *
+ * [subpath-imports]: https://nodejs.org/api/packages.html#subpath-imports
+ *
+ * @see {@linkcode ImportsSubpath}
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The value to check
+ * @return {value is ImportsSubpath}
+ *  `true` if `value` is `imports` subpath, `false` otherwise
+ */
+function isImportsSubpath(value) {
+    return typeof value === 'string' && value[0] === chars.hash;
+}
+export default isImportsSubpath;

package/dist/lib/is-module-id.d.mts

@@ -0,0 +1,23 @@
+/**
+ * @file isModuleId
+ * @module mlly/lib/isModuleId
+ */
+import type { ModuleId } from '@flex-development/mlly';
+/**
+ * Check if `value` is a module id.
+ *
+ * ::: warning
+ * Does **not** guarantee `value` references an existing file or directory.
+ * :::
+ *
+ * @see {@linkcode ModuleId}
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The value to check
+ * @return {value is ModuleId}
+ *  `true` if `value` is module id, `false` otherwise
+ */
+declare function isModuleId(this: void, value: unknown): value is ModuleId;
+export default isModuleId;

package/dist/lib/is-module-id.mjs

@@ -0,0 +1,24 @@
+/**
+ * @file isModuleId
+ * @module mlly/lib/isModuleId
+ */
+/**
+ * Check if `value` is a module id.
+ *
+ * ::: warning
+ * Does **not** guarantee `value` references an existing file or directory.
+ * :::
+ *
+ * @see {@linkcode ModuleId}
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The value to check
+ * @return {value is ModuleId}
+ *  `true` if `value` is module id, `false` otherwise
+ */
+function isModuleId(value) {
+    return typeof value === 'string' || value instanceof URL;
+}
+export default isModuleId;