@flex-development/mlly 1.0.0-beta.1 → 1.0.0-beta.3

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## [1.0.0-beta.3](https://github.com/flex-development/mlly/compare/1.0.0-beta.2...1.0.0-beta.3) (2026-02-03)
+
+### ⚠ BREAKING CHANGES
+
+- **lib:** [`getSource`] return `FileContent`
+- **ts:** [`ReadFile`] return string given `encoding`
+
+### :package: Build
+
+- [[`2a5ffdb`](https://github.com/flex-development/mlly/commit/2a5ffdb20ce9b1fc5be481bd1de15cf429d0aafa)] **deps-dev:** Bump cspell from 9.6.2 to 9.6.3 ([#960](https://github.com/flex-development/mlly/issues/960))
+
+### :mechanical_arm: Refactors
+
+- [[`eaca2a7`](https://github.com/flex-development/mlly/commit/eaca2a7549deadd7362f8a2f5993167d9313bb45)] **lib:** [`getSource`] return `FileContent`
+- [[`490d72c`](https://github.com/flex-development/mlly/commit/490d72cba0f59cb4f2fe4ff27cac4b81fa597cc6)] **ts:** match `this` context to node
+- [[`cd54387`](https://github.com/flex-development/mlly/commit/cd54387ed7324085ed94d7b5ebb996e5cac85b4e)] **ts:** [`ReadFile`] return string given `encoding`
+
+## [1.0.0-beta.2](https://github.com/flex-development/mlly/compare/1.0.0-beta.1...1.0.0-beta.2) (2026-02-02)
+
+### :sparkles: Features
+
+- [[`a799aef`](https://github.com/flex-development/mlly/commit/a799aef04f5fa6033297c362474047acaaeb0e1f)] **ts:** generic fs methods
+
 ## [1.0.0-beta.1](https://github.com/flex-development/mlly/compare/1.0.0-alpha.20...1.0.0-beta.1) (2026-02-02)
 
 ### ⚠ BREAKING CHANGES
@@ -1253,3 +1276,5 @@
 - [[`0266ca9`](https://github.com/flex-development/mlly/commit/0266ca9a5593d0c66e950ba1fe2c8f6df8422ff9)] **resolve:** sort `RESOLVE_EXTENSIONS` according to priority
 - [[`36c4b74`](https://github.com/flex-development/mlly/commit/36c4b7475c9bb6c924f5e75c8d6d215a8d23e79c)] **specifiers:** [`toBareSpecifier`] improve `exports` path search
 
+
+

package/README.md

@@ -57,6 +57,8 @@
 - [Types](#types)
   - [`Aliases`](#aliases)
   - [`Awaitable<T>`](#awaitablet)
+  - [`BufferEncodingMap`](#bufferencodingmap)
+  - [`BufferEncoding`](#bufferencoding)
   - [`ChangeExtFn<[Ext]>`](#changeextfnext)
   - [`ConditionMap`](#conditionmap)
   - [`Condition`](#condition)
@@ -65,6 +67,7 @@
   - [`EmptyObject`](#emptyobject)
   - [`EmptyString`](#emptystring)
   - [`Ext`](#ext)
+  - [`FileContent`](#filecontent)
   - [`FileSystem`](#filesystem)
   - [`GetSourceContext`](#getsourcecontext)
   - [`GetSourceHandler`](#getsourcehandler)
@@ -84,11 +87,11 @@
   - [`PatternMatch`](#patternmatch)
   - [`ProtocolMap`](#protocolmap)
   - [`Protocol`](#protocol)
-  - [`ReadFile`](#readfile)
-  - [`Realpath`](#realpath)
+  - [`ReadFile<[T]>`](#readfilet)
+  - [`Realpath<[T]>`](#realpatht)
   - [`ResolveAliasOptions`](#resolvealiasoptions)
   - [`ResolveModuleOptions`](#resolvemoduleoptions)
-  - [`Stat`](#stat)
+  - [`Stat<[T]>`](#statt)
   - [`Stats`](#stats)
 - Additional Documentation
   - [Resolution Algorithm](./docs/resolution-algorithm.md)
@@ -271,7 +274,7 @@ Get the source code for a module.
 
 #### Type Parameters
 
-- `T` ([`Awaitable<string | null | undefined>`](#awaitablet))
+- `T` ([`Awaitable<FileContent | null | undefined>`](#filecontent))
   — the module source code
 
 #### Parameters
@@ -1039,6 +1042,31 @@ type Awaitable<T> = PromiseLike<T> | T
 - `T` (`any`)
   - the value
 
+### `BufferEncodingMap`
+
+Registry of character encodings that can be used when working with `Buffer` objects (`interface`).
+
+When developing extensions that use additional encodings, augment `BufferEncodingMap` to register custom encodings:
+
+```ts
+declare module '@flex-development/mlly' {
+  interface BufferEncodingMap {
+    custom: 'custom'
+  }
+}
+```
+
+### `BufferEncoding`
+
+Union of values that can occur where a buffer encoding is expected (`type`).
+
+To register new encodings, augment [`BufferEncodingMap`](#bufferencodingmap).
+They will be added to this union automatically.
+
+```ts
+type BufferEncoding = BufferEncodingMap[keyof BufferEncodingMap]
+```
+
 ### `ChangeExtFn<[Ext]>`
 
 Get a new file extension for `url` (`type`).
@@ -1132,17 +1160,25 @@ A file extension (`type`).
 type Ext = `${Dot}${string}`
 ```
 
+### `FileContent`
+
+Union of values that can occur where file content is expected (`type`).
+
+```ts
+type FileContent = Uint8Array | string
+```
+
 ### `FileSystem`
 
 The file system API (`interface`).
 
 #### Properties
 
-- `readFile` ([`ReadFile`](#readfile))
+- `readFile` ([`ReadFile`](#readfilet))
   — read the entire contents of a file
-- `realpath` ([`Realpath`](#realpath))
+- `realpath` ([`Realpath`](#realpatht))
   — compute a canonical pathname by resolving `.`, `..`, and symbolic links
-- `stat` ([`Stat`](#stat))
+- `stat` ([`Stat`](#statt))
   — get information about a directory or file
 
 ### `GetSourceContext`
@@ -1172,7 +1208,7 @@ Get the source code for a module (`type`).
 type GetSourceHandler = (
   this: GetSourceContext,
   url: URL
-) => Awaitable<Uint8Array | string | null | undefined>
+) => Awaitable<FileContent | null | undefined>
 ```
 
 #### Parameters
@@ -1184,7 +1220,7 @@ type GetSourceHandler = (
 
 #### Returns
 
-([`Awaitable<Uint8Array | string | null | undefined>`](#awaitablet)) The source code
+([`Awaitable<FileContent | null | undefined>`](#filecontent)) The source code
 
 ### `GetSourceHandlers`
 
@@ -1202,6 +1238,9 @@ Options for retrieving source code (`interface`).
 
 #### Properties
 
+- `encoding?` ([`BufferEncoding`](#bufferencoding) | `null` | `undefined`)
+  — the encoding of the result
+  > 👉 **note**: used when the `file:` handler is called
 - `format?` ([`ModuleFormat`](#moduleformat) | `null` | `undefined`)
   — the module format hint
 - `fs?` ([`FileSystem`](#filesystem) | `null` | `undefined`)
@@ -1372,26 +1411,46 @@ They will be added to this union automatically.
 type Protocol = ProtocolMap[keyof ProtocolMap]
 ```
 
-### `ReadFile`
+### `ReadFile<[T]>`
 
 Read the entire contents of a file (`interface`).
 
+#### Overloads
+
+```ts
+(id: ModuleId, encoding: BufferEncoding): Awaitable<string>
+(id: ModuleId, encoding?: BufferEncoding | null | undefined): T
+```
+
+#### Type Parameters
+
+- `T` ([`Awaitable<FileContent | null | undefined>`](#filecontent), optional)
+  — the file contents
+  - **default**: [`Awaitable<FileContent>`](#filecontent)
+
 #### Parameters
 
 - `id` ([`ModuleId`](#moduleid))
   — the module id
+- `encoding` ([`BufferEncoding`](#bufferencoding))
+  — the encoding of the file contents
 
 #### Returns
 
-([`Awaitable<Buffer | string>`](#awaitablet)) The file contents
+(`T`) The file contents
 
-### `Realpath`
+### `Realpath<[T]>`
 
 Compute a canonical pathname by resolving `.`, `..`, and symbolic links (`interface`).
 
 > 👉 **Note**: A canonical pathname is not necessarily unique.
 > Hard links and bind mounts can expose an entity through many pathnames.
 
+#### Type Parameters
+
+- `T` ([`Awaitable<string>`](#awaitablet), optional)
+  — the canonical pathname
+
 #### Parameters
 
 - `id` ([`ModuleId`](#moduleid))
@@ -1399,7 +1458,7 @@ Compute a canonical pathname by resolving `.`, `..`, and symbolic links (`interf
 
 #### Returns
 
-([`Awaitable<string>`](#awaitablet)) The canonical pathname
+(`T`) The canonical pathname
 
 ### `ResolveAliasOptions`
 
@@ -1451,10 +1510,15 @@ Options for path alias resolution (`interface`).
 - `preserveSymlinks?` (`boolean` | `null` | `undefined`)
   — whether to keep symlinks instead of resolving them
 
-### `Stat`
+### `Stat<[T]>`
 
 Get information about a directory or file (`interface`).
 
+#### Type Parameters
+
+- `T` ([`Awaitable<Stats>`](#stats), optional)
+  — the info
+
 #### Parameters
 
 - `id` ([`ModuleId`](#moduleid))
@@ -1462,7 +1526,7 @@ Get information about a directory or file (`interface`).
 
 #### Returns
 
-([`Awaitable<Stats>`](#stats)) The info
+(`T`) The info
 
 ### `Stats`
 

package/dist/interfaces/buffer-encoding-map.d.mts

@@ -0,0 +1,29 @@
+/**
+ * @file Interfaces - BufferEncodingMap
+ * @module mlly/interfaces/BufferEncodingMap
+ */
+/**
+ * Registry of character encodings that can be used when working
+ * with {@linkcode Buffer} objects.
+ *
+ * This interface can be augmented to register custom encodings.
+ *
+ * @example
+ *  declare module '@flex-development/mlly' {
+ *    interface BufferEncodingMap {
+ *      custom: 'custom'
+ *    }
+ *  }
+ */
+interface BufferEncodingMap {
+    ascii: 'ascii';
+    base64: 'base64';
+    base64url: 'base64url';
+    binary: 'binary';
+    hex: 'hex';
+    latin1: 'latin1';
+    ucs2: 'ucs2' | 'ucs-2';
+    utf16le: 'utf16le' | 'utf-16le';
+    utf8: 'utf8' | 'utf-8';
+}
+export type { BufferEncodingMap as default };

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

@@ -2,11 +2,19 @@
  * @file Interfaces - GetSourceOptions
  * @module mlly/interfaces/GetSourceOptions
  */
-import type { FileSystem, GetSourceHandlers, List, ModuleFormat } from '@flex-development/mlly';
+import type { BufferEncoding, FileSystem, GetSourceHandlers, List, ModuleFormat } from '@flex-development/mlly';
 /**
  * Options for retrieving source code.
  */
 interface GetSourceOptions {
+    /**
+     * The encoding of the result.
+     *
+     * > 👉 **Note**: Used when the `file:` handler is called.
+     *
+     * @see {@linkcode BufferEncoding}
+     */
+    encoding?: BufferEncoding | null | undefined;
     /**
      * The module format hint.
      *

package/dist/interfaces/index.d.mts

@@ -3,6 +3,7 @@
  * @module mlly/interfaces
  */
 export type { default as Aliases } from '#interfaces/aliases';
+export type { default as BufferEncodingMap } from '#interfaces/buffer-encoding-map';
 export type { default as ConditionMap } from '#interfaces/condition-map';
 export type { default as FileSystem } from '#interfaces/file-system';
 export type { default as GetSourceContext } from '#interfaces/get-source-context';

package/dist/interfaces/is-directory.d.mts

@@ -7,11 +7,11 @@
  */
 interface IsDirectory {
     /**
-     * @this {void}
+     * @this {unknown}
      *
      * @return {boolean}
      *  `true` if stats describes directory, `false` otherwise
      */
-    (this: void): boolean;
+    (): boolean;
 }
 export type { IsDirectory as default };

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

@@ -12,6 +12,6 @@ interface IsFile {
      * @return {boolean}
      *  `true` if stats object describes regular file, `false` otherwise
      */
-    (this: void): boolean;
+    (): boolean;
 }
 export type { IsFile as default };

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

@@ -2,23 +2,42 @@
  * @file Interfaces - ReadFile
  * @module mlly/interfaces/ReadFile
  */
-import type { Awaitable, ModuleId } from '@flex-development/mlly';
+import type { Awaitable, BufferEncoding, FileContent, ModuleId } from '@flex-development/mlly';
 /**
  * Read the entire contents of a file.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode Buffer}
+ *
+ * @template {Awaitable<FileContent | null | undefined>} [T]
+ *  The file contents
  */
-interface ReadFile {
+interface ReadFile<T extends Awaitable<FileContent | null | undefined> = Awaitable<FileContent>> {
     /**
-     * @see {@linkcode Awaitable}
-     * @see {@linkcode Buffer}
      * @see {@linkcode ModuleId}
      *
-     * @this {void}
+     * @this {unknown}
      *
      * @param {ModuleId} id
      *  The module id
-     * @return {Awaitable<Buffer | string>}
+     * @param {BufferEncoding} encoding
+     *  The encoding of the file contents
+     * @return {Awaitable<string>}
      *  The file contents
      */
-    (this: void, id: ModuleId): Awaitable<Buffer | string>;
+    (id: ModuleId, encoding: BufferEncoding): Awaitable<string>;
+    /**
+     * @see {@linkcode ModuleId}
+     *
+     * @this {unknown}
+     *
+     * @param {ModuleId} id
+     *  The module id
+     * @param {BufferEncoding | null | undefined} [encoding]
+     *  The encoding of the file contents
+     * @return {T}
+     *  The file contents
+     */
+    (id: ModuleId, encoding?: BufferEncoding | null | undefined): T;
 }
 export type { ReadFile as default };

package/dist/interfaces/realpath.d.mts

@@ -8,19 +8,23 @@ import type { Awaitable, ModuleId } from '@flex-development/mlly';
  *
  * > 👉 **Note**: A canonical pathname is not necessarily unique.
  * > Hard links and bind mounts can expose an entity through many pathnames.
+ *
+ * @see {@linkcode Awaitable}
+ *
+ * @template {Awaitable<string>} [T]
+ *  The canonical pathname
  */
-interface Realpath {
+interface Realpath<T extends Awaitable<string> = Awaitable<string>> {
     /**
-     * @see {@linkcode Awaitable}
      * @see {@linkcode ModuleId}
      *
-     * @this {void}
+     * @this {unknown}
      *
      * @param {ModuleId} id
      *  The module id
-     * @return {Awaitable<string>}
+     * @return {T}
      *  The canonical pathname
      */
-    (this: void, id: ModuleId): Awaitable<string>;
+    (id: ModuleId): T;
 }
 export type { Realpath as default };

package/dist/interfaces/stat.d.mts

@@ -5,20 +5,24 @@
 import type { Awaitable, ModuleId, Stats } from '@flex-development/mlly';
 /**
  * Get information about a directory or file.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode Stats}
+ *
+ * @template {Awaitable<Stats>} [T]
+ *  The info
  */
-interface Stat {
+interface Stat<T extends Awaitable<Stats> = Awaitable<Stats>> {
     /**
-     * @see {@linkcode Awaitable}
      * @see {@linkcode ModuleId}
-     * @see {@linkcode Stats}
      *
-     * @this {void}
+     * @this {unknown}
      *
      * @param {ModuleId} id
      *  The module id
-     * @return {Awaitable<Stats>}
+     * @return {T}
      *  The info
      */
-    (this: void, id: ModuleId): Awaitable<Stats>;
+    (id: ModuleId): T;
 }
 export type { Stat as default };

package/dist/lib/get-source.d.mts

@@ -2,7 +2,7 @@
  * @file getSource
  * @module mlly/lib/getSource
  */
-import type { Awaitable, EmptyString, GetSourceOptions, ModuleId } from '@flex-development/mlly';
+import type { Awaitable, EmptyString, FileContent, GetSourceOptions, ModuleId } from '@flex-development/mlly';
 export default getSource;
 /**
  * Get the source code for a module.
@@ -30,7 +30,7 @@ declare function getSource(this: void, id: EmptyString | null | undefined, optio
  * @see {@linkcode GetSourceOptions}
  * @see {@linkcode ModuleId}
  *
- * @template {Awaitable<string | null | undefined>} T
+ * @template {Awaitable<FileContent | null | undefined>} T
  *  The module source code
  *
  * @this {void}
@@ -43,4 +43,4 @@ declare function getSource(this: void, id: EmptyString | null | undefined, optio
  *  The module source code
  * @throws {ErrUnsupportedEsmUrlScheme}
  */
-declare function getSource<T extends Awaitable<string | null | undefined>>(this: void, id: ModuleId | null | undefined, options?: GetSourceOptions | null | undefined): T;
+declare function getSource<T extends Awaitable<FileContent | null | undefined>>(this: void, id: ModuleId | null | undefined, options?: GetSourceOptions | null | undefined): T;

package/dist/lib/get-source.mjs

@@ -28,7 +28,7 @@ export default getSource;
  *  The module id
  * @param {GetSourceOptions | null | undefined} [options]
  *  Source code retrieval options
- * @return {Awaitable<string | null | undefined>}
+ * @return {Awaitable<FileContent | null | undefined>}
  *  The module source code
  * @throws {ErrUnsupportedEsmUrlScheme}
  */
@@ -79,7 +79,7 @@ function getSource(id, options) {
     /**
      * The source code.
      *
-     * @var {Awaitable<Uint8Array | string | null | undefined>} code
+     * @var {ReturnType<GetSourceHandler>} code
      */
     let code = handle.call(context, url);
     // resolve source code.
@@ -87,10 +87,7 @@ function getSource(id, options) {
         void code.then(resolved => (code = resolved));
     }
     return chainOrCall(code, () => {
-        ok(!isPromise(code), 'expected `code` to be resolved');
-        if (code !== null && code !== undefined)
-            code = String(code);
-        return code;
+        return ok(!isPromise(code), 'expected `code` to be resolved'), code;
     });
 }
 /**
@@ -115,7 +112,7 @@ function data(url) {
  *
  * @param {URL} url
  *  The module URL
- * @return {Awaitable<Buffer | string | null>}
+ * @return {Awaitable<FileContent | null>}
  *  The source code
  */
 function file(url) {
@@ -127,7 +124,7 @@ function file(url) {
      */
     const exists = isFile(url, this.fs);
     return chainOrCall(exists, isFile => {
-        return isFile ?? exists ? this.fs.readFile(url) : null;
+        return isFile ?? exists ? this.fs.readFile(url, this.encoding) : null;
     });
 }
 /**

package/dist/lib/read-package-json.mjs

@@ -62,19 +62,18 @@ function readPackageJson(id, specifier, parent, fs) {
             /**
              * The stringified contents of the package manifest file.
              *
-             * @const {Awaitable<Buffer | string>} contents
+             * @const {Awaitable<string>} contents
              */
-            const contents = fs.readFile(url);
+            const contents = fs.readFile(url, 'utf8');
             // parse file content.
-            return chainOrCall(contents, data => {
-                data ??= contents;
+            return chainOrCall(contents, (data = contents) => {
                 try {
                     /**
                      * The parsed file contents.
                      *
-                     * @const {any} parsed
+                     * @const {unknown} parsed
                      */
-                    const parsed = JSON.parse(String(data));
+                    const parsed = JSON.parse(data);
                     if (isPackageJson(parsed))
                         return parsed;
                     throw new Error('Invalid package manifest object', { cause: parsed });

package/dist/types/buffer-encoding.d.mts

@@ -0,0 +1,13 @@
+/**
+ * @file Type Aliases - BufferEncoding
+ * @module mlly/types/BufferEncoding
+ */
+import type { BufferEncodingMap } from '@flex-development/mlly';
+/**
+ * Union of values that can occur where a buffer encoding is expected.
+ *
+ * To register new encodings, augment {@linkcode BufferEncodingMap}.
+ * They will be added to this union automatically.
+ */
+type BufferEncoding = BufferEncodingMap[keyof BufferEncodingMap];
+export type { BufferEncoding as default };

package/dist/types/file-content.d.mts

@@ -0,0 +1,11 @@
+/**
+ * @file Type Aliases - FileContent
+ * @module mlly/types/FileContent
+ */
+/**
+ * Union of values that can occur where file content is expected.
+ *
+ * @see {@linkcode Uint8Array}
+ */
+type FileContent = Uint8Array | string;
+export type { FileContent as default };

package/dist/types/get-source-handler.d.mts

@@ -2,11 +2,12 @@
  * @file Type Aliases - GetSourceHandler
  * @module mlly/types/GetSourceHandler
  */
-import type { Awaitable, GetSourceContext } from '@flex-development/mlly';
+import type { Awaitable, FileContent, GetSourceContext } from '@flex-development/mlly';
 /**
  * Get the source code for a module.
  *
  * @see {@linkcode Awaitable}
+ * @see {@linkcode FileContent}
  * @see {@linkcode GetSourceContext}
  * @see {@linkcode URL}
  *
@@ -15,8 +16,8 @@ import type { Awaitable, GetSourceContext } from '@flex-development/mlly';
  *
  * @param {URL} url
  *  The module URL
- * @return {Awaitable<Uint8Array | string | null | undefined>}
+ * @return {Awaitable<FileContent | null | undefined>}
  *  The source code
  */
-type GetSourceHandler = (this: GetSourceContext, url: URL) => Awaitable<Uint8Array | string | null | undefined>;
+type GetSourceHandler = (this: GetSourceContext, url: URL) => Awaitable<FileContent | null | undefined>;
 export type { GetSourceHandler as default };

package/dist/types/index.d.mts

@@ -3,6 +3,7 @@
  * @module mlly/types
  */
 export type { default as Awaitable } from '#types/awaitable';
+export type { default as BufferEncoding } from '#types/buffer-encoding';
 export type { default as ChangeExtFn } from '#types/change-ext-fn';
 export type { default as Condition } from '#types/condition';
 export type { default as Dot } from '#types/dot';
@@ -10,6 +11,7 @@ export type { default as EmptyArray } from '#types/empty-array';
 export type { default as EmptyObject } from '#types/empty-object';
 export type { default as EmptyString } from '#types/empty-string';
 export type { default as Ext } from '#types/ext';
+export type { default as FileContent } from '#types/file-content';
 export type { default as GetSourceHandler } from '#types/get-source-handler';
 export type { default as GetSourceHandlers } from '#types/get-source-handlers';
 export type { default as List } from '#types/list';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flex-development/mlly",
   "description": "ECMAScript module utilities",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "keywords": [
     "ecmascript",
     "esm",
@@ -180,7 +180,7 @@
     "chai-string": "1.6.0",
     "concat-stream": "2.0.0",
     "cross-env": "10.1.0",
-    "cspell": "9.6.2",
+    "cspell": "9.6.3",
     "dprint": "0.51.1",
     "editorconfig": "3.0.1",
     "eslint": "9.39.2",