feat(lib)!: [resolveModule] support extension rewrite map

- `ChangeExtFn` -> `GetNewExtension`

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>

Author: unicornware

README.md

@@ -23,6 +23,7 @@
   - [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)
@@ -67,16 +68,17 @@
   - [`Awaitable<T>`](#awaitablet)
   - [`BufferEncodingMap`](#bufferencodingmap)
   - [`BufferEncoding`](#bufferencoding)
-  - [`ChangeExtFn<[Ext]>`](#changeextfnext)
   - [`ConditionMap`](#conditionmap)
   - [`Condition`](#condition)
   - [`Dot`](#dot)
   - [`EmptyArray`](#emptyarray)
   - [`EmptyObject`](#emptyobject)
   - [`EmptyString`](#emptystring)
   - [`Ext`](#ext)
+  - [`ExtensionRewrites`](#extensionrewrites)
   - [`FileContent`](#filecontent)
   - [`FileSystem`](#filesystem)
+  - [`GetNewExtension<[T]>`](#getnewextensiont)
   - [`GetSourceContext`](#getsourcecontext)
   - [`GetSourceHandler`](#getsourcehandler)
   - [`GetSourceHandlers`](#getsourcehandlers)
@@ -215,6 +217,39 @@ const resolved: URL = resolveModule('./src/lib', import.meta.url, {
 })
 ```
 
+### 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/*'
+}
+
+/**
+ * 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
@@ -987,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
 
@@ -1021,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
 
@@ -1144,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`).
@@ -1237,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`).
@@ -1258,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`).
@@ -1557,7 +1610,7 @@ Options for path alias resolution (`interface`).
 
 ### `ResolveModuleOptions`
 
-Options for path alias resolution (`interface`).
+Options for module resolution (`interface`).
 
 #### Properties
 
@@ -1571,9 +1624,12 @@ Options for path alias resolution (`interface`).
 - `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.
-  > \:point\_right: **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)

package.json

@@ -72,9 +72,7 @@
       "default": "./dist/interfaces/*.d.mts"
     },
     "#internal/fs": {
-      "types": {
-        "mlly": "./src/internal/fs.d.mts"
-      },
+      "types": "./src/internal/fs.d.mts",
       "browser": {
         "mlly": "./src/internal/fs.browser.mts",
         "default": "./dist/internal/fs.browser.mjs"

src/interfaces/__tests__/resolve-module-options.spec-d.mts

@@ -5,9 +5,10 @@
 
 import type TestSubject from '#interfaces/resolve-module-options'
 import type {
-  ChangeExtFn,
   Condition,
+  ExtensionRewrites,
   FileSystem,
+  GetNewExtension,
   List,
   MainField
 } from '@flex-development/mlly'
@@ -24,10 +25,12 @@ describe('unit-d:interfaces/ResolveModuleOptions', () => {
       .toEqualTypeOf<Nilable<List<Condition>>>()
   })
 
-  it('should match [ext?: ChangeExtFn | string | null | undefined]', () => {
-    expectTypeOf<TestSubject>()
-      .toHaveProperty('ext')
-      .toEqualTypeOf<Nilable<ChangeExtFn | string>>()
+  it('should match [ext?: ExtensionRewrites | GetNewExtension | string | false | null | undefined]', () => {
+    // Arrange
+    type Expect = Nilable<ExtensionRewrites | GetNewExtension | string | false>
+
+    // Expect
+    expectTypeOf<TestSubject>().toHaveProperty('ext').toEqualTypeOf<Expect>()
   })
 
   it('should match [extensions?: List<string> | null | undefined]', () => {

src/interfaces/resolve-module-options.mts

@@ -5,16 +5,17 @@
 
 import type {
   Aliases,
-  ChangeExtFn,
   Condition,
+  ExtensionRewrites,
   FileSystem,
+  GetNewExtension,
   List,
   MainField,
   ModuleId
 } from '@flex-development/mlly'
 
 /**
- * Module resolution options.
+ * Options for module resolution.
  */
 interface ResolveModuleOptions {
   /**
@@ -49,14 +50,17 @@ interface ResolveModuleOptions {
   cwd?: ModuleId | null | undefined
 
   /**
-   * A replacement file extension or a function that returns a file extension.
+   * A replacement file extension, a record of replacement file extensions,
+   * or a function that returns a replacement file extension.
    *
-   * > 👉 **Note**: An empty string (`''`) or `null` will
-   * > remove a file extension.
+   * > 👉 **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.
    *
-   * @see {@linkcode ChangeExtFn}
+   * @see {@linkcode ExtensionRewrites}
+   * @see {@linkcode GetNewExtension}
    */
-  ext?: ChangeExtFn | string | null | undefined
+  ext?: ExtensionRewrites | GetNewExtension | string | false | null | undefined
 
   /**
    * The module extensions to probe for.

src/lib/__snapshots__/node/resolve-module.snap

@@ -26,7 +26,7 @@ exports[`unit:lib/resolveModule > fs (default) > should return resolved URL ("mo
 
 exports[`unit:lib/resolveModule > fs (default) > should return resolved URL ("node:test") 1`] = `"node:test"`;
 
-exports[`unit:lib/resolveModule > fs (default) > should return resolved URL ("subpath-exports/lib/a.js") 1`] = `file://\${process.cwd()}/__fixtures__/node_modules/subpath-exports/lib/a.js`;
+exports[`unit:lib/resolveModule > fs (default) > should return resolved URL ("subpath-exports/lib/a.js") 1`] = `file://\${process.cwd()}/__fixtures__/node_modules/subpath-exports/lib/a`;
 
 exports[`unit:lib/resolveModule > fs (default) > should return resolved URL ("unist") 1`] = `file://\${process.cwd()}/node_modules/@types/unist/index.d.ts`;
 
@@ -56,6 +56,6 @@ exports[`unit:lib/resolveModule > fs (only async) > should return resolved URL (
 
 exports[`unit:lib/resolveModule > fs (only async) > should return resolved URL ("node:test") 1`] = `"node:test"`;
 
-exports[`unit:lib/resolveModule > fs (only async) > should return resolved URL ("subpath-exports/lib/a.js") 1`] = `file://\${process.cwd()}/__fixtures__/node_modules/subpath-exports/lib/a.js`;
+exports[`unit:lib/resolveModule > fs (only async) > should return resolved URL ("subpath-exports/lib/a.js") 1`] = `file://\${process.cwd()}/__fixtures__/node_modules/subpath-exports/lib/a`;
 
 exports[`unit:lib/resolveModule > fs (only async) > should return resolved URL ("unist") 1`] = `file://\${process.cwd()}/node_modules/@types/unist/index.d.ts`;

src/lib/__tests__/resolve-module.spec.mts

@@ -52,7 +52,7 @@ describe('unit:lib/resolveModule', () => {
       [pkg.name + '/package.json', import.meta.url],
       [pkgKronk.name, import.meta.url],
       [pkgPathe.name + '/dot', import.meta.url],
-      [subpathExports.name + '/lib/a.js', parent]
+      [subpathExports.name + '/lib/a.js', parent, { ext: { '.js': false } }]
     ])('should return resolved URL (%j)', async (
       specifier,
       parent,

src/lib/resolve-alias.mts

@@ -24,7 +24,7 @@ export default resolveAlias
  * @param {string} specifier
  *  The specifier using an alias
  * @param {ResolveAliasOptions | null | undefined} [options]
- *  Alias resolution options
+ *  Options for alias resolution
  * @return {string | null}
  *  The specifier of the aliased module
  */