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

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [1.0.0-beta.6](https://github.com/flex-development/mlly/compare/1.0.0-beta.5...1.0.0-beta.6) (2026-02-12)
+
+### ⚠ BREAKING CHANGES
+
+- **lib:** [`resolveModule`] support extension rewrite map
+
+### :package: Build
+
+- [[`38c36b4`](https://github.com/flex-development/mlly/commit/38c36b4a6df62494e87aeb6ba7d9ce8466ab22cc)] **deps-dev:** Bump vite-tsconfig-paths from 6.1.0 to 6.1.1 ([#975](https://github.com/flex-development/mlly/issues/975))
+
+### :sparkles: Features
+
+- [[`efdcc40`](https://github.com/flex-development/mlly/commit/efdcc40de2380932f7cfac80b0d7e96a2cdb8e48)] **lib:** [`resolveModule`] support extension rewrite map
+
 ## [1.0.0-beta.5](https://github.com/flex-development/mlly/compare/1.0.0-beta.4...1.0.0-beta.5) (2026-02-12)
 
 ### :package: Build
@@ -1312,3 +1326,4 @@
 
 
 
+

package/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,7 +68,6 @@
   - [`Awaitable<T>`](#awaitablet)
   - [`BufferEncodingMap`](#bufferencodingmap)
   - [`BufferEncoding`](#bufferencoding)
-  - [`ChangeExtFn<[Ext]>`](#changeextfnext)
   - [`ConditionMap`](#conditionmap)
   - [`Condition`](#condition)
   - [`Dot`](#dot)
@@ -75,8 +75,10 @@
   - [`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/dist/index.d.mts

@@ -605,7 +605,7 @@ declare function readPackageJson<T extends Awaitable<PackageJson | null>>(this:
  * @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
  */
@@ -646,7 +646,7 @@ declare function resolveAlias(this: void, specifier: string, options?: ResolveAl
  * @param {ModuleId} parent
  *  The URL of the parent module
  * @param {ResolveModuleOptions | null | undefined} [options]
- *  Module resolution options
+ *  Options for module resolution
  * @return {T}
  *  The resolved URL
  * @throws {NodeError}
@@ -1109,35 +1109,6 @@ type Awaitable<T> = PromiseLike<T> | T;
  */
 type BufferEncoding = BufferEncodingMap[keyof BufferEncodingMap];
 
-/**
- * @file Type Aliases - ChangeExtFn
- * @module mlly/types/ChangeExtFn
- */
-/**
- * Get a new file extension for `url`.
- *
- * Returning an empty string (`''`), `null`, or `undefined` will remove the
- * current file extension.
- *
- * ::: info
- * The new file extension need not begin with a dot character (`'.'`).
- * :::
- *
- * @see {@linkcode URL}
- * @see https://github.com/flex-development/pathe/tree/1.0.3#changeextpath-string-ext-nullablestring-string
- *
- * @template {string | null | undefined} Ext
- *  The new file extension
- *
- * @param {URL} url
- *  The resolved module URL
- * @param {string} specifier
- *  The module specifier being resolved
- * @return {Ext}
- *  The new file extension
- */
-type ChangeExtFn<Ext extends string | null | undefined = string | null | undefined> = (this: void, url: URL, specifier: string) => Ext;
-
 /**
  * @file Type Aliases - Condition
  * @module mlly/types/Condition
@@ -1209,6 +1180,25 @@ type EmptyString = '';
  */
 type Ext = `${Dot}${string}`;
 
+/**
+ * @file Type Aliases - ExtensionRewrites
+ * @module mlly/types/ExtensionRewrites
+ */
+
+/**
+ * Record, where each key is the file extension of a module specifier and
+ * each value is a replacement file extension.
+ *
+ * > 👉 **Note**: Replacement file extensions are normalized and do not need to
+ * > begin with a dot character (`'.'`); falsy values will remove an extension.
+ *
+ * @see {@linkcode EmptyString}
+ * @see {@linkcode Ext}
+ */
+type ExtensionRewrites = {
+    [K in EmptyString | Ext]?: string | false | null | undefined;
+};
+
 /**
  * @file Type Aliases - FileContent
  * @module mlly/types/FileContent
@@ -1220,6 +1210,36 @@ type Ext = `${Dot}${string}`;
  */
 type FileContent = Uint8Array | string;
 
+/**
+ * @file Type Aliases - GetNewExtension
+ * @module mlly/types/GetNewExtension
+ */
+/**
+ * Get a new file extension for a `url`.
+ *
+ * Returning an empty string (`''`), `false`, `null`, or `undefined`
+ * will remove the current file extension.
+ *
+ * ::: info
+ * File extensions are normalized and
+ * do not need to begin with a dot character (`'.'`).
+ * :::
+ *
+ * @see {@linkcode URL}
+ * @see https://github.com/flex-development/pathe/tree/1.0.3#changeextpath-string-ext-nullablestring-string
+ *
+ * @template {string | false | null | undefined} [T]
+ *  The new file extension
+ *
+ * @param {URL} url
+ *  The resolved module URL
+ * @param {string} specifier
+ *  The module specifier being resolved
+ * @return {T}
+ *  The new file extension
+ */
+type GetNewExtension<T extends string | false | null | undefined = string | false | null | undefined> = (this: void, url: URL, specifier: string) => T;
+
 /**
  * @file Type Aliases - GetSourceHandler
  * @module mlly/types/GetSourceHandler
@@ -1760,7 +1780,7 @@ interface ResolveAliasOptions {
  */
 
 /**
- * Module resolution options.
+ * Options for module resolution.
  */
 interface ResolveModuleOptions {
     /**
@@ -1792,14 +1812,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.
      *
@@ -1884,4 +1907,4 @@ interface Stats {
 }
 
 export { canParseUrl, cwd, defaultConditions, defaultExtensions, defaultMainFields, extensionFormatMap, formats, getSource, isAbsoluteSpecifier, isArrayIndex, isBareSpecifier, isDirectory, isFile, isImportsSubpath, isModuleId, isRelativeSpecifier, legacyMainResolve, lookupPackageScope, moduleResolve, packageExportsResolve, packageImportsExportsResolve, packageImportsResolve, packageResolve, packageSelfResolve, packageTargetResolve, patternKeyCompare, patternMatch, readPackageJson, resolveAlias, resolveModule, resolver_d as resolver, root, toRelativeSpecifier, toUrl };
-export type { Aliases, Awaitable, BufferEncoding, BufferEncodingMap, ChangeExtFn, Condition, ConditionMap, Dot, EmptyArray, EmptyObject, EmptyString, Ext, FileContent, FileSystem, GetSourceContext, GetSourceHandler, GetSourceHandlers, GetSourceOptions, IsDirectory, IsFile, List, MainField, MainFieldMap, ModuleFormat, ModuleFormatMap, ModuleId, Numeric, PatternKeyComparison, PatternKeyComparisonMap, PatternMatch, Protocol, ProtocolMap, ReadFile, Realpath, ResolveAliasOptions, ResolveModuleOptions, Stat, Stats };
+export type { Aliases, Awaitable, BufferEncoding, BufferEncodingMap, Condition, ConditionMap, Dot, EmptyArray, EmptyObject, EmptyString, Ext, ExtensionRewrites, FileContent, FileSystem, GetNewExtension, GetSourceContext, GetSourceHandler, GetSourceHandlers, GetSourceOptions, IsDirectory, IsFile, List, MainField, MainFieldMap, ModuleFormat, ModuleFormatMap, ModuleId, Numeric, PatternKeyComparison, PatternKeyComparisonMap, PatternMatch, Protocol, ProtocolMap, ReadFile, Realpath, ResolveAliasOptions, ResolveModuleOptions, Stat, Stats };

package/dist/lib/resolve-module.mjs

@@ -1 +1 @@
-var i=Object.defineProperty;var a=(t,e)=>i(t,"name",{value:e,configurable:!0});import O from"#internal/constant";import U from"#internal/identity";import x from"#internal/is-promise";import D from"#lib/default-extensions";import y from"#lib/resolve-alias";import{moduleResolve as _}from"#lib/resolver";import{codes as f,isNodeError as N}from"@flex-development/errnode";import m from"@flex-development/pathe";var k=P;function P(t,e,r){let n;try{n=_(y(t,{...r,parent:e})??t,e,r?.conditions,r?.mainFields,r?.preserveSymlinks,r?.fs)}catch(d){return c(d,t,e,r)}return x(n)?n.then(d=>h(d,t,r?.ext),d=>c(d,t,e,r)):h(n,t,r?.ext)}a(P,"resolveModule");function h(t,e,r){return t.protocol==="file:"&&r!==void 0&&(t.href=typeof r=="function"?m.changeExt(t.href,r(t,e)):m.changeExt(t.href,r),t=new URL(m.toPosix(t.href).replace(/\/index$/,m.sep))),t}a(h,"changeExt");function c(t,e,r,n){const d=new Set([f.ERR_MODULE_NOT_FOUND,f.ERR_UNSUPPORTED_DIR_IMPORT]);if(N(t)&&d.has(t.code)){const E=[...n?.extensions??D],R=[];let s,l=[];t.code===f.ERR_MODULE_NOT_FOUND&&!t.url&&(l=[e.startsWith("@types/")?e:"@types/"+e].flatMap(o=>[o,o+m.sep+"index.d.ts",o+m.sep+"index.d.mts",o+m.sep+"index.d.cts"])),t.code===f.ERR_MODULE_NOT_FOUND&&t.url&&(l=E.map(o=>e+m.formatExt(o))),t.code===f.ERR_UNSUPPORTED_DIR_IMPORT&&(l=E.map(o=>e+m.sep+"index"+m.formatExt(o)));for(let o of l){try{if(s=_(o,r,n?.conditions,n?.mainFields,n?.preserveSymlinks,n?.fs),!x(s))return h(s,e,n?.ext)}catch{continue}R.push(s.then(U,O(void 0)))}if(R.length)return Promise.all(R).then(o=>{for(const u of o)if(u)return h(u,e,n?.ext);throw t})}throw t}a(c,"retry");export{k as default};
+var O=Object.defineProperty;var a=(t,n)=>O(t,"name",{value:n,configurable:!0});import c from"#internal/constant";import U from"#internal/identity";import _ from"#internal/is-promise";import y from"#lib/default-extensions";import D from"#lib/resolve-alias";import{moduleResolve as i}from"#lib/resolver";import{codes as l,isNodeError as N}from"@flex-development/errnode";import m from"@flex-development/pathe";var k=P;function P(t,n,e){t=D(t,{...e,parent:n})??t;let r;try{r=i(t,n,e?.conditions,e?.mainFields,e?.preserveSymlinks,e?.fs)}catch(d){return x(d,t,n,e)}return _(r)?r.then(d=>u(d,t,e?.ext),d=>x(d,t,n,e)):u(r,t,e?.ext)}a(P,"resolveModule");function x(t,n,e,r){const d=new Set([l.ERR_MODULE_NOT_FOUND,l.ERR_UNSUPPORTED_DIR_IMPORT]);if(N(t)&&d.has(t.code)){const h=[...r?.extensions??y],R=[];let f,s=[];t.code===l.ERR_MODULE_NOT_FOUND&&!t.url&&(s=[n.startsWith("@types/")?n:"@types/"+n].flatMap(o=>[o,o+m.sep+"index.d.ts",o+m.sep+"index.d.mts",o+m.sep+"index.d.cts"])),t.code===l.ERR_MODULE_NOT_FOUND&&t.url&&(s=h.map(o=>n+m.formatExt(o))),t.code===l.ERR_UNSUPPORTED_DIR_IMPORT&&(s=h.map(o=>n+m.sep+"index"+m.formatExt(o)));for(let o of s){try{if(f=i(o,e,r?.conditions,r?.mainFields,r?.preserveSymlinks,r?.fs),!_(f))return u(f,n,r?.ext)}catch{continue}R.push(f.then(U,c(void 0)))}if(R.length)return Promise.all(R).then(o=>{for(const E of o)if(E)return u(E,n,r?.ext);throw t})}throw t}a(x,"retry");function u(t,n,e){if(t.protocol==="file:"&&e!==void 0){let r;typeof e=="function"?r=e(t,n):typeof e=="object"&&e?r=m.extToValue(t.href,e):r=e,t.href=m.changeExt(t.href,r||null),t=new URL(m.toPosix(t.href).replace(/\/index$/,m.sep))}return t}a(u,"rewriteExtension");export{k as default};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flex-development/mlly",
   "description": "ESM utilities for modern tooling — spec-compliant, developer-friendly, and fully typed",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.6",
   "keywords": [
     "bundle",
     "cli",
@@ -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"
@@ -216,7 +214,7 @@
     "typescript": "5.9.3",
     "unified": "11.0.5",
     "vfile": "6.0.3",
-    "vite-tsconfig-paths": "6.1.0",
+    "vite-tsconfig-paths": "6.1.1",
     "vitest": "4.0.18"
   },
   "resolutions": {