@flex-development/mlly 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -12,13 +12,22 @@
 [![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.
+[ESM][node-esm] utilities for modern tooling — spec-compliant, developer-friendly, and fully typed.
 
 ## Contents
 
 - [What is this?](#what-is-this)
+- [Why this package?](#why-this-package)
 - [Install](#install)
-- [Use](#use)
+- [Quick Start](#quick-start)
+  - [Resolve like Node.js](#resolve-like-nodejs)
+  - [Resolve with custom conditions](#resolve-with-custom-conditions)
+  - [Resolve a directory index](#resolve-a-directory-index)
+  - [Resolve path aliases](#resolve-path-aliases)
+  - [Rewrite an extension](#rewrite-an-extension)
+  - [Use a custom file system](#use-a-custom-file-system)
+- [Use Cases](#use-cases)
+- [Design Goals](#design-goals)
 - [API](#api)
   - [`canParseUrl(input[, base])`](#canparseurlinput-base)
   - [`cwd()`](#cwd)
@@ -59,7 +68,6 @@
   - [`Awaitable<T>`](#awaitablet)
   - [`BufferEncodingMap`](#bufferencodingmap)
   - [`BufferEncoding`](#bufferencoding)
-  - [`ChangeExtFn<[Ext]>`](#changeextfnext)
   - [`ConditionMap`](#conditionmap)
   - [`Condition`](#condition)
   - [`Dot`](#dot)
@@ -67,8 +75,10 @@
   - [`EmptyObject`](#emptyobject)
   - [`EmptyString`](#emptystring)
   - [`Ext`](#ext)
+  - [`ExtensionRewrites`](#extensionrewrites)
   - [`FileContent`](#filecontent)
   - [`FileSystem`](#filesystem)
+  - [`GetNewExtension<[T]>`](#getnewextensiont)
   - [`GetSourceContext`](#getsourcecontext)
   - [`GetSourceHandler`](#getsourcehandler)
   - [`GetSourceHandlers`](#getsourcehandlers)
@@ -94,13 +104,44 @@
   - [`Stat`](#stat)
   - [`Stats`](#stats)
 - Additional Documentation
-  - [Resolution Algorithm](./docs/resolution-algorithm.md)
+  - [Resolution Algorithm][resolution-algorithm]
+- [Sponsors](#sponsors)
 - [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.
+`@flex-development/mlly` is a set of [ECMAScript module][node-esm] (ESM) utilities
+for building modern, Node.js-compatible tooling. It implements Node's [resolution algorithms][resolution-algorithm]
+and provides additional helpers for resolving modules in real-world projects.
+
+### Features
+
+- Comply with Node.js [resolution algorithms][resolution-algorithm]
+  - Resolve `exports` and `imports` maps (including subpaths + patterns)
+  - Support condition-based resolution (`development`, `production`, custom conditions, etc.)
+  - Support configurable `main` fields for legacy / fallback entrypoints
+- Enhance DX/UX with high-level [`resolveModule`](#resolvemoduletspecifier-parent-options) ergonomics
+  on top of spec-compliant resolution
+  - Extensionless and directory index resolution
+  - Path alias resolution (TypeScript-style mappings)
+  - Rewrite file extensions (useful for TS/MTS/CTS, build outputs, or dual publishing)
+  - Scopeless `@types/*` resolution (`unist` → `@types/unist`)
+- Utilities for specifier classification and conversion
+- Work with custom file system adapters (sync/async, in-memory, browser)
+
+## Why this package?
+
+Node's ESM support is powerful, but writing tooling around it can be painful.
+
+If you're building a CLI, bundler, runtime tool, or plugin system, you often need to:
+
+- resolve modules the same way Node does
+- support `exports` / `imports` correctly
+- work with custom resolution conditions
+- handle extensionless paths, directory indexes, and TypeScript configurations
+
+`@flex-development/mlly` provides these building blocks in a spec-aligned way,
+while also bridging gaps in developer experience.
 
 ## Install
 
@@ -133,67 +174,139 @@ In browsers with [`esm.sh`][esmsh]:
 </script>
 ```
 
-## Use
+## Quick Start
+
+### Resolve like Node.js
 
 ```ts
-import {
-  lookupPackageScope,
-  readPackageJson,
-  resolveModule,
-  type FileSystem
-} from '@flex-development/mlly'
-import pkg from '@flex-development/mlly/package.json' with { type: 'json' }
-import type { PackageJson } from '@flex-development/pkg-types'
-import nfs from 'node:fs'
+import { moduleResolve } from '@flex-development/mlly'
 
 /**
- * A file system API with both asynchronous and synchronous methods.
+ * The resolved URL.
  *
- * @const {FileSystem} fs
+ * @const {URL} resolved
  */
-const fs: FileSystem = {
-  readFile: nfs.promises.readFile,
-  realpath: nfs.promises.realpath,
-  stat: nfs.statSync
-}
+const resolved: URL = moduleResolve('typescript', import.meta.url)
+```
+
+### Resolve with custom conditions
+
+```ts
+import { moduleResolve } from '@flex-development/mlly'
 
 /**
- * The URL of the package directory.
+ * The resolved URL.
  *
- * @const {URL | null} scope
+ * @const {URL} resolved
  */
-const scope: URL | null = lookupPackageScope(import.meta.url, null, fs)
+const resolved: URL = moduleResolve('devlop', import.meta.url, ['development'])
+```
 
-console.dir(scope) // file:///Users/lex/Projects/flex-development/mlly/
+### Resolve a directory index
+
+```ts
+import { resolveModule } from '@flex-development/mlly'
 
 /**
- * The package manifest.
+ * The resolved URL.
  *
- * @const {PackageJson | null} manifest
+ * @const {URL} resolved
  */
-const manifest: PackageJson | null = await readPackageJson(
-  scope,
-  null,
-  import.meta.url,
-  fs
-)
+const resolved: URL = resolveModule('./src/lib', import.meta.url, {
+  extensions: ['.mts']
+})
+```
 
-console.dir(manifest?.name === pkg.name) // true
-console.dir(manifest) // `pkg`
+### Resolve path aliases
+
+```ts
+import { resolveModule, type Aliases } from '@flex-development/mlly'
+
+/**
+ * The path mappings dictionary.
+ *
+ * @const {Aliases} aliases
+ */
+const aliases: Aliases = {
+  '@/internal': './src/internal',
+  '@/internal/*': './src/internal/*'
+}
 
 /**
- * A fully resolved URL.
+ * The resolved directory URL.
+ *
+ * @const {URL} directory
+ */
+const directory: URL = resolveModule('@/internal', import.meta.url, { aliases })
+
+/**
+ * The resolved file URL.
+ *
+ * @const {URL} file
+ */
+const file: URL = resolveModule('@/internal/fs', import.meta.url, { aliases })
+
+console.dir(directory)
+console.dir(file)
+```
+
+### Rewrite an extension
+
+```ts
+import { resolveModule } from '@flex-development/mlly'
+
+/**
+ * The resolved URL.
  *
  * @const {URL} resolved
  */
-const resolved = resolveModule(pkg.name, import.meta.url, {
-  conditions: new Set(['mlly']),
-  ext: null
+const resolved: URL = resolveModule('./src/index.ts', import.meta.url, {
+  ext: { '.cts': '.cjs', '.mts': '.mjs', '.ts': '.js' }
 })
+```
 
-console.dir(resolved) // file:///Users/lex/Projects/flex-development/mlly/src/
+### Use a custom file system
+
+```ts
+import vfs from '#internal/vfs' // a virtual, async file system
+import { resolveModule } from '@flex-development/mlly'
+
+/**
+ * The resolved URL.
+ *
+ * @const {URL} resolved
+ */
+const resolved: URL = await resolveModule('react', import.meta.url, { fs: vfs })
 ```
 
+<br />
+
+> \:eyes: See the [API reference](#api) for lower-level building blocks and resolution primitives.
+
+## Use Cases
+
+`mlly` is designed for developers who need Node-compatible ESM resolution behavior.
+
+Common use cases include:
+
+- CLI tools that load user config files and/or plugins
+- Plugin systems that resolve modules relative to a project root
+- Bundlers and transpilers that need to interpret `exports`, `imports`, and `main` fields
+- Test runners and code execution tools
+- Monorepo tooling that resolves workspace dependencies
+- Runtime loaders and developer tools that operate on virtual filesystems
+- Framework tooling that needs resolution behavior matching Node.js
+
+## Design Goals
+
+This package is built around a few core goals:
+
+- Spec-compliant behavior where it matters (resolution rules, `exports`/`imports`)
+- Developer-friendly ergonomics for real-world projects and workflows
+- TypeScript-first APIs with strong typing and predictable return values
+- Composable building blocks (low-level primitives + high-level helpers)
+- Testability and deterministic behavior across environments
+
 ## API
 
 `mlly` exports the identifiers listed below.
@@ -204,7 +317,7 @@ There is no default export.
 
 Check if `input` can be parsed to a `URL`.
 
-> 👉 **Note**: If `input` is relative, `base` is required.
+> \:point\_right: **Note**: If `input` is relative, `base` is required.
 > If `input` is absolute, `base` is ignored.
 
 #### Parameters
@@ -270,7 +383,7 @@ const enum formats {
 
 Get the source code for a module.
 
-> 👉 **Note**: Returns a promise if the [handler](#getsourcehandler) for `id` is async.
+> \:point\_right: **Note**: Returns a promise if the [handler](#getsourcehandler) for `id` is async.
 
 #### Type Parameters
 
@@ -296,7 +409,7 @@ Get the source code for a module.
 
 Check if `value` is an *absolute specifier*.
 
-> 👉 **Note**: Only checks specifier syntax.\
+> \:point\_right: **Note**: Only checks specifier syntax.\
 > Does **not** guarantee the specifier references an existing module.
 
 #### Parameters
@@ -325,7 +438,7 @@ Check if `value` is a valid array index.
 
 Check if `value` is a *bare specifier*.
 
-> 👉 **Note**: Only checks specifier syntax.\
+> \:point\_right: **Note**: Only checks specifier syntax.\
 > Does **not** guarantee the specifier references an existing module.
 
 #### Parameters
@@ -341,7 +454,7 @@ Check if `value` is a *bare specifier*.
 
 Check if a directory exists.
 
-> 👉 **Note**: Returns a promise if `fs.stat` is async.
+> \:point\_right: **Note**: Returns a promise if `fs.stat` is async.
 
 #### Type Parameters
 
@@ -363,7 +476,7 @@ Check if a directory exists.
 
 Check if a file exists.
 
-> 👉 **Note**: Returns a promise if `fs.stat` is async.
+> \:point\_right: **Note**: Returns a promise if `fs.stat` is async.
 
 #### Type Parameters
 
@@ -385,7 +498,7 @@ Check if a file exists.
 
 Check if `value` is an [`imports`][subpath-imports] subpath.
 
-> 👉 **Note**: Only checks specifier syntax.\
+> \:point\_right: **Note**: Only checks specifier syntax.\
 > Does **not** guarantee the specifier references an existing module.
 
 #### Parameters
@@ -414,7 +527,7 @@ Check if `value` is a module id.
 
 Check if `value` is a *relative specifier*.
 
-> 👉 **Note**: Only checks specifier syntax.\
+> \:point\_right: **Note**: Only checks specifier syntax.\
 > Does **not** guarantee the specifier references an existing module.
 
 #### Parameters
@@ -436,7 +549,7 @@ Resolve a [`main`][main]-like package entry point.
 
 Implements the [`LEGACY_MAIN_RESOLVE`][algorithm-legacy-main-resolve] resolution algorithm.
 
-> 👉 **Note**: Returns a promise if `fs.stat` is async.
+> \:point\_right: **Note**: Returns a promise if `fs.stat` is async.
 
 #### Type Parameters
 
@@ -471,7 +584,7 @@ Get the package scope URL for a module `url`.
 
 Implements the [`LOOKUP_PACKAGE_SCOPE`][algorithm-lookup-package-scope] algorithm.
 
-> 👉 **Note**: Returns a promise if `fs.stat` is async.
+> \:point\_right: **Note**: Returns a promise if `fs.stat` is async.
 
 #### Overloads
 
@@ -522,8 +635,8 @@ Resolve a module `specifier`.
 
 Implements the [`ESM_RESOLVE`][algorithm-esm-resolve] algorithm.
 
-> 👉 **Note**: Returns a promise if `fs.realpath` or `fs.stat` is async, or one the following methods returns a promise:
-> [`packageImportsResolve`](#packageimportsresolvetspecifier-parent-conditions-mainfields-fs),
+> \:point\_right: **Note**: Returns a promise if `fs.realpath` or `fs.stat` is async, or one the following methods
+> returns a promise: [`packageImportsResolve`](#packageimportsresolvetspecifier-parent-conditions-mainfields-fs),
 > [`packageResolve`](#packageresolvetspecifier-parent-conditions-mainfields-fs).
 
 #### Type Parameters
@@ -562,7 +675,7 @@ Resolve a package export.
 
 Implements the [`PACKAGE_EXPORTS_RESOLVE`][algorithm-package-exports-resolve] algorithm.
 
-> 👉 **Note**: Never returns a promisee.
+> \:point\_right: **Note**: Never returns a promisee.
 
 #### Type Parameters
 
@@ -599,7 +712,7 @@ Resolve a package export or import.
 
 Implements the [`PACKAGE_IMPORTS_EXPORTS_RESOLVE`][algorithm-package-imports-exports-resolve] algorithm.
 
-> 👉 **Note**: Returns a promise if
+> \:point\_right: **Note**: Returns a promise if
 > [`packageTargetResolve`](#packagetargetresolvetpackageurl-target-subpath-patternmatch-isimports-conditions-mainfields-parent-fs),
 > returns a promise.
 
@@ -643,7 +756,7 @@ Resolve a package import.
 
 Implements the [`PACKAGE_IMPORTS_RESOLVE`][algorithm-package-imports-resolve] algorithm.
 
-> 👉 **Note**: Returns a promise if [`lookupPackageScope`](#lookuppackagescopeturl-end-fs),
+> \:point\_right: **Note**: Returns a promise if [`lookupPackageScope`](#lookuppackagescopeturl-end-fs),
 > [`packageImportsExportsResolve`](#packageimportsexportsresolvetmatchkey-matchobject-packageurl-isimports-conditions-mainfields-parent-fs),
 > or [`readPackageJson`](#readpackagejsontid-specifier-parent-fs) returns a promise.
 
@@ -690,7 +803,7 @@ Implements the [`PACKAGE_RESOLVE`][algorithm-package-resolve] algorithm.
 > package name, or a specific feature module within a package prefixed by the package name.
 > Including the file extension is only necessary for packages without an [`exports`][exports] field.
 
-> 👉 **Note**: Returns a promise if `fs.stat` is async or one of the following methods returns a promise:
+> \:point\_right: **Note**: Returns a promise if `fs.stat` is async or one of the following methods returns a promise:
 > [`legacyMainResolve`](#legacymainresolvetpackageurl-manifest-mainfields-parent-fs),
 > [`packageExportsResolve`](#packageexportsresolvetpackageurl-subpath-exports-conditions-parent-fs),
 > [`packageSelfResolve`](#packageselfresolvetname-subpath-parent-conditions-fs), or
@@ -735,7 +848,7 @@ Resolve the self-import of a package.
 
 Implements the [`PACKAGE_SELF_RESOLVE`][algorithm-package-self-resolve] algorithm.
 
-> 👉 **Note**: Returns a promise if [`lookupPackageScope`](#lookuppackagescopeturl-end-fs),
+> \:point\_right: **Note**: Returns a promise if [`lookupPackageScope`](#lookuppackagescopeturl-end-fs),
 > [`packageExportsResolve`](#packageexportsresolvetpackageurl-subpath-exports-conditions-parent-fs),
 > or [`readPackageJson`](#readpackagejsontid-specifier-parent-fs) returns a promise.
 
@@ -772,7 +885,7 @@ Resolve a package target.
 
 Implements the [`PACKAGE_TARGET_RESOLVE`][algorithm-package-target-resolve] algorithm.
 
-> 👉 **Note**: Returns a promise if `target` is internal to the package and
+> \:point\_right: **Note**: Returns a promise if `target` is internal to the package and
 > [`packageResolve`](#packageresolvetspecifier-parent-conditions-mainfields-fs) returns a promise.
 
 #### Type Parameters
@@ -851,7 +964,7 @@ Read a `package.json` file.
 
 Implements the [`READ_PACKAGE_JSON`][algorithm-read-package-json] algorithm.
 
-> 👉 **Note**: Returns a promise if `fs.readFile` or `fs.stat` is async.
+> \:point\_right: **Note**: Returns a promise if `fs.readFile` or `fs.stat` is async.
 
 #### Overloads
 
@@ -886,7 +999,7 @@ function readPackageJson<T extends Awaitable<PackageJson | null>>(
   — the url of the package directory, the `package.json` file, or a module in the same directory as a `package.json`
 - `specifier` (`string` | `null` | `undefined`)
   — the module specifier that initiated the reading of the `package.json` file
-  > 👉 **note**: should be a `file:` url if `parent` is not a url
+  > \:point\_right: **note**: should be a `file:` url if `parent` is not a url
 - `parent` ([`ModuleId`](#moduleid) | `null` | `undefined`)
   — the url of the parent module
 - `fs` ([`FileSystem`](#filesystem) | `null` | `undefined`)
@@ -909,7 +1022,7 @@ Resolve an aliased `specifier`.
 - `specifier` (`string`)
   — the specifier using an alias
 - `options` ([`ResolveAliasOptions`](#resolvealiasoptions) | `null` | `undefined`)
-  — alias resolution options
+  — options for alias resolution
 
 #### Returns
 
@@ -923,13 +1036,12 @@ Implements the [`ESM_RESOLVE`][algorithm-esm-resolve] algorithm, mostly \:wink:.
 
 Adds support for:
 
-- Changing file extensions
-- Directory index resolution
-- Extensionless file resolution
+- Extensionless and directory index resolution
 - Path alias resolution
+- Rewrite file extensions
 - Scopeless `@types/*` resolution (i.e. `unist` -> `@types/unist`)
 
-> 👉 **Note**: Returns a promise if
+> \:point\_right: **Note**: Returns a promise if
 > [`moduleResolve`](#moduleresolvetspecifier-parent-conditions-mainfields-preservesymlinks-fs) returns a promise.
 
 #### Type Parameters
@@ -944,7 +1056,7 @@ Adds support for:
 - `parent` ([`ModuleId`](#moduleid))
   — the url of the parent module
 - `options` ([`ResolveModuleOptions`](#resolvemoduleoptions))
-  — module resolution options
+  — options for module resolution
 
 #### Returns
 
@@ -973,7 +1085,7 @@ The URL of the file system root.
 
 Turn `url` into a *relative specifier*.
 
-> 👉 **Note**: The relative specifier will only have a file extension if `specifier` also has an extension.
+> \:point\_right: **Note**: The relative specifier will only have a file extension if `specifier` also has an extension.
 
 #### Parameters
 
@@ -990,7 +1102,7 @@ Turn `url` into a *relative specifier*.
 
 Convert `id` to a `URL`.
 
-> 👉 **Note**: If `id` cannot be parsed as a `URL` and is also not a [builtin module][builtin-module],
+> \:point\_right: **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].
 
 #### Parameters
@@ -1040,7 +1152,7 @@ type Awaitable<T> = PromiseLike<T> | T
 #### Type Parameters
 
 - `T` (`any`)
-  - the value
+  — the value
 
 ### `BufferEncodingMap`
 
@@ -1067,34 +1179,6 @@ They will be added to this union automatically.
 type BufferEncoding = BufferEncodingMap[keyof BufferEncodingMap]
 ```
 
-### `ChangeExtFn<[Ext]>`
-
-Get a new file extension for `url` (`type`).
-
-Returning an empty string (`''`), `null`, or `undefined` will remove the current file extension.
-
-```ts
-type ChangeExtFn<
-  Ext extends string | null | undefined = string | null | undefined
-> = (this: void, url: URL, specifier: string) => Ext
-```
-
-#### Type Parameters
-
-- `Ext` (`string` | `null` | `undefined`, optional)
-  — the new file extension
-
-#### Parameters
-
-- `url` (`URL`)
-  — the resolved module URL
-- `specifier` (`string`)
-  — the module specifier being resolved
-
-#### Returns
-
-(`Ext`) The new file extension
-
 ### `ConditionMap`
 
 Registry of export/import conditions (`interface`).
@@ -1160,6 +1244,20 @@ A file extension (`type`).
 type Ext = `${Dot}${string}`
 ```
 
+### `ExtensionRewrites`
+
+Record, where each key is the file extension of a module specifier
+and each value is a replacement file extension (`type`).
+
+> 👉 **Note**: Replacement file extensions are normalized and do not need to begin with a dot character (`'.'`);
+> falsy values will remove an extension.
+
+```ts
+type ExtensionRewrites = {
+  [K in EmptyString | Ext]?: string | false | null | undefined
+}
+```
+
 ### `FileContent`
 
 Union of values that can occur where file content is expected (`type`).
@@ -1181,6 +1279,38 @@ The file system API (`interface`).
 - `stat` ([`Stat`](#stat))
   — get information about a directory or file
 
+### `GetNewExtension<[T]>`
+
+Get a new file extension for a `url` (`type`).
+
+Returning an empty string (`''`), `false`, `null`, or `undefined` will remove the current file extension.
+
+```ts
+type GetNewExtension<
+  T extends string | false | null | undefined =
+    | string
+    | false
+    | null
+    | undefined
+> = (this: void, url: URL, specifier: string) => T
+```
+
+#### Type Parameters
+
+- `T` (`string` | `false` | `null` | `undefined`, optional)
+  — the new file extension
+
+#### Parameters
+
+- `url` (`URL`)
+  — the resolved module URL
+- `specifier` (`string`)
+  — the module specifier being resolved
+
+#### Returns
+
+(`T`) The new file extension
+
 ### `GetSourceContext`
 
 Source code retrieval context (`interface`).
@@ -1240,7 +1370,7 @@ Options for retrieving source code (`interface`).
 
 - `encoding?` ([`BufferEncoding`](#bufferencoding) | `null` | `undefined`)
   — the encoding of the result
-  > 👉 **note**: used when the `file:` handler is called
+  > \:point\_right: **note**: used when the `file:` handler is called
 - `format?` ([`ModuleFormat`](#moduleformat) | `null` | `undefined`)
   — the module format hint
 - `fs?` ([`FileSystem`](#filesystem) | `null` | `undefined`)
@@ -1282,7 +1412,7 @@ type List<T = unknown> = ReadonlySet<T> | readonly T[]
 #### Type Parameters
 
 - `T` (`any`, optional)
-  — list item type
+  — the list item type
 
 ### `MainFieldMap`
 
@@ -1443,7 +1573,7 @@ Read the entire contents of a file (`interface`).
 
 Compute a canonical pathname by resolving `.`, `..`, and symbolic links (`interface`).
 
-> 👉 **Note**: A canonical pathname is not necessarily unique.
+> \:point\_right: **Note**: A canonical pathname is not necessarily unique.
 > Hard links and bind mounts can expose an entity through many pathnames.
 
 #### Type Parameters
@@ -1471,7 +1601,7 @@ Options for path alias resolution (`interface`).
   if `true`, the resolved specifier will be a [`file:` URL][file-url]
 - `aliases?` ([`Aliases`](#aliases) | `null` | `undefined`)
   — the path mappings dictionary
-  > 👉 **note**: paths should be relative to `cwd`
+  > \:point\_right: **note**: paths should be relative to `cwd`
 - `cwd?` ([`ModuleId`](#moduleid) | `null` | `undefined`)
   — the url of the directory to resolve non-absolute modules from
   - **default**: [`cwd()`](#cwd)
@@ -1480,33 +1610,36 @@ Options for path alias resolution (`interface`).
 
 ### `ResolveModuleOptions`
 
-Options for path alias resolution (`interface`).
+Options for module resolution (`interface`).
 
 #### Properties
 
 - `aliases?` ([`Aliases`](#aliases) | `null` | `undefined`)
   — the path mappings dictionary
-  > 👉 **note**: paths should be relative to `cwd`
+  > \:point\_right: **note**: paths should be relative to `cwd`
 - `conditions?` ([`List<Condition>`](#condition) | `null` | `undefined`)
   — the list of export/import conditions
   - **default**: [`defaultConditions`](#defaultconditions)
-  > 👉 **note**: should be sorted by priority
+  > \:point\_right: **note**: should be sorted by priority
 - `cwd?` ([`ModuleId`](#moduleid) | `null` | `undefined`)
   — the url of the directory to resolve path `aliases` from
   - **default**: [`cwd()`](#cwd)
-- `ext?` ([`ChangeExtFn`](#changeextfnext) | `string` | `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
+  <!--lint disable-->
+- `ext?` ([`ExtensionRewrites`](#extensionrewrites) | [`GetNewExtension`](#getnewextensiont) | `false` | `string` | `null` | `undefined`)
+  — a replacement file extension, a record of replacement file extensions, or a function that returns a replacement file extension
+  <!--lint enable-->
+  > \:point\_right: **note**: replacement file extensions are normalized and do not need to begin
+  > with a dot character (`'.'`); an empty string (`''`), `false`, or `null` will remove an extension
 - `extensions?` ([`List<string>`](#listt) | `null` | `undefined`)
   — the module extensions to probe for
   - **default**: [`defaultExtensions`](#defaultextensions)
-  > 👉 **note**: should be sorted by priority
+  > \:point\_right: **note**: should be sorted by priority
 - `fs?` ([`FileSystem`](#filesystem) | `null` | `undefined`)
   — the file system api
 - `mainFields?` ([`List<MainField>`](#mainfield) | `null` | `undefined`)
   — the list of legacy `main` fields
   - **default**: [`defaultMainFields`](#defaultmainfields)
-  > 👉 **note**: should be sorted by priority
+  > \:point\_right: **note**: should be sorted by priority
 - `preserveSymlinks?` (`boolean` | `null` | `undefined`)
   — whether to keep symlinks instead of resolving them
 
@@ -1539,12 +1672,16 @@ An object describing a directory or file (`interface`).
 - `isFile` ([`IsFile`](#isfile))
   — check if the stats object describes a file
 
+## Sponsors
+
+If you find this package helpful, consider sponsoring to support maintenance, tests, and long-term stability.
+
 ## 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.
+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.
 
 [algorithm-esm-resolve]: ./docs/resolution-algorithm.md#esm_resolvespecifier-parent-conditions-mainfields-preservesymlinks-extensionformatmap
 
@@ -1604,6 +1741,8 @@ community you agree to abide by its terms.
 
 [pkg-package-json]: https://github.com/flex-development/pkg-types/blob/main/src/package-json.ts
 
+[resolution-algorithm]: ./docs/resolution-algorithm.md
+
 [subpath-imports]: https://nodejs.org/api/packages.html#subpath-imports
 
 [typescript]: https://www.typescriptlang.org