@flex-development/mlly 1.0.0-alpha.2 → 1.0.0-alpha.20

package/README.md

@@ -1,17 +1,197 @@
-# mlly
+# \:gear: mlly
 
-[![conventional commits](https://img.shields.io/badge/conventional%20commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
-[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
-[![module type: esm](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://github.com/voxpelli/badges-cjs-esm)
+[![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/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)
-[![typescript](https://badgen.net/badge/-/typescript?color=2a72bc&icon=typescript&label)](https://typescriptlang.org)
+[![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][node-esm] utilities.
+
+## Contents
+
+- [What is this?](#what-is-this)
+- [Install](#install)
+- [Use](#use)
+- [API](#api)
+- [Types](#types)
+- [Contribute](#contribute)
+
+## 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,
+  legacyMainResolveSync,
+  lookupPackageScope,
+  moduleResolve,
+  moduleResolveSync,
+  packageExportsResolve,
+  packageExportsResolveSync,
+  packageImportsExportsResolve,
+  packageImportsExportsResolveSync,
+  packageImportsResolve,
+  packageImportsResolveSync,
+  packageResolve,
+  packageResolveSync,
+  packageSelfResolve,
+  packageSelfResolveSync,
+  packageTargetResolve,
+  packageTargetResolveSync,
+  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`
+  - `legacyMainResolveSync`
+  - `moduleResolve`
+  - `moduleResolveSync`
+  - `packageExportsResolve`
+  - `packageExportsResolveSync`
+  - `packageImportsExportsResolve`
+  - `packageImportsExportsResolveSync`
+  - `packageImportsResolve`
+  - `packageImportsResolveSync`
+  - `packageResolve`
+  - `packageResolveSync`
+  - `packageSelfResolve`
+  - `packageSelfResolveSync`
+  - `packageTargetResolve`
+  - `packageTargetResolveSync`
+- [`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
 
-> [ECMAScript module][1] utilities.
+[esmsh]: https://esm.sh
 
-## Getting Started
+[node-esm]: https://nodejs.org/api/esm.html
 
-See the [docs][2] for install and usage instructions.
+[typescript]: https://www.typescriptlang.org
 
-[1]: https://nodejs.org/api/esm.html
-[2]: https://mlly.vercel.app/
+[yarn]: https://yarnpkg.com

package/dist/index.d.mts

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

package/dist/index.mjs

@@ -1,4 +1 @@
-export * from "./constants.mjs";
-export * from "./interfaces/index.mjs";
-export * from "./lib/index.mjs";
-export * from "./types/index.mjs";
+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,54 @@
+/**
+ * @file Interfaces - FileSystem
+ * @module mlly/interfaces/FileSystem
+ */
+import type { ModuleId, Stats } from '@flex-development/mlly';
+/**
+ * File system API.
+ */
+interface FileSystem {
+    /**
+     * Get the contents of `id`.
+     *
+     * @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 {Buffer | string}
+     *  File contents
+     */
+    readFileSync(this: void, id: ModuleId): Buffer | string;
+    /**
+     * Get the resolved pathname for `id`.
+     *
+     * @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 {string}
+     *  Resolved pathname
+     */
+    realpathSync(this: void, id: ModuleId): string;
+    /**
+     * Get information about a directory or file.
+     *
+     * @see {@linkcode ModuleId}
+     * @see {@linkcode Stats}
+     *
+     * @this {void}
+     *
+     * @param {ModuleId} id
+     *  The path or `file:` URL to handle
+     * @return {Stats}
+     *  Info about `id`
+     */
+    statSync(this: void, id: ModuleId): Stats;
+}
+export type { FileSystem as default };

package/dist/interfaces/index.d.mts

@@ -1,12 +1,14 @@
 /**
- * @file Interfaces
+ * @file Entry Point - Interfaces
  * @module mlly/interfaces
  */
-export type { default as DynamicImport } from './import-dynamic.mjs';
-export type { default as StaticImport } from './import-static.mjs';
-export type { default as ResolveOptions } from './options-resolve.mjs';
-export type { default as ResolveAliasOptions } from './options-resolve-alias.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

@@ -0,0 +1,47 @@
+/**
+ * @file Interfaces - GetSourceOptions
+ * @module mlly/interfaces/GetSourceOptions
+ */
+import type { FileSystem, GetSourceHandlers, ModuleFormat } from '@flex-development/mlly';
+/**
+ * Source code retrieval options.
+ */
+interface GetSourceOptions {
+    /**
+     * Module format hint.
+     *
+     * @see {@linkcode ModuleFormat}
+     */
+    format?: ModuleFormat | null | undefined;
+    /**
+     * File system API.
+     *
+     * @see {@linkcode FileSystem}
+     */
+    fs?: FileSystem | null | undefined;
+    /**
+     * URL handler map.
+     *
+     * @see {@linkcode GetSourceHandlers}
+     */
+    handlers?: GetSourceHandlers | null | undefined;
+    /**
+     * 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.
+     *
+     * > 👉 **Note**: Only applicable if {@linkcode network} is enabled.
+     */
+    req?: RequestInit | null | undefined;
+    /**
+     * List of supported URL schemes.
+     *
+     * @default ['data','file','http','https','node']
+     */
+    schemes?: Set<string> | readonly string[] | null | undefined;
+}
+export type { GetSourceOptions as default };

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

@@ -2,68 +2,40 @@
  * @file Interfaces - ResolveAliasOptions
  * @module mlly/interfaces/ResolveAliasOptions
  */
-import type { OneOrMany } from '@flex-development/tutils';
+import type { Aliases, ModuleId } from '@flex-development/mlly';
 /**
  * Path alias resolution options.
- *
- * @see https://github.com/dividab/tsconfig-paths
  */
 interface ResolveAliasOptions {
     /**
-     * Base directory to resolve non-absolute module names.
+     * Return resolved module URL as absolute specifier (a [`file:` URL][1]).
      *
-     * @see https://www.typescriptlang.org/tsconfig#baseUrl
+     * [1]: https://nodejs.org/api/esm.html#file-urls
      *
-     * @default process.cwd()
+     * @see https://nodejs.org/api/esm.html#terminology
      */
-    baseUrl?: string;
+    absolute?: boolean | null | undefined;
     /**
-     * Module extensions to probe for.
-     *
-     * **Note**: Should be sorted by priority.
-     *
-     * @default RESOLVE_EXTENSIONS
-     */
-    extensions?: string[] | readonly string[];
-    /**
-     * Checks for the existence of a file at `path`.
-     *
-     * @param {string} path - Path to check
-     * @return {boolean} `true` if file exists, `false` otherwise
-     */
-    fileExists?(this: void, path: string): boolean;
-    /**
-     * `package.json` fields to check when resolving modules.
+     * Path mappings.
      *
-     * A nested field can be selected by passing an array of field names.
+     * > 👉 **Note**: Paths should be relative to {@linkcode cwd}.
      *
-     * @default ['main', 'module']
-     */
-    mainFields?: OneOrMany<string>[];
-    /**
-     * Absolute path to file containing path alias.
+     * @see {@linkcode Aliases}
      */
-    parent?: string;
+    aliases?: Aliases | null | undefined;
     /**
-     * Path mappings.
+     * URL of directory to resolve non-absolute modules from.
      *
-     * **Note**: Should be relative to {@link baseUrl}.
+     * @see {@linkcode ModuleId}
      *
-     * @see https://www.typescriptlang.org/tsconfig#paths
-     *
-     * @default {}
+     * @default cwd()
      */
-    paths?: Record<string, string[]>;
+    cwd?: ModuleId | null | undefined;
     /**
-     * Synchronously returns the contents of `filename`.
+     * URL of parent module.
      *
-     * @param {string} filename - Filename
-     * @return {string} Contents of `filename`
-     */
-    readFile?(this: void, filename: string): string;
-    /**
-     * Absolute path to tsconfig file.
+     * @see {@linkcode ModuleId}
      */
-    tsconfig?: string;
+    parent?: ModuleId | null | undefined;
 }
 export type { ResolveAliasOptions as default };

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

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

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

@@ -0,0 +1,35 @@
+/**
+ * @file Interfaces - ProtocolMap
+ * @module mlly/interfaces/ProtocolMap
+ */
+/**
+ * URL protocol registry.
+ *
+ * @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
+ */
+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/stats.d.mts

@@ -0,0 +1,28 @@
+/**
+ * @file Interfaces - Stats
+ * @module mlly/interfaces/Stats
+ */
+/**
+ * File system metadata.
+ */
+interface Stats {
+    /**
+     * Check if the stats object describes a file system directory.
+     *
+     * @this {void}
+     *
+     * @return {boolean}
+     *  `true` if stats object describes directory, `false` otherwise
+     */
+    isDirectory(this: void): boolean;
+    /**
+     * Check if the stats object describes a regular file.
+     *
+     * @this {void}
+     *
+     * @return {boolean}
+     *  `true` if stats object describes regular file, `false` otherwise
+     */
+    isFile(this: void): boolean;
+}
+export type { Stats as default };