tiny-essentials 1.28.19 → 1.29.1

package/dist/v1/libs/fs/encoding.mjs

@@ -0,0 +1,102 @@
+/**
+ * @file Byte/string conversion helpers shared by every {@link TinyFSCore} backend.
+ */
+/**
+ * Converts a byte array into a base64 string.
+ *
+ * @param {Uint8Array} bytes Source bytes.
+ * @returns {string} The base64 representation.
+ */
+export const bytesToBase64 = (bytes) => {
+    let binary = '';
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+};
+/**
+ * Converts a base64 string into a byte array.
+ *
+ * @param {string} value Source string.
+ * @returns {Uint8Array} The decoded bytes.
+ */
+export const base64ToBytes = (value) => {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+};
+/**
+ * Converts a byte array into a lowercase hexadecimal string.
+ *
+ * @param {Uint8Array} bytes Source bytes.
+ * @returns {string} The hexadecimal representation.
+ */
+export const bytesToHex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+/**
+ * Converts a hexadecimal string into a byte array.
+ *
+ * @param {string} value Source string.
+ * @returns {Uint8Array} The decoded bytes.
+ * @throws {TypeError} When the string length is odd.
+ */
+export const hexToBytes = (value) => {
+    if (value.length % 2 !== 0) {
+        throw new TypeError('The "hex" encoded string must have an even length');
+    }
+    const bytes = new Uint8Array(value.length / 2);
+    for (let index = 0; index < bytes.length; index += 1) {
+        bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
+    }
+    return bytes;
+};
+/**
+ * Decodes a byte array using the requested encoding.
+ *
+ * @param {Uint8Array} bytes Source bytes.
+ * @param {string | null} encoding Target encoding, or `null` for binary.
+ * @returns {string | Uint8Array} The decoded payload.
+ */
+export const decodeBytes = (bytes, encoding) => {
+    if (encoding === null) {
+        return bytes;
+    }
+    if (encoding === 'base64') {
+        return bytesToBase64(bytes);
+    }
+    if (encoding === 'hex') {
+        return bytesToHex(bytes);
+    }
+    return new TextDecoder('utf-8').decode(bytes);
+};
+/**
+ * Converts supported input values into a byte array.
+ *
+ * @param {string | Uint8Array | ArrayBuffer | ArrayBufferView} data Source payload.
+ * @param {string | null} encoding Encoding used when `data` is a string.
+ * @returns {Uint8Array} The encoded bytes.
+ * @throws {TypeError} When the payload type is not supported.
+ */
+export const toUint8Array = (data, encoding) => {
+    if (typeof data === 'string') {
+        if (encoding === 'base64') {
+            return base64ToBytes(data);
+        }
+        if (encoding === 'hex') {
+            return hexToBytes(data);
+        }
+        return new TextEncoder().encode(data);
+    }
+    if (data instanceof Uint8Array) {
+        return data;
+    }
+    if (data instanceof ArrayBuffer) {
+        return new Uint8Array(data);
+    }
+    if (ArrayBuffer.isView(data)) {
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    }
+    throw new TypeError('The "data" argument must be a string, an ArrayBuffer or an ArrayBufferView');
+};

package/dist/v1/libs/fs/error.cjs

@@ -0,0 +1,188 @@
+'use strict';
+
+var constants = require('./constants.cjs');
+
+/**
+ * @file Errno-style error helpers shared by every {@link TinyFSCore} backend.
+ *
+ * These helpers are intentionally dependency free so they can be imported from
+ * the abstract class, from concrete backends and from user code without
+ * creating circular imports.
+ */
+
+
+/** @type {string} */
+const NULL_BYTE = '\u0000';
+
+/**
+ * @typedef {Object} FileSystemErrorProperties
+ * @property {string} code POSIX error code, e.g. `ENOENT`.
+ * @property {string} errno Alias of `code`, mirrors Node.js.
+ * @property {string} syscall Name of the originating operation.
+ * @property {string} path Path the operation was applied to.
+ */
+
+/**
+ * @typedef {Error & FileSystemErrorProperties} FileSystemError
+ */
+
+/**
+ * Builds an errno-style error that matches the shape produced by Node.js.
+ *
+ * @param {string} code POSIX error code, e.g. `ENOENT`.
+ * @param {string} syscall Name of the originating operation.
+ * @param {string} targetPath Path the operation was applied to.
+ * @param {string} [detail] Extra human readable context.
+ * @returns {FileSystemError} The formatted error.
+ */
+const createFileSystemError = (code, syscall, targetPath, detail = '') => {
+  const suffix = detail.length > 0 ? `, ${detail}` : '';
+  /** @type {FileSystemError} */
+  const error = /** @type {FileSystemError} */ (
+    new Error(`${code}: ${syscall} '${targetPath}'${suffix}`)
+  );
+  error.code = code;
+  error.errno = code;
+  error.syscall = syscall;
+  error.path = targetPath;
+  return error;
+};
+
+/**
+ * Translates a `DOMException` thrown by a Web API into an errno-style error.
+ *
+ * @param {unknown} error The value caught from a browser call.
+ * @param {string} syscall Name of the originating operation.
+ * @param {string} targetPath Path the operation was applied to.
+ * @param {string} [mismatchCode] Error code used when the entry exists with the wrong type.
+ * @returns {FileSystemError | Error} An errno-style error.
+ */
+const toFileSystemError = (error, syscall, targetPath, mismatchCode = 'ENOTDIR') => {
+  if (typeof DOMException !== 'undefined' && error instanceof DOMException) {
+    switch (error.name) {
+      case 'NotFoundError':
+        return createFileSystemError('ENOENT', syscall, targetPath);
+      case 'TypeMismatchError':
+        return createFileSystemError(mismatchCode, syscall, targetPath);
+      case 'InvalidModificationError':
+        return createFileSystemError('ENOTEMPTY', syscall, targetPath);
+      case 'NoModificationAllowedError':
+        return createFileSystemError('EBUSY', syscall, targetPath);
+      case 'NotAllowedError':
+        return createFileSystemError('EACCES', syscall, targetPath);
+      default:
+        return createFileSystemError('EIO', syscall, targetPath, error.message);
+    }
+  }
+  return error instanceof Error ? error : new Error(String(error));
+};
+
+/**
+ * Validates that a value is a usable path string.
+ *
+ * @param {unknown} value Candidate value.
+ * @param {string} argumentName Name used in the thrown message.
+ * @returns {string} The validated path.
+ * @throws {TypeError} When the value is not a string or contains a null byte.
+ * @throws {Error} When the value is empty.
+ */
+const assertPath = (value, argumentName) => {
+  if (typeof value !== 'string') {
+    const received = value === null ? 'null' : typeof value;
+    throw new TypeError(
+      `The "${argumentName}" argument must be of type string. Received ${received}`,
+    );
+  }
+  if (value.length === 0) {
+    throw createFileSystemError('ENOENT', 'open', value, 'path must not be empty');
+  }
+  if (value.includes(NULL_BYTE)) {
+    throw new TypeError('The "path" argument must not contain null bytes');
+  }
+  return value;
+};
+
+/**
+ * Validates that a value is a plain options object.
+ *
+ * @param {unknown} value Candidate value.
+ * @param {string} functionName Name used in the thrown message.
+ * @returns {Record<string, unknown>} The validated options object.
+ * @throws {TypeError} When the value is not a plain object.
+ */
+const assertOptionsObject = (value, functionName) => {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    const received = value === null ? 'null' : Array.isArray(value) ? 'Array' : typeof value;
+    throw new TypeError(
+      `The "options" argument must be of type object. Received ${received} in ${functionName}()`,
+    );
+  }
+  return /** @type {Record<string, unknown>} */ (value);
+};
+
+/**
+ * Validates an encoding identifier.
+ *
+ * @param {unknown} value Candidate encoding.
+ * @param {string} functionName Name used in the thrown message.
+ * @returns {string | null} The validated encoding, or `null` for binary mode.
+ * @throws {TypeError} When the encoding is not supported.
+ */
+const assertEncoding = (value, functionName) => {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  if (typeof value !== 'string' || !constants.SUPPORTED_ENCODINGS.includes(value)) {
+    throw new TypeError(
+      `The "encoding" option must be one of ${constants.SUPPORTED_ENCODINGS.join(', ')}. ` +
+        `Received ${String(value)} in ${functionName}()`,
+    );
+  }
+  return value;
+};
+
+/**
+ * Validates a POSIX permission bitmask.
+ *
+ * @param {unknown} value Candidate mode.
+ * @param {string} argumentName Name used in the thrown message.
+ * @returns {number} The validated mode.
+ * @throws {TypeError} When the value is not an integer.
+ * @throws {RangeError} When the value is outside the 12-bit range.
+ */
+const assertMode = (value, argumentName) => {
+  if (typeof value !== 'number' || !Number.isInteger(value)) {
+    throw new TypeError(`The "${argumentName}" argument must be an integer`);
+  }
+  if (value < 0 || value > 0o7777) {
+    throw new RangeError(`The "${argumentName}" argument must be between 0o0000 and 0o7777`);
+  }
+  return value;
+};
+
+/**
+ * Validates a non-negative integer.
+ *
+ * @param {unknown} value Candidate value.
+ * @param {string} argumentName Name used in the thrown message.
+ * @returns {number} The validated integer.
+ * @throws {TypeError} When the value is not an integer.
+ * @throws {RangeError} When the value is negative.
+ */
+const assertInteger = (value, argumentName) => {
+  if (typeof value !== 'number' || !Number.isInteger(value)) {
+    throw new TypeError(`The "${argumentName}" argument must be an integer`);
+  }
+  if (value < 0) {
+    throw new RangeError(`The "${argumentName}" argument must not be negative`);
+  }
+  return value;
+};
+
+exports.assertEncoding = assertEncoding;
+exports.assertInteger = assertInteger;
+exports.assertMode = assertMode;
+exports.assertOptionsObject = assertOptionsObject;
+exports.assertPath = assertPath;
+exports.createFileSystemError = createFileSystemError;
+exports.toFileSystemError = toFileSystemError;

package/dist/v1/libs/fs/error.d.mts

@@ -0,0 +1,105 @@
+/**
+ * @file Errno-style error helpers shared by every {@link TinyFSCore} backend.
+ *
+ * These helpers are intentionally dependency free so they can be imported from
+ * the abstract class, from concrete backends and from user code without
+ * creating circular imports.
+ */
+export type FileSystemErrorProperties = {
+    /**
+     * POSIX error code, e.g. `ENOENT`.
+     */
+    code: string;
+    /**
+     * Alias of `code`, mirrors Node.js.
+     */
+    errno: string;
+    /**
+     * Name of the originating operation.
+     */
+    syscall: string;
+    /**
+     * Path the operation was applied to.
+     */
+    path: string;
+};
+export type FileSystemError = Error & FileSystemErrorProperties;
+/**
+ * @typedef {Object} FileSystemErrorProperties
+ * @property {string} code POSIX error code, e.g. `ENOENT`.
+ * @property {string} errno Alias of `code`, mirrors Node.js.
+ * @property {string} syscall Name of the originating operation.
+ * @property {string} path Path the operation was applied to.
+ */
+/**
+ * @typedef {Error & FileSystemErrorProperties} FileSystemError
+ */
+/**
+ * Builds an errno-style error that matches the shape produced by Node.js.
+ *
+ * @param {string} code POSIX error code, e.g. `ENOENT`.
+ * @param {string} syscall Name of the originating operation.
+ * @param {string} targetPath Path the operation was applied to.
+ * @param {string} [detail] Extra human readable context.
+ * @returns {FileSystemError} The formatted error.
+ */
+export declare const createFileSystemError: (code: string, syscall: string, targetPath: string, detail?: string) => FileSystemError;
+/**
+ * Translates a `DOMException` thrown by a Web API into an errno-style error.
+ *
+ * @param {unknown} error The value caught from a browser call.
+ * @param {string} syscall Name of the originating operation.
+ * @param {string} targetPath Path the operation was applied to.
+ * @param {string} [mismatchCode] Error code used when the entry exists with the wrong type.
+ * @returns {FileSystemError | Error} An errno-style error.
+ */
+export declare const toFileSystemError: (error: unknown, syscall: string, targetPath: string, mismatchCode?: string) => FileSystemError | Error;
+/**
+ * Validates that a value is a usable path string.
+ *
+ * @param {unknown} value Candidate value.
+ * @param {string} argumentName Name used in the thrown message.
+ * @returns {string} The validated path.
+ * @throws {TypeError} When the value is not a string or contains a null byte.
+ * @throws {Error} When the value is empty.
+ */
+export declare const assertPath: (value: unknown, argumentName: string) => string;
+/**
+ * Validates that a value is a plain options object.
+ *
+ * @param {unknown} value Candidate value.
+ * @param {string} functionName Name used in the thrown message.
+ * @returns {Record<string, unknown>} The validated options object.
+ * @throws {TypeError} When the value is not a plain object.
+ */
+export declare const assertOptionsObject: (value: unknown, functionName: string) => Record<string, unknown>;
+/**
+ * Validates an encoding identifier.
+ *
+ * @param {unknown} value Candidate encoding.
+ * @param {string} functionName Name used in the thrown message.
+ * @returns {string | null} The validated encoding, or `null` for binary mode.
+ * @throws {TypeError} When the encoding is not supported.
+ */
+export declare const assertEncoding: (value: unknown, functionName: string) => string | null;
+/**
+ * Validates a POSIX permission bitmask.
+ *
+ * @param {unknown} value Candidate mode.
+ * @param {string} argumentName Name used in the thrown message.
+ * @returns {number} The validated mode.
+ * @throws {TypeError} When the value is not an integer.
+ * @throws {RangeError} When the value is outside the 12-bit range.
+ */
+export declare const assertMode: (value: unknown, argumentName: string) => number;
+/**
+ * Validates a non-negative integer.
+ *
+ * @param {unknown} value Candidate value.
+ * @param {string} argumentName Name used in the thrown message.
+ * @returns {number} The validated integer.
+ * @throws {TypeError} When the value is not an integer.
+ * @throws {RangeError} When the value is negative.
+ */
+export declare const assertInteger: (value: unknown, argumentName: string) => number;
+//# sourceMappingURL=error.d.mts.map

package/dist/v1/libs/fs/error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.mts","sourceRoot":"","sources":["../../../../src/v1/libs/fs/error.mjs"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQA,YAAkB,yBAAyB,GAC3C;;;;IAAmB,IAAI,EAAZ,MAAM,CACjB;;;;IAAmB,KAAK,EAAb,MAAM,CACjB;;;;IAAmB,OAAO,EAAf,MAAM,CACjB;;;;IAAmB,IAAI,EAAZ,MAAM,CACnB;CAAA,CAAA;AAGE,YAA6C,eAAe,GAAlD,KAAK,GAAG,yBAAyB,CAAiB;AAT/D;;;;;;GAMG;AAEH;;GAEG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,SANvB,MAAM,WACN,MAAM,cACN,MAAM,WACN,MAAM,KACJ,eAaZ,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,UANnB,OAAO,WACP,MAAM,cACN,MAAM,iBACN,MAAM,KACJ,eAAe,GAAG,KAoB9B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,UANZ,OAAO,gBACP,MAAM,KACJ,MAkBZ,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,UALrB,OAAO,gBACP,MAAM,KACJ,MAAM,CAAC,MAAM,EAAE,OAAO,CAWlC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,UALhB,OAAO,gBACP,MAAM,KACJ,MAAM,GAAG,IAcrB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,UANZ,OAAO,gBACP,MAAM,KACJ,MAYZ,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,UANf,OAAO,gBACP,MAAM,KACJ,MAYZ,CAAC"}

package/dist/v1/libs/fs/error.mjs

@@ -0,0 +1,158 @@
+/**
+ * @file Errno-style error helpers shared by every {@link TinyFSCore} backend.
+ *
+ * These helpers are intentionally dependency free so they can be imported from
+ * the abstract class, from concrete backends and from user code without
+ * creating circular imports.
+ */
+import { SUPPORTED_ENCODINGS } from './constants.mjs';
+/** @type {string} */
+const NULL_BYTE = '\u0000';
+/**
+ * @typedef {Object} FileSystemErrorProperties
+ * @property {string} code POSIX error code, e.g. `ENOENT`.
+ * @property {string} errno Alias of `code`, mirrors Node.js.
+ * @property {string} syscall Name of the originating operation.
+ * @property {string} path Path the operation was applied to.
+ */
+/**
+ * @typedef {Error & FileSystemErrorProperties} FileSystemError
+ */
+/**
+ * Builds an errno-style error that matches the shape produced by Node.js.
+ *
+ * @param {string} code POSIX error code, e.g. `ENOENT`.
+ * @param {string} syscall Name of the originating operation.
+ * @param {string} targetPath Path the operation was applied to.
+ * @param {string} [detail] Extra human readable context.
+ * @returns {FileSystemError} The formatted error.
+ */
+export const createFileSystemError = (code, syscall, targetPath, detail = '') => {
+    const suffix = detail.length > 0 ? `, ${detail}` : '';
+    /** @type {FileSystemError} */
+    const error = /** @type {FileSystemError} */ (new Error(`${code}: ${syscall} '${targetPath}'${suffix}`));
+    error.code = code;
+    error.errno = code;
+    error.syscall = syscall;
+    error.path = targetPath;
+    return error;
+};
+/**
+ * Translates a `DOMException` thrown by a Web API into an errno-style error.
+ *
+ * @param {unknown} error The value caught from a browser call.
+ * @param {string} syscall Name of the originating operation.
+ * @param {string} targetPath Path the operation was applied to.
+ * @param {string} [mismatchCode] Error code used when the entry exists with the wrong type.
+ * @returns {FileSystemError | Error} An errno-style error.
+ */
+export const toFileSystemError = (error, syscall, targetPath, mismatchCode = 'ENOTDIR') => {
+    if (typeof DOMException !== 'undefined' && error instanceof DOMException) {
+        switch (error.name) {
+            case 'NotFoundError':
+                return createFileSystemError('ENOENT', syscall, targetPath);
+            case 'TypeMismatchError':
+                return createFileSystemError(mismatchCode, syscall, targetPath);
+            case 'InvalidModificationError':
+                return createFileSystemError('ENOTEMPTY', syscall, targetPath);
+            case 'NoModificationAllowedError':
+                return createFileSystemError('EBUSY', syscall, targetPath);
+            case 'NotAllowedError':
+                return createFileSystemError('EACCES', syscall, targetPath);
+            default:
+                return createFileSystemError('EIO', syscall, targetPath, error.message);
+        }
+    }
+    return error instanceof Error ? error : new Error(String(error));
+};
+/**
+ * Validates that a value is a usable path string.
+ *
+ * @param {unknown} value Candidate value.
+ * @param {string} argumentName Name used in the thrown message.
+ * @returns {string} The validated path.
+ * @throws {TypeError} When the value is not a string or contains a null byte.
+ * @throws {Error} When the value is empty.
+ */
+export const assertPath = (value, argumentName) => {
+    if (typeof value !== 'string') {
+        const received = value === null ? 'null' : typeof value;
+        throw new TypeError(`The "${argumentName}" argument must be of type string. Received ${received}`);
+    }
+    if (value.length === 0) {
+        throw createFileSystemError('ENOENT', 'open', value, 'path must not be empty');
+    }
+    if (value.includes(NULL_BYTE)) {
+        throw new TypeError('The "path" argument must not contain null bytes');
+    }
+    return value;
+};
+/**
+ * Validates that a value is a plain options object.
+ *
+ * @param {unknown} value Candidate value.
+ * @param {string} functionName Name used in the thrown message.
+ * @returns {Record<string, unknown>} The validated options object.
+ * @throws {TypeError} When the value is not a plain object.
+ */
+export const assertOptionsObject = (value, functionName) => {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        const received = value === null ? 'null' : Array.isArray(value) ? 'Array' : typeof value;
+        throw new TypeError(`The "options" argument must be of type object. Received ${received} in ${functionName}()`);
+    }
+    return /** @type {Record<string, unknown>} */ (value);
+};
+/**
+ * Validates an encoding identifier.
+ *
+ * @param {unknown} value Candidate encoding.
+ * @param {string} functionName Name used in the thrown message.
+ * @returns {string | null} The validated encoding, or `null` for binary mode.
+ * @throws {TypeError} When the encoding is not supported.
+ */
+export const assertEncoding = (value, functionName) => {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value !== 'string' || !SUPPORTED_ENCODINGS.includes(value)) {
+        throw new TypeError(`The "encoding" option must be one of ${SUPPORTED_ENCODINGS.join(', ')}. ` +
+            `Received ${String(value)} in ${functionName}()`);
+    }
+    return value;
+};
+/**
+ * Validates a POSIX permission bitmask.
+ *
+ * @param {unknown} value Candidate mode.
+ * @param {string} argumentName Name used in the thrown message.
+ * @returns {number} The validated mode.
+ * @throws {TypeError} When the value is not an integer.
+ * @throws {RangeError} When the value is outside the 12-bit range.
+ */
+export const assertMode = (value, argumentName) => {
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw new TypeError(`The "${argumentName}" argument must be an integer`);
+    }
+    if (value < 0 || value > 0o7777) {
+        throw new RangeError(`The "${argumentName}" argument must be between 0o0000 and 0o7777`);
+    }
+    return value;
+};
+/**
+ * Validates a non-negative integer.
+ *
+ * @param {unknown} value Candidate value.
+ * @param {string} argumentName Name used in the thrown message.
+ * @returns {number} The validated integer.
+ * @throws {TypeError} When the value is not an integer.
+ * @throws {RangeError} When the value is negative.
+ */
+export const assertInteger = (value, argumentName) => {
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw new TypeError(`The "${argumentName}" argument must be an integer`);
+    }
+    if (value < 0) {
+        throw new RangeError(`The "${argumentName}" argument must not be negative`);
+    }
+    return value;
+};

package/dist/v1/libs/fs/handle.cjs

@@ -0,0 +1,121 @@
+'use strict';
+
+var error = require('./error.cjs');
+
+/**
+ * @file Thin facade returned by {@link TinyFSCore#open}.
+ */
+
+
+/**
+ * Handle returned by `open()`, shaped like `node:fs/promises.FileHandle`.
+ *
+ * The handle is a facade over the originating {@link TinyFSCore} instance.
+ * Every method delegates back to the file system, so no file descriptor is
+ * actually held open.
+ */
+class FileHandle {
+  /** @type {import('./index.mjs').default} */
+  #fs;
+
+  /** @type {string} */
+  #path;
+
+  /** @type {string} */
+  #flags;
+
+  /** @type {boolean} */
+  #closed;
+
+  /**
+   * @param {import('./index.mjs').default} fs Originating file system.
+   * @param {string} path Absolute path of the opened file.
+   * @param {string} flags Access mode the handle was opened with.
+   */
+  constructor(fs, path, flags) {
+    this.#fs = fs;
+    this.#path = path;
+    this.#flags = flags;
+    this.#closed = false;
+  }
+
+  /** @returns {string} Absolute path of the opened file. */
+  get path() {
+    return this.#path;
+  }
+
+  /** @returns {string} Access mode the handle was opened with. */
+  get flags() {
+    return this.#flags;
+  }
+
+  /** @returns {boolean} `true` once `close()` has been awaited. */
+  get closed() {
+    return this.#closed;
+  }
+
+  /**
+   * @param {import('./index.mjs').TReadFileOptions} [options] Read options.
+   * @returns {Promise<string | Uint8Array>} The file contents.
+   */
+  async readFile(options) {
+    this.#assertOpen();
+    return this.#fs.readFile(this.#path, options);
+  }
+
+  /**
+   * @param {string | Uint8Array | ArrayBuffer} data Payload to persist.
+   * @param {import('./index.mjs').TWriteFileOptions} [options] Write options.
+   * @returns {Promise<void>} Resolves once the payload is committed.
+   */
+  async writeFile(data, options) {
+    this.#assertOpen();
+    return this.#fs.writeFile(this.#path, data, options);
+  }
+
+  /**
+   * @param {string | Uint8Array | ArrayBuffer} data Payload to append.
+   * @param {import('./index.mjs').TWriteFileOptions} [options] Write options.
+   * @returns {Promise<void>} Resolves once the payload is committed.
+   */
+  async appendFile(data, options) {
+    this.#assertOpen();
+    return this.#fs.appendFile(this.#path, data, options);
+  }
+
+  /**
+   * @returns {Promise<import('./stats.mjs').Stats>} A fresh snapshot of the file metadata.
+   */
+  async stat() {
+    this.#assertOpen();
+    return this.#fs.stat(this.#path);
+  }
+
+  /**
+   * @param {number} [length] Target length in bytes.
+   * @returns {Promise<void>} Resolves once the file is truncated.
+   */
+  async truncate(length) {
+    this.#assertOpen();
+    return this.#fs.truncate(this.#path, length);
+  }
+
+  /**
+   * @returns {Promise<void>} Resolves once the handle is released.
+   */
+  async close() {
+    this.#closed = true;
+  }
+
+  /**
+   * @returns {void}
+   * @throws {Error} When the handle has already been closed.
+   */
+  #assertOpen() {
+    if (this.#closed) {
+      throw error.createFileSystemError('EBADF', 'read', this.#path, 'file handle is closed');
+    }
+  }
+}
+
+exports.FileHandle = FileHandle;