tiny-essentials 1.28.18 → 1.29.0

package/docs/v1/libs/fs/TinyFS.md

@@ -0,0 +1,752 @@
+# 🗄️ TinyFS Core
+
+> A tiny, dependency-free, `node:fs/promises`-compatible file system core written in pure ESM JavaScript.
+
+TinyFS Core is an **abstract base class**. It gives you a complete, promise-based file system
+API surface — `readFile`, `writeFile`, `readdir`, `stat`, `chmod`, `rename`, and friends — while
+delegating the actual byte storage to a backend you write.
+
+The base class is **not a stub**. It ships with a working in-memory side table for permissions,
+ownership and timestamps, so a backend only has to answer one question: *"where do the bytes
+live?"*
+
+---
+
+## 📑 Table of Contents
+
+1. [Features](#-features)
+2. [Requirements](#-requirements)
+3. [Project Layout](#-project-layout)
+4. [Quick Start](#-quick-start)
+5. [Core Concepts](#-core-concepts)
+   - [The Metadata Side Table](#1--the-metadata-side-table)
+   - [Protected Hooks](#2--protected-hooks)
+   - [Capabilities](#3--capabilities)
+   - [Identity and Permissions](#4--identity-and-permissions)
+6. [API Reference](#-api-reference)
+   - [Constructor](#constructor)
+   - [Instance Getters](#instance-getters)
+   - [Static Members](#static-members)
+   - [File Operations](#-file-operations)
+   - [Directory Operations](#-directory-operations)
+   - [Metadata Operations](#-metadata-operations)
+   - [Path Operations](#-path-operations)
+   - [Handles](#-handles)
+7. [Building a Backend](#-building-a-backend)
+8. [Error Codes](#-error-codes)
+9. [Known Divergences and Gotchas](#-known-divergences-and-gotchas)
+10. [Cheatsheet](#-cheatsheet)
+
+---
+
+## ✨ Features
+
+| Feature | Status |
+| --- | --- |
+| 🧩 Zero runtime dependencies | ✅ |
+| 📦 Pure ESM (`import` / `export`) | ✅ |
+| 🔒 Private class fields with getters | ✅ |
+| 🧪 Trivially mockable | ✅ |
+| 🪟 Windows-style path handling | ❌ POSIX only |
+| 🔗 Symbolic links | ❌ Base class only |
+| 🧵 Concurrent write safety | ❌ Backend's responsibility |
+
+---
+
+## 📋 Requirements
+
+- **Node.js** `>= 18.0.0` (native ESM, private class fields, `Object.freeze` on statics).
+- A module resolver that understands the `.mjs` extension.
+
+---
+
+## 📁 Project Layout
+
+The core module imports from six sibling modules. Your tree should look like this:
+
+```text
+src/
+├── index.mjs       # TinyFSCore — the abstract class
+├── constants.mjs   # DEFAULT_FILE_MODE, DEFAULT_DIRECTORY_MODE, DEFAULT_UMASK, ROOT_PATH, constants
+├── error.mjs       # assertPath, assertInteger, assertMode, assertOptionsObject,
+│                   # assertEncoding, createFileSystemError
+├── encoding.mjs    # decodeBytes, toUint8Array
+├── stats.mjs       # Stats, Dirent
+├── handle.mjs      # FileHandle
+└── path.mjs        # toSegments
+```
+
+---
+
+## 🚀 Quick Start
+
+```javascript
+import MemoryFileSystem from './memory-fs.mjs';
+
+const fs = new MemoryFileSystem({ cwd: '/app' });
+
+// Write and read text.
+await fs.writeFile('/app/notes.txt', 'hello world', { encoding: 'utf8' });
+const text = await fs.readFile('/app/notes.txt', { encoding: 'utf8' });
+
+console.log(text); // "hello world"
+
+// Inspect metadata.
+const stats = await fs.stat('/app/notes.txt');
+console.log(stats.size);
+console.log(stats.mode.toString(8));
+
+// Clean up.
+await fs.rm('/app/notes.txt');
+```
+
+> 💡 The example above requires a backend. Jump to
+> [Building a Backend](#-building-a-backend) for a complete, copy-pasteable implementation.
+
+---
+
+## 🧠 Core Concepts
+
+### 1. 🗂️ The Metadata Side Table
+
+Every `TinyFSCore` instance owns a private `Map`:
+
+```javascript
+#metadata = new Map(); // Map<string, FSMetadata>
+```
+
+This map stores `mode`, `uid`, `gid`, `atimeMs`, `mtimeMs` and `birthtimeMs` for each path.
+**Your backend never touches it directly.** The public methods read and write it for you.
+
+The shape of each record is:
+
+```javascript
+/**
+ * @typedef {Object} FSMetadata
+ * @property {number | null} mode
+ * @property {number | null} uid
+ * @property {number | null} gid
+ * @property {number | null} atimeMs
+ * @property {number | null} mtimeMs
+ * @property {number | null} birthtimeMs
+ */
+```
+
+A `null` field means *"not set"*. When `stat()` encounters a `null`, it substitutes a sensible
+default based on the entry kind.
+
+---
+
+### 2 🔌 Protected Hooks
+
+Methods prefixed with a single underscore are **hooks**. They are the contract between the core
+and your backend. Every hook receives **raw, already-validated values** — no encoding, no
+defaults, no metadata merging.
+
+| Hook | Purpose |
+| --- | --- |
+| `_readFile(path)` | Return the raw bytes of a file. |
+| `_writeFile(path, bytes, options)` | Persist bytes. Honour `options.append`. |
+| `_readdir(path)` | Return `FSDirectoryEntry[]`. |
+| `_mkdir(path, options)` | Create a directory. Honour `options.recursive`. |
+| `_rm(path, options)` | Remove an entry. Honour `recursive` and `force`. |
+| `_stat(path)` | Return an `FSStatDescriptor`, or `undefined` when missing. |
+| `_rename(oldPath, newPath)` | Move an entry. |
+| `_copyFile(source, destination, mode)` | Copy a file. |
+| `_readMetadata(path)` | Read the side table. **Rarely overridden.** |
+| `_writeMetadata(path, metadata)` | Write the side table. **Rarely overridden.** |
+
+Every hook throws `ENOSYS` by default, so an unimplemented operation fails loudly instead of
+silently corrupting data.
+
+---
+
+### 3. 🎚️ Capabilities
+
+`capabilities` is a **static getter** that advertises what a backend supports. It is frozen, so
+consumers can safely cache it.
+
+```javascript
+import TinyFSCore from 'tiny-essentials/libs/fs/TinyFSCore';
+
+console.log(TinyFSCore.capabilities);
+// {
+//   permissions: false,
+//   ownership: false,
+//   symlinks: false,
+//   timestamps: false,
+//   atomicRename: false,
+//   seekableHandles: false
+// }
+```
+
+> ⚠️ Because it is `static`, read it from the **class**, not the instance:
+> `MyBackend.capabilities`. Inside an instance method, use `this.constructor.capabilities`.
+
+---
+
+### 4. 🔐 Identity and Permissions
+
+The constructor accepts an `FSIdentity`. The `access()` method uses it to decide which permission
+triad applies:
+
+| Condition | Triad | Bit shift |
+| --- | --- | --- |
+| `uid === identity.uid` | Owner | `>> 6` |
+| `gid === identity.gid` or in `identity.groups` | Group | `>> 3` |
+| Otherwise | Other | `>> 0` |
+
+```javascript
+const fs = new MemoryFileSystem({
+  identity: { uid: 1000, gid: 1000, groups: [27, 100] },
+});
+```
+
+---
+
+## 📚 API Reference
+
+### Constructor
+
+```javascript
+new TinyFSCore(options?)
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `options.cwd` | `string` | `ROOT_PATH` | Working directory used to resolve relative paths. |
+| `options.umask` | `number` | `DEFAULT_UMASK` | Mask applied to `mode` on creation. |
+| `options.identity` | `FSIdentity` | `{ uid: 0, gid: 0, groups: [] }` | Effective identity used by `access()`. |
+
+```javascript
+const fs = new MemoryFileSystem({
+  cwd: '/srv/app',
+  umask: 0o022,
+  identity: { uid: 1000, gid: 1000, groups: [] },
+});
+```
+
+---
+
+### Instance Getters
+
+```javascript
+fs.cwd;      // string       — the configured working directory
+fs.umask;    // number       — the configured umask
+fs.identity; // FSIdentity  — the effective identity
+```
+
+---
+
+### Static Members
+
+```javascript
+TinyFSCore.capabilities; // Readonly<FSCapabilities>
+```
+
+---
+
+### 📄 File Operations
+
+#### `readFile(path, options?)`
+
+Reads the entire contents of a file.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | Absolute path of the file. |
+| `options.encoding` | `string \| null` | When omitted or `null`, resolves to a `Uint8Array`. |
+
+**Returns:** `Promise<string | Uint8Array>`
+
+```javascript
+const buffer = await fs.readFile('/data/blob.bin');         // Uint8Array
+const text   = await fs.readFile('/data/notes.txt', { encoding: 'utf8' });
+```
+
+---
+
+#### `writeFile(path, data, options?)`
+
+Writes data to a file, replacing it when it already exists.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | Absolute path of the file. |
+| `data` | `string \| Uint8Array \| ArrayBuffer` | Payload to persist. |
+| `options.encoding` | `string \| null` | Used to serialise string input. |
+| `options.append` | `boolean` | When `true`, appends instead of replacing. |
+| `options.mode` | `number` | Permission bits applied **when the file is created**. |
+
+**Returns:** `Promise<void>`
+
+```javascript
+await fs.writeFile('/logs/app.log', 'boot\n', { mode: 0o640 });
+```
+
+> ⚠️ Metadata is written **only when the file does not exist yet**. Overwriting an existing file
+> preserves its original `mode`, `uid`, `gid` and `birthtimeMs`.
+
+---
+
+#### `appendFile(path, data, options?)`
+
+Convenience wrapper around `writeFile` with `append: true`. Creates the file when missing.
+
+```javascript
+await fs.appendFile('/logs/app.log', 'request handled\n');
+```
+
+---
+
+#### `copyFile(sourcePath, destinationPath, mode?)`
+
+Copies a file and duplicates its metadata record.
+
+```javascript
+await fs.copyFile('/a.txt', '/b.txt');
+```
+
+> ⚠️ **Divergence:** the JSDoc advertises `number | TCopyFileOptions`, but the implementation
+> only honours the `number` form. Passing an object silently resolves to `0`.
+
+---
+
+#### `truncate(path, length?)`
+
+Resizes a file to `length` bytes. Shorter files are zero-padded; longer files are cut.
+
+```javascript
+await fs.truncate('/data.bin', 1024);
+await fs.truncate('/data.bin'); // length defaults to 0
+```
+
+---
+
+### 📁 Directory Operations
+
+#### `readdir(path, options?)`
+
+Reads directory entries.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `options.withFileTypes` | `boolean` | When `true`, resolves to `Dirent[]`. |
+| `options.recursive` | `boolean` | When `true`, walks sub-directories depth-first. |
+
+**Returns:** `Promise<Array<string | Dirent>>`
+
+```javascript
+const names = await fs.readdir('/src');
+const dirents = await fs.readdir('/src', { withFileTypes: true });
+const tree = await fs.readdir('/src', { recursive: true });
+```
+
+> ⚠️ **Divergence:** in recursive mode, nested entries are always reported with the kind
+> `'file'`, even when they are directories.
+
+---
+
+#### `mkdir(path, options?)`
+
+Creates a directory.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `options.recursive` | `boolean` | When `true`, missing parents are created. |
+| `options.mode` | `number` | Permission bits for the new directory. |
+
+**Returns:** `Promise<string | undefined>` — the created path when `recursive` is `true`.
+
+```javascript
+await fs.mkdir('/var/lib/app', { recursive: true, mode: 0o755 });
+```
+
+---
+
+#### `rm(path, options?)`
+
+Removes a file, or a directory tree when `recursive` is `true`.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `options.recursive` | `boolean` | Removes directories and their contents. |
+| `options.force` | `boolean` | When `true`, a missing path is not an error. |
+
+```javascript
+await fs.rm('/tmp/cache', { recursive: true, force: true });
+```
+
+---
+
+#### `unlink(path)`
+
+Removes a file. Throws `EISDIR` when the path is a directory.
+
+```javascript
+await fs.unlink('/tmp/old.log');
+```
+
+---
+
+#### `rmdir(path, options?)`
+
+Removes a directory. Forwards to `rm()`.
+
+```javascript
+await fs.rmdir('/tmp/empty');
+```
+
+---
+
+#### `rename(oldPath, newPath)`
+
+Moves an entry and carries its metadata record across.
+
+```javascript
+await fs.rename('/tmp/draft.md', '/docs/final.md');
+```
+
+---
+
+### 🏷️ Metadata Operations
+
+#### `stat(path, options?)`
+
+Retrieves a `Stats` snapshot. Throws `ENOENT` when the path is missing.
+
+```javascript
+const stats = await fs.stat('/etc/hosts');
+console.log(stats.size, stats.mode.toString(8));
+```
+
+---
+
+#### `lstat(path, options?)`
+
+Alias of `stat()`. The base class has no symbolic links, so both behave identically.
+
+---
+
+#### `chmod(path, mode)`
+
+Changes the permission bits.
+
+```javascript
+await fs.chmod('/usr/local/bin/tool', 0o755);
+```
+
+---
+
+#### `chown(path, uid, gid?)`
+
+Changes ownership. `gid` defaults to `uid`.
+
+```javascript
+await fs.chown('/var/www', 33, 33);
+```
+
+---
+
+#### `utimes(path, atimeMs, mtimeMs?)`
+
+Updates the access and modification times. `mtimeMs` defaults to `atimeMs`.
+
+```javascript
+await fs.utimes('/var/log/app.log', Date.now(), Date.now());
+```
+
+---
+
+#### `access(path, mode?)`
+
+Checks whether a path is reachable with the requested permission.
+
+| Constant | Meaning |
+| --- | --- |
+| `constants.F_OK` | Existence only (default). |
+| `constants.R_OK` | Read permission. |
+| `constants.W_OK` | Write permission. |
+| `constants.X_OK` | Execute permission. |
+
+**Throws:** `Error` with `code: 'EACCES'` when the permission is missing.
+
+```javascript
+try {
+  await fs.access('/etc/shadow', constants.R_OK);
+} catch (error) {
+  console.error(error.code); // "EACCES"
+}
+```
+
+> ⚠️ **Divergence:** `chmod`, `chown` and `utimes` do **not** verify that the path exists.
+> They will happily create an orphan metadata record. Call `stat()` first if that matters.
+
+---
+
+### 🛣️ Path Operations
+
+#### `realpath(path)`
+
+Resolves the canonical absolute path. Throws `ENOENT` when the path is missing.
+
+```javascript
+await fs.realpath('/var/../var/log/./app.log');
+// "/var/log/app.log"
+```
+
+---
+
+#### `exists(path)`
+
+Reports whether a path exists. Never throws for a missing path.
+
+```javascript
+if (await fs.exists('/etc/hosts')) {
+  console.log('found');
+}
+```
+
+---
+
+### 🔓 Handles
+
+#### `open(path, flags?)`
+
+Opens a file and returns a `FileHandle`.
+
+| Flag | Behaviour |
+| --- | --- |
+| `'r'` (default) | Verifies the file exists. |
+| `'w'` | Truncates the file. |
+| `'a'` | Opens for appending. |
+
+```javascript
+const handle = await fs.open('/data/report.csv', 'w');
+```
+
+---
+
+## 🏗️ Building a Backend
+
+A complete, working in-memory backend. This is the smallest useful implementation.
+
+```javascript
+import TinyFSCore from 'tiny-essentials/libs/fs/TinyFSCore';
+import { createFileSystemError } from 'tiny-essentials/libs/fs/error.mjs';
+
+/**
+ * In-memory file system used for tests and local development.
+ * @augments TinyFSCore
+ */
+export class MemoryFileSystem extends TinyFSCore {
+  /** @type {Map<string, Uint8Array>} */
+  #files = new Map();
+
+  /** @type {Set<string>} */
+  #directories = new Set(['/']);
+
+  /**
+   * @returns {import('tiny-essentials/libs/fs/TinyFSCore').FSCapabilities} The capabilities of this backend.
+   */
+  static get capabilities() {
+    return Object.freeze({
+      permissions: true,
+      ownership: true,
+      symlinks: false,
+      timestamps: true,
+      atomicRename: true,
+      seekableHandles: false,
+    });
+  }
+
+  /**
+   * @param {string} targetPath Absolute path of the file.
+   * @returns {Promise<Uint8Array>} The raw file contents.
+   */
+  async _readFile(targetPath) {
+    const bytes = this.#files.get(targetPath);
+    if (bytes === undefined) {
+      throw createFileSystemError('ENOENT', 'open', targetPath);
+    }
+    return bytes;
+  }
+
+  /**
+   * @param {string} targetPath Absolute path of the file.
+   * @param {Uint8Array} bytes Payload to persist.
+   * @param {{ append: boolean, mode: number | undefined }} options Write options.
+   * @returns {Promise<void>} Resolves once the payload is committed.
+   */
+  async _writeFile(targetPath, bytes, options) {
+    const previous = options.append ? this.#files.get(targetPath) ?? new Uint8Array(0) : new Uint8Array(0);
+    const merged = new Uint8Array(previous.length + bytes.length);
+    merged.set(previous, 0);
+    merged.set(bytes, previous.length);
+    this.#files.set(targetPath, merged);
+  }
+
+  /**
+   * @param {string} targetPath Absolute path of the directory.
+   * @returns {Promise<import('tiny-essentials/libs/fs/stats.mjs').FSDirectoryEntry[]>} The directory entries.
+   */
+  async _readdir(targetPath) {
+    const prefix = targetPath.endsWith('/') ? targetPath : `${targetPath}/`;
+    const entries = new Map();
+
+    for (const filePath of this.#files.keys()) {
+      if (!filePath.startsWith(prefix)) continue;
+      const [name, ...rest] = filePath.slice(prefix.length).split('/');
+      entries.set(name, { name, kind: rest.length === 0 ? 'file' : 'directory' });
+    }
+
+    return [...entries.values()];
+  }
+
+  /**
+   * @param {string} targetPath Absolute path of the directory.
+   * @returns {Promise<void>} Resolves once the directory exists.
+   */
+  async _mkdir(targetPath) {
+    this.#directories.add(targetPath);
+  }
+
+  /**
+   * @param {string} targetPath Absolute path of the entry.
+   * @returns {Promise<void>} Resolves once the entry is gone.
+   */
+  async _rm(targetPath) {
+    this.#files.delete(targetPath);
+    this.#directories.delete(targetPath);
+  }
+
+  /**
+   * @param {string} targetPath Absolute path of the entry.
+   * @returns {Promise<import('tiny-essentials/libs/fs/stats.mjs').FSStatDescriptor | undefined>} The descriptor.
+   */
+  async _stat(targetPath) {
+    const bytes = this.#files.get(targetPath);
+    if (bytes !== undefined) {
+      return { name: targetPath.split('/').pop() ?? '', kind: 'file', size: bytes.length, mtimeMs: Date.now() };
+    }
+    if (this.#directories.has(targetPath)) {
+      return { name: targetPath.split('/').pop() ?? '', kind: 'directory', size: 0, mtimeMs: Date.now() };
+    }
+    return undefined;
+  }
+
+  /**
+   * @param {string} oldPath Current absolute path.
+   * @param {string} newPath Target absolute path.
+   * @returns {Promise<void>} Resolves once the move is complete.
+   */
+  async _rename(oldPath, newPath) {
+    const bytes = this.#files.get(oldPath);
+    if (bytes === undefined) {
+      throw createFileSystemError('ENOENT', 'rename', oldPath);
+    }
+    this.#files.set(newPath, bytes);
+    this.#files.delete(oldPath);
+  }
+
+  /**
+   * @param {string} sourcePath Absolute path of the source file.
+   * @param {string} destinationPath Absolute path of the destination file.
+   * @returns {Promise<void>} Resolves once the copy is complete.
+   */
+  async _copyFile(sourcePath, destinationPath) {
+    const bytes = await this._readFile(sourcePath);
+    this.#files.set(destinationPath, Uint8Array.from(bytes));
+  }
+}
+```
+
+### ✅ Backend Checklist
+
+1. Extend `TinyFSCore`.
+2. Override `static get capabilities()` and return a frozen object.
+3. Implement only the hooks your use case needs. Everything else throws `ENOSYS`.
+4. **Never** handle encoding, validation or metadata inside a hook. That is the core's job.
+5. Throw `createFileSystemError(code, syscall, path)` instead of a bare `Error`.
+
+---
+
+## 🚨 Error Codes
+
+All errors are created through `createFileSystemError(code, syscall, path, message?)`.
+
+| Code | Thrown by | Meaning |
+| --- | --- | --- |
+| `ENOENT` | `stat`, `access`, `realpath`, `open` | No such file or directory. |
+| `EACCES` | `access` | Permission denied. |
+| `EISDIR` | `unlink` | The path is a directory. |
+| `ENOSYS` | Any unoverridden hook | The backend does not implement this operation. |
+
+```javascript
+try {
+  await fs.readFile('/missing.txt');
+} catch (error) {
+  console.error(error.code);    // "ENOENT"
+  console.error(error.syscall); // "open"
+  console.error(error.path);    // "/missing.txt"
+}
+```
+
+---
+
+## ⚠️ Known Divergences and Gotchas
+
+Read this section before you file a bug. These are the behaviours that differ from
+`node:fs/promises` or from the JSDoc.
+
+| # | Location | Behaviour |
+| --- | --- | --- |
+| 1 | `copyFile` | Accepts `TCopyFileOptions` in JSDoc but only honours the `number` form. Passing an object silently resolves to `0`. |
+| 2 | `readdir` | In `recursive` mode, every nested entry is reported with the kind `'file'`. |
+| 3 | `chmod` / `chown` / `utimes` | Do **not** verify that the path exists. They create orphan metadata records. |
+| 4 | `writeFile` | Writes metadata only on creation. Overwriting does **not** refresh `mtimeMs`. |
+| 5 | `rm` | Deletes only the exact path from the metadata map. Descendants keep their records. |
+| 6 | `lstat` | Alias of `stat`. There is no symlink support in the base class. |
+| 7 | `capabilities` | It is `static`. Use `this.constructor.capabilities` inside instance methods. |
+| 8 | `__stat` | Public by convention only. It is the internal implementation behind `stat`. |
+| 9 | `unlink` | Calls `__stat` first, so a missing file throws `ENOENT` before `rm` runs. |
+
+---
+
+## 🧾 Cheatsheet
+
+```javascript
+// ─── Setup ────────────────────────────────────────────────────────────
+const fs = new MemoryFileSystem({ cwd: '/app', umask: 0o022 });
+
+// ─── Files ────────────────────────────────────────────────────────────
+await fs.writeFile('/a.txt', 'data', { encoding: 'utf8' });
+await fs.appendFile('/a.txt', 'more');
+const buffer = await fs.readFile('/a.txt');               // Uint8Array
+const text = await fs.readFile('/a.txt', { encoding: 'utf8' });
+await fs.copyFile('/a.txt', '/b.txt');
+await fs.truncate('/a.txt', 2);
+await fs.unlink('/a.txt');
+
+// ─── Directories ──────────────────────────────────────────────────────
+await fs.mkdir('/nested/dir', { recursive: true, mode: 0o755 });
+const names = await fs.readdir('/nested');
+const dirents = await fs.readdir('/nested', { withFileTypes: true });
+await fs.rmdir('/nested');
+await fs.rm('/nested', { recursive: true, force: true });
+
+// ─── Metadata ─────────────────────────────────────────────────────────
+const stats = await fs.stat('/a.txt');
+await fs.chmod('/a.txt', 0o600);
+await fs.chown('/a.txt', 1000, 1000);
+await fs.utimes('/a.txt', Date.now(), Date.now());
+await fs.access('/a.txt', 0o4);
+
+// ─── Paths ────────────────────────────────────────────────────────────
+await fs.rename('/a.txt', '/b.txt');
+const absolute = await fs.realpath('/a/../a.txt');
+const found = await fs.exists('/a.txt');
+
+// ─── Handles ──────────────────────────────────────────────────────────
+const handle = await fs.open('/a.txt', 'w');
+```