@flex-development/mlly 1.0.0-alpha.18 → 1.0.0-alpha.19

package/README.md

@@ -1,20 +1,181 @@
-# mlly
+# \:gear: mlly
 
-[![github release](https://img.shields.io/github/v/release/flex-development/mlly.svg?include_prereleases&sort=semver)](https://github.com/flex-development/mlly/releases/latest)
+[![github release](https://img.shields.io/github/v/release/flex-development/mlly.svg?include_prereleases\&sort=semver)](https://github.com/flex-development/mlly/releases/latest)
 [![npm](https://img.shields.io/npm/v/@flex-development/mlly.svg)](https://npmjs.com/package/@flex-development/mlly)
-[![codecov](https://codecov.io/gh/flex-development/mlly/branch/main/graph/badge.svg?token=36NUNRH6FW)](https://codecov.io/gh/flex-development/mlly)
+[![codecov](https://codecov.io/gh/flex-development/mlly/graph/badge.svg?token=36NUNRH6FW)](https://codecov.io/gh/flex-development/mlly)
 [![module type: esm](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://github.com/voxpelli/badges-cjs-esm)
 [![license](https://img.shields.io/github/license/flex-development/mlly.svg)](LICENSE.md)
-[![conventional commits](https://img.shields.io/badge/-conventional%20commits-fe5196?logo=conventional-commits&logoColor=ffffff)](https://conventionalcommits.org/)
-[![typescript](https://img.shields.io/badge/-typescript-3178c6?logo=typescript&logoColor=ffffff)](https://typescriptlang.org/)
-[![vitest](https://img.shields.io/badge/-vitest-6e9f18?style=flat&logo=vitest&logoColor=ffffff)](https://vitest.dev/)
-[![yarn](https://img.shields.io/badge/-yarn-2c8ebb?style=flat&logo=yarn&logoColor=ffffff)](https://yarnpkg.com/)
+[![conventional commits](https://img.shields.io/badge/-conventional%20commits-fe5196?logo=conventional-commits\&logoColor=ffffff)](https://conventionalcommits.org)
+[![typescript](https://img.shields.io/badge/-typescript-3178c6?logo=typescript\&logoColor=ffffff)](https://typescriptlang.org)
+[![vitest](https://img.shields.io/badge/-vitest-6e9f18?style=flat\&logo=vitest\&logoColor=ffffff)](https://vitest.dev)
+[![yarn](https://img.shields.io/badge/-yarn-2c8ebb?style=flat\&logo=yarn\&logoColor=ffffff)](https://yarnpkg.com)
 
-> [ECMAScript module][1] utilities.
+[ECMAScript module][node-esm] utilities.
 
-## Getting Started
+## Contents
 
-See the [docs][2] for install and usage instructions.
+- [What is this?](#what-is-this)
+- [Install](#install)
+- [Use](#use)
+- [API](#api)
+- [Types](#types)
+- [Contribute](#contribute)
 
-[1]: https://nodejs.org/api/esm.html
-[2]: https://mlly.vercel.app/
+## What is this?
+
+`mlly` is a set of [ECMAScript module][node-esm] (ESM) utilities. It exposes several tools to bridge the gap between
+developer experience and the current state of ECMAScript modules.
+
+## Install
+
+This package is [ESM only][esm].
+
+In Node.js (version 18+) with [yarn][]:
+
+```sh
+yarn add @flex-development/mlly
+```
+
+<blockquote>
+  <small>
+    See <a href='https://yarnpkg.com/protocol/git'>Git - Protocols | Yarn</a>
+    &nbsp;for details regarding installing from Git.
+  </small>
+</blockquote>
+
+In Deno with [`esm.sh`][esmsh]:
+
+```ts
+import { resolveModule } from 'https://esm.sh/@flex-development/mlly'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import { resolveModule } from 'https://esm.sh/@flex-development/mlly'
+</script>
+```
+
+## Use
+
+```js
+import {
+  canParseUrl,
+  cwd,
+  defaultConditions,
+  defaultExtensions,
+  defaultMainFields,
+  extensionFormatMap,
+  formats,
+  getSource,
+  isAbsoluteSpecifier,
+  isArrayIndex,
+  isBareSpecifier,
+  isDirectory,
+  isFile,
+  isImportsSubpath,
+  isRelativeSpecifier,
+  legacyMainResolve,
+  lookupPackageScope,
+  moduleResolve,
+  packageExportsResolve,
+  packageImportsExportsResolve,
+  packageImportsResolve,
+  packageResolve,
+  packageSelfResolve,
+  packageTargetResolve,
+  patternKeyCompare,
+  patternMatch,
+  readPackageJson,
+  resolveAlias,
+  resolveModule,
+  resolver,
+  root,
+  toRelativeSpecifier,
+  toUrl
+} from '@flex-development/mlly'
+```
+
+## API
+
+This package exports the following identifiers:
+
+- [`canParseUrl`](./src/lib/can-parse-url.mts)
+- [`cwd`](./src/lib/cwd.mts)
+- [`defaultConditions`](./src/lib/default-conditions.mts)
+- [`defaultExtensions`](./src/lib/default-extensions.mts)
+- [`defaultMainFields`](./src/lib/default-main-fields.mts)
+- [`extensionFormatMap`](./src/lib/extension-format-map.mts)
+- [`formats`](./src/lib/formats.mts)
+- [`getSource`](./src/lib/get-source.mts)
+- [`isAbsoluteSpecifier`](./src/lib/is-absolute-specifier.mts)
+- [`isArrayIndex`](./src/lib/is-array-index.mts)
+- [`isBareSpecifier`](./src/lib/is-bare-specifier.mts)
+- [`isDirectory`](./src/lib/is-directory.mts)
+- [`isFile`](./src/lib/is-file.mts)
+- [`isImportsSubpath`](./src/lib/is-imports-subpath.mts)
+- [`isRelativeSpecifier`](./src/lib/is-relative-specifier.mts)
+- [`lookupPackageScope`](./src/lib/lookup-package-scope.mts)
+- [`patternKeyCompare`](./src/lib/pattern-key-compare.mts)
+- [`patternMatch`](./src/lib/pattern-match.mts)
+- [`readPackageJson`](./src/lib/read-package-json.mts)
+- [`resolveAlias`](./src/lib/resolve-alias.mts)
+- [`resolveModule`](./src/lib/resolve-module.mts)
+- [`resolver`](./src/lib/resolver.mts)
+  - `legacyMainResolve`
+  - `moduleResolve`
+  - `packageExportsResolve`
+  - `packageImportsExportsResolve`
+  - `packageImportsResolve`
+  - `packageResolve`
+  - `packageSelfResolve`
+  - `packageTargetResolve`
+- [`root`](./src/lib/root.mts)
+- [`toRelativeSpecifier`](./src/lib/to-relative-specifier.mts)
+- [`toUrl`](./src/lib/to-url.mts)
+
+There is no default export.
+
+## Types
+
+This package is fully typed with [TypeScript][].
+
+### Interfaces
+
+- [`Aliases`](src/interfaces/aliases.mts)
+- [`FileSystem`](src/interfaces/file-system.mts)
+- [`MainFieldMap`](src/interfaces/main-field-map.mts)
+- [`ModuleFormatMap`](src/interfaces/module-format-map.mts)
+- [`ResolveAliasOptions`](src/interfaces/options-resolve-alias.mts)
+- [`ResolveModuleOptions`](src/interfaces/options-resolve-module.mts)
+- [`ProtocolMap`](src/interfaces/protocol-map.mts)
+- [`Stats`](src/interfaces/stats.mts)
+
+### Type Aliases
+
+- [`ChangeExtFn`](src/types/change-ext-fn.mts)
+- [`MainField`](src/types/main-field.mts)
+- [`ModuleFormat`](src/types/module-format.mts)
+- [`ModuleId`](src/types/module-id.mts)
+- [`Numeric`](src/types/numeric.mts)
+- [`PatternKeyCompareResult`](src/types/pattern-key-compare-result.mts)
+- [`PatternMatch`](src/types/pattern-match.mts)
+- [`Protocol`](src/types/protocol.mts)
+
+## Contribute
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+This project has a [code of conduct](./CODE_OF_CONDUCT.md). By interacting with this repository, organization, or
+community you agree to abide by its terms.
+
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[node-esm]: https://nodejs.org/api/esm.html
+
+[typescript]: https://www.typescriptlang.org
+
+[yarn]: https://yarnpkg.com

package/dist/index.d.mts

@@ -2,7 +2,6 @@
  * @file Package Entry Point
  * @module mlly
  */
-export * from './enums/index.mjs';
-export type * from './interfaces/index.mjs';
-export type * 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,3 +1 @@
-export * from "./enums/index.mjs";
-export * from "./utils/index.mjs";
-//# sourceMappingURL=index.mjs.map
+export * from "#lib/index";

package/dist/interfaces/aliases.d.mts

@@ -0,0 +1,11 @@
+/**
+ * @file Interfaces - Aliases
+ * @module mlly/interfaces/Aliases
+ */
+/**
+ * Path aliases.
+ */
+interface Aliases {
+    [alias: string]: (string | null | undefined)[] | string | null | undefined;
+}
+export type { Aliases as default };

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

@@ -0,0 +1,52 @@
+/**
+ * @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 {
+    /**
+     * Throw [`ERR_UNSUPPORTED_ESM_URL_SCHEME`][err]?
+     *
+     * [err]: https://nodejs.org/api/errors.html#err_unsupported_esm_url_scheme
+     */
+    error: boolean;
+    /**
+     * File system API.
+     *
+     * @see {@linkcode FileSystem}
+     *
+     * @override
+     */
+    fs: FileSystem;
+    /**
+     * URL handler map.
+     *
+     * @see {@linkcode GetSourceHandlers}
+     *
+     * @override
+     */
+    handlers: GetSourceHandlers;
+    /**
+     * Request options for network based modules.
+     *
+     * > 👉 **Note**: Only applicable if {@linkcode network} is
+     * > enabled.
+     *
+     * @override
+     */
+    req: RequestInit;
+    /**
+     * List of supported URL schemes.
+     *
+     * @override
+     */
+    schemes: Set<string>;
+}
+export type { GetSourceContext as default };

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

@@ -0,0 +1,57 @@
+/**
+ * @file Interfaces - FileSystem
+ * @module mlly/interfaces/FileSystem
+ */
+import type { Awaitable, ModuleId, Stats } from '@flex-development/mlly';
+/**
+ * File system API.
+ */
+interface FileSystem {
+    /**
+     * Get the contents of `id`.
+     *
+     * @see {@linkcode Awaitable}
+     * @see {@linkcode Buffer}
+     * @see {@linkcode ModuleId}
+     * @see https://nodejs.org/api/fs.html#fsreadfilepath-options-callback
+     *
+     * @this {void}
+     *
+     * @param {ModuleId} id
+     *  The path or `file:` URL to handle
+     * @return {Awaitable<Buffer | string>}
+     *  File contents
+     */
+    readFile(this: void, id: ModuleId): Awaitable<Buffer | string>;
+    /**
+     * Get the resolved pathname for `id`.
+     *
+     * @see {@linkcode Awaitable}
+     * @see {@linkcode ModuleId}
+     * @see https://nodejs.org/api/fs.html#fsrealpathpath-options-callback
+     *
+     * @this {void}
+     *
+     * @param {ModuleId} id
+     *  The path or `file:` URL to handle
+     * @return {Awaitable<string>}
+     *  Resolved pathname
+     */
+    realpath(this: void, id: ModuleId): Awaitable<string>;
+    /**
+     * Get information about a directory or file.
+     *
+     * @see {@linkcode Awaitable}
+     * @see {@linkcode ModuleId}
+     * @see {@linkcode Stats}
+     *
+     * @this {void}
+     *
+     * @param {ModuleId} id
+     *  The path or `file:` URL to handle
+     * @return {Awaitable<Stats>}
+     *  Info about `id`
+     */
+    stat(this: void, id: ModuleId): Awaitable<Stats>;
+}
+export type { FileSystem as default };

package/dist/interfaces/index.d.mts

@@ -1,24 +1,14 @@
 /**
- * @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 GetSourceContext } from '#interfaces/context-get-source';
+export type { default as FileSystem } from '#interfaces/file-system';
+export type { default as MainFieldMap } from '#interfaces/main-field-map';
+export type { default as ModuleFormatMap } from '#interfaces/module-format-map';
+export type { default as GetSourceOptions } from '#interfaces/options-get-source';
+export type { default as ResolveAliasOptions } from '#interfaces/options-resolve-alias';
+export type { default as ResolveModuleOptions } from '#interfaces/options-resolve-module';
+export type { default as ProtocolMap } from '#interfaces/protocol-map';
+export type { default as Stats } from '#interfaces/stats';

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

@@ -0,0 +1,13 @@
+/**
+ * @file Interfaces - MainFieldMap
+ * @module mlly/interfaces/MainFieldMap
+ */
+/**
+ * Main fields registry.
+ */
+interface MainFieldMap {
+    main: 'main';
+    module: 'module';
+    types: 'types';
+}
+export type { MainFieldMap as default };

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

@@ -0,0 +1,17 @@
+/**
+ * @file Interfaces - ModuleFormatMap
+ * @module mlly/interfaces/ModuleFormatMap
+ */
+/**
+ * Module format registry.
+ */
+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/options-get-source.d.mts

@@ -2,53 +2,46 @@
  * @file Interfaces - GetSourceOptions
  * @module mlly/interfaces/GetSourceOptions
  */
-import type { Format } from '../enums/index.mjs';
-import type { Optional, OrLowercase } from '@flex-development/tutils';
+import type { FileSystem, GetSourceHandlers, ModuleFormat } from '@flex-development/mlly';
 /**
  * Source code retrieval options.
- *
- * @see {@linkcode Format}
- * @see {@linkcode RequestInit}
  */
 interface GetSourceOptions {
     /**
-     * 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
+     * Module format hint.
      *
-     * @default false
+     * @see {@linkcode ModuleFormat}
      */
-    experimental_network_imports?: Optional<boolean>;
+    format?: ModuleFormat | null | undefined;
     /**
-     * Module format hint.
-     *
-     * @see {@linkcode Format}
+     * File system API.
      *
-     * @default undefined
+     * @see {@linkcode FileSystem}
      */
-    format?: Optional<OrLowercase<Format>>;
+    fs?: FileSystem | null | undefined;
     /**
-     * Ignore [`ERR_UNSUPPORTED_ESM_URL_SCHEME`][1] if thrown.
+     * URL handler map.
      *
-     * [1]: https://nodejs.org/api/errors.html#err_unsupported_esm_url_scheme
+     * @see {@linkcode GetSourceHandlers}
+     */
+    handlers?: GetSourceHandlers | null | undefined;
+    /**
+     * Ignore [`ERR_UNSUPPORTED_ESM_URL_SCHEME`][err] if thrown.
      *
-     * @default false
+     * [err]: https://nodejs.org/api/errors.html#err_unsupported_esm_url_scheme
      */
-    ignore_errors?: Optional<boolean>;
+    ignoreErrors?: boolean | null | undefined;
     /**
      * Request options for network based modules.
      *
-     * Only applicable if {@linkcode experimental_network_imports} is enabled.
-     *
-     * @see {@linkcode RequestInit}
+     * > 👉 **Note**: Only applicable if {@linkcode network} is enabled.
+     */
+    req?: RequestInit | null | undefined;
+    /**
+     * List of supported URL schemes.
      *
-     * @default {}
+     * @default ['data','file','http','https','node']
      */
-    // @ts-ignore peer dependency
-    req?: Optional<import('node-fetch').RequestInit>;
+    schemes?: Set<string> | readonly string[] | null | undefined;
 }
 export type { GetSourceOptions as default };

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

@@ -2,52 +2,40 @@
  * @file Interfaces - ResolveAliasOptions
  * @module mlly/interfaces/ResolveAliasOptions
  */
-import type { ModuleId } from '../types/index.mjs';
-import type { MapLike, OneOrMany, Optional } from '@flex-development/tutils';
-import type ResolveModuleOptions from './options-resolve-module.mjs';
+import type { Aliases, ModuleId } from '@flex-development/mlly';
 /**
  * Path alias resolution options.
- *
- * @see {@linkcode ModuleId}
- *
- * @extends {ResolveModuleOptions}
  */
-interface ResolveAliasOptions extends ResolveModuleOptions {
+interface ResolveAliasOptions {
     /**
      * 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?: Optional<boolean>;
+    absolute?: boolean | null | undefined;
     /**
      * Path mappings.
      *
-     * **Note**: Paths should be relative to {@linkcode cwd}.
+     * > 👉 **Note**: Paths should be relative to {@linkcode cwd}.
      *
-     * @default {}
+     * @see {@linkcode Aliases}
      */
-    aliases?: Optional<MapLike<OneOrMany<string>>>;
+    aliases?: Aliases | null | undefined;
     /**
-     * Directory to resolve non-absolute modules from.
+     * URL of directory to resolve non-absolute modules from.
+     *
+     * @see {@linkcode ModuleId}
      *
-     * @default pathToFileURL('.')
+     * @default cwd()
      */
-    cwd?: Optional<ModuleId>;
+    cwd?: ModuleId | null | 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
+     * URL of parent module.
      *
-     * @default import.meta.url
+     * @see {@linkcode ModuleId}
      */
-    parent?: Optional<ModuleId>;
+    parent?: ModuleId | null | undefined;
 }
 export type { ResolveAliasOptions as default };

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

@@ -2,63 +2,74 @@
  * @file Interfaces - ResolveModuleOptions
  * @module mlly/interfaces/ResolveModuleOptions
  */
-import type { ChangeExtFn, ModuleId } from '../types/index.mjs';
-import type { Nilable, Optional } from '@flex-development/tutils';
+import type { Aliases, ChangeExtFn, FileSystem, MainField, ModuleId } from '@flex-development/mlly';
+import type { Condition } from '@flex-development/pkg-types';
 /**
  * Module resolution options.
- *
- * @see {@linkcode ChangeExtFn}
- * @see {@linkcode ModuleId}
  */
 interface ResolveModuleOptions {
     /**
-     * Export condition to apply.
+     * Path mappings.
      *
-     * @see https://nodejs.org/api/packages.html#conditional-exports
+     * > 👉 **Note**: Paths should be relative to {@linkcode cwd}.
      *
-     * @default 'default'
+     * @see {@linkcode Aliases}
      */
-    condition?: Optional<string>;
+    aliases?: Aliases | null | undefined;
     /**
-     * Export conditions.
+     * List of export/import conditions.
      *
-     * **Note**: Should be sorted by priority.
+     * > 👉 **Note**: Should be sorted by priority.
      *
+     * @see {@linkcode Condition}
      * @see https://nodejs.org/api/packages.html#conditional-exports
      *
-     * @default CONDITIONS
+     * @default defaultConditions
+     */
+    conditions?: Condition[] | Set<Condition> | null | undefined;
+    /**
+     * URL of directory to resolve path aliases from.
+     *
+     * @see {@linkcode ModuleId}
+     *
+     * @default cwd()
      */
-    conditions?: Optional<Set<string> | string[]>;
+    cwd?: ModuleId | null | 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.
+     * An empty string (`''`) or `null` will remove a file extension.
      *
-     * @default undefined
+     * @see {@linkcode ChangeExtFn}
      */
-    ext?: ChangeExtFn | Nilable<string>;
+    ext?: ChangeExtFn | string | null | undefined;
     /**
      * Module extensions to probe for.
      *
-     * **Note**: Should be sorted by priority.
+     * > 👉 **Note**: Should be sorted by priority.
      *
-     * @default RESOLVE_EXTENSIONS
+     * @default defaultExtensions
      */
-    extensions?: Optional<Set<string> | string[]>;
+    extensions?: Set<string> | string[] | null | undefined;
     /**
-     * URL of module to resolve from.
+     * File system API.
      *
-     * @see {@linkcode ModuleId}
+     * @see {@linkcode FileSystem}
+     */
+    fs?: FileSystem | null | undefined;
+    /**
+     * List of legacy `main` fields.
      *
-     * @default import.meta.url
+     * > 👉 **Note**: Should be sorted by priority.
+     *
+     * @see {@linkcode MainField}
+     *
+     * @default defaultMainFields
      */
-    parent?: Optional<ModuleId>;
+    mainFields?: MainField[] | Set<MainField> | null | undefined;
     /**
      * Keep symlinks instead of resolving them.
-     *
-     * @default false
      */
-    preserveSymlinks?: Optional<boolean>;
+    preserveSymlinks?: boolean | null | undefined;
 }
 export type { ResolveModuleOptions as default };