memfs 4.57.4 → 4.57.5

package/docs/adapters.md

@@ -0,0 +1,134 @@
+`memfs` bridges its two APIs in both directions:
+
+- **Node `fs`-to-FSA** (`memfs/lib/node-to-fsa`) --- expose any `fs`-like
+  filesystem (the real `fs`, a `memfs` volume, anything) through browser FSA
+  handles.
+- **FSA-to-Node `fs`** (`memfs/lib/fsa-to-node`) --- run `fs`-based code on
+  top of a real FSA directory (e.g. the browser's OPFS or a user-picked folder).
+
+## Node `fs`-to-FSA
+
+`nodeToFsa` wraps a folder of an `fs`-like filesystem into a `FileSystemDirectoryHandle`:
+
+```ts
+import {nodeToFsa} from 'memfs/lib/node-to-fsa';
+
+nodeToFsa(fs, dirPath: string, ctx?: {
+  mode?: 'read' | 'readwrite';   // default 'read'
+  syncHandleAllowed?: boolean;
+  separator?: '/' | '\\';
+}): FileSystemDirectoryHandle;
+```
+
+The `fs` argument can be Node's real `fs` module or any `fs`-like object,
+including a `memfs` instance:
+
+```ts
+import { memfs } from 'memfs';
+import { nodeToFsa } from 'memfs/lib/node-to-fsa';
+
+const { fs } = memfs({ '/files/note.txt': 'hi' });
+const dir = nodeToFsa(fs, '/files', { mode: 'readwrite' });
+
+const handle = await dir.getFileHandle('note.txt');
+await (await handle.getFile()).text(); // 'hi'
+
+const created = await dir.getFileHandle('new.txt', { create: true });
+const writable = await created.createWritable();
+await writable.write('data');
+await writable.close();
+```
+
+From here you have a real FSA
+handle: `getDirectoryHandle`, `removeEntry`, `entries()`, `createWritable()`,
+and (when `syncHandleAllowed`) `createSyncAccessHandle()` all work --- see
+[File System Access](/libs/memfs/file-system-access) for the handle surface.
+
+```jj.note
+The writable stream writes to a temporary `.crswap` swap file and atomically
+renames it over the target on `close()`, mirroring how Chrome implements FSA
+writes.
+```
+
+## FSA-to-Node `fs`
+
+`FsaNodeFs` implements the Node `fs` API on top of an FSA `FileSystemDirectoryHandle`.
+This lets `fs`-based packages run in the browser against OPFS or a directory the
+user granted access to.
+
+```ts
+import { FsaNodeFs } from 'memfs/lib/fsa-to-node';
+
+const fs = new FsaNodeFs(dir); // dir: a FileSystemDirectoryHandle (or a Promise of one)
+
+await fs.promises.writeFile('/hello.txt', 'Hello World!');
+await fs.promises.readFile('/hello.txt', 'utf8'); // 'Hello World!'
+```
+
+Out of the box the **asynchronous** methods are supported --- the callback API,
+the promises API, `createReadStream`, and `createWriteStream`:
+
+```ts
+fs.mkdir('/dir', err => {
+  /* ... */
+});
+fs.createWriteStream('/out.bin').end(Buffer.from([1, 2, 3]));
+```
+
+### Synchronous API
+
+The FSA API is asynchronous, so synchronous `fs` methods (`readFileSync`, `writeFileSync`, ...)
+need a helper that blocks the calling thread. `memfs` does this with a **Web Worker**
+plus `Atomics`/`SharedArrayBuffer`: the sync call parks on the main thread while
+the worker performs the async FSA work.
+
+Wire up the sync adapter and pass it to `FsaNodeFs`:
+
+```ts
+import { FsaNodeFs, FsaNodeSyncAdapterWorker } from 'memfs/lib/fsa-to-node';
+
+const adapter = await FsaNodeSyncAdapterWorker.start('https://<path>/worker.js', dir);
+const fs = new FsaNodeFs(dir, adapter);
+
+fs.writeFileSync('/hello.txt', 'Hello World!'); // now synchronous methods work
+```
+
+The worker file instantiates a `FsaNodeSyncWorker` (imported from the
+underlying package --- it is not re-exported through the `memfs/lib/fsa-to-node`
+entry point):
+
+```ts
+import { FsaNodeSyncWorker } from '@jsonjoy.com/fs-fsa-to-node/lib/worker/FsaNodeSyncWorker';
+
+if (typeof window === 'undefined') {
+  const worker = new FsaNodeSyncWorker();
+  worker.start();
+}
+```
+
+`SharedArrayBuffer` and `Atomics` require the page to be
+[cross-origin isolated](https://web.dev/cross-origin-isolation-guide/): serve
+over HTTPS and send these response headers.
+
+```ts
+// webpack devServer
+{
+  devServer: {
+    https: true,
+    headers: {
+      'Cross-Origin-Opener-Policy': 'same-origin',
+      'Cross-Origin-Embedder-Policy': 'require-corp',
+    },
+  },
+}
+```
+
+With that in place, most synchronous methods work too.
+
+## Demos
+
+The repository ships runnable browser demos:
+
+- **Async API and `WriteStream`** --- `yarn demo:fsa-to-node-zipfile`
+- **Synchronous API over a worker** --- `yarn demo:fsa-to-node-sync-tests`
+- **`isomorphic-git` on OPFS / FSA** --- `yarn demo:git-opfs`, `yarn demo:git-fsa`

package/docs/fsa.md

@@ -0,0 +1,133 @@
+The browser [File System Access (FSA) API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_Access_API)
+hands you a `FileSystemDirectoryHandle` and you navigate from
+there --- `getDirectoryHandle`, `getFileHandle`, `createWritable`, and so on. `memfs`
+provides a complete **in-memory** implementation of that API, useful for
+testing FSA/OPFS code in Node and for sandboxes that have no real disk.
+
+```ts
+import { fsa } from 'memfs/lib/fsa';
+
+const { dir, core } = fsa({ mode: 'readwrite' });
+
+const folder = await dir.getDirectoryHandle('new-folder', { create: true });
+const file = await folder.getFileHandle('file.txt', { create: true });
+await (await file.createWritable()).write('Hello, world!');
+
+core.toJSON(); // {'/new-folder/file.txt': 'Hello, world!'}
+```
+
+## `fsa()`
+
+```ts
+fsa(
+  ctx?: Partial<CoreFsaContext>,
+  core?: Superblock,   // defaults to a fresh in-memory filesystem
+  dirPath?: string,    // root for the returned handle, defaults to '/'
+): {
+  core: Superblock;                // the backing filesystem (toJSON / fromJSON)
+  dir: FileSystemDirectoryHandle;  // handle rooted at dirPath
+  FileSystemObserver: ...;         // change-observer constructor
+};
+```
+
+The context controls behaviour:
+
+| Option              | Default  | Meaning                                                           |
+| ------------------- | -------- | ----------------------------------------------------------------- |
+| `mode`              | `'read'` | `'read'` or `'readwrite'`. Write operations require `'readwrite'` |
+| `separator`         | `'/'`    | Path separator used by `core.toJSON` / `fromJSON`                 |
+| `syncHandleAllowed` | `false`  | Enables `createSyncAccessHandle()` on file handles                |
+| `locks`             | ---      | A `FileLockManager` controlling concurrent-write locks            |
+
+`core` is a `Superblock` --- the same in-memory store that backs `Volume` ---
+so you can serialize and seed the filesystem directly:
+
+```ts
+const { dir, core } = fsa({ mode: 'readwrite' });
+
+core.fromJSON({
+  'documents/readme.txt': 'Welcome!',
+  'photos/vacation.jpg': Buffer.from('...'),
+  'empty-folder': null,
+});
+
+const docs = await dir.getDirectoryHandle('documents');
+const readme = await docs.getFileHandle('readme.txt');
+await (await readme.getFile()).text(); // 'Welcome!'
+```
+
+## Directory handles
+
+A directory handle (`FileSystemDirectoryHandle`) supports the standard async
+methods:
+
+| Method                                | Description                                                        |
+| ------------------------------------- | ------------------------------------------------------------------ |
+| `getDirectoryHandle(name, {create?})` | Get or create a subdirectory                                       |
+| `getFileHandle(name, {create?})`      | Get or create a file                                               |
+| `removeEntry(name, {recursive?})`     | Delete a file or directory                                         |
+| `keys()` / `values()` / `entries()`   | Async iterators over children                                      |
+| `resolve(handle)`                     | Relative path (as `string[]`) from here to a descendant, or `null` |
+
+```ts
+for await (const [name, handle] of dir.entries()) {
+  handle.kind; // 'file' | 'directory'
+}
+```
+
+## File handles
+
+A file handle (`FileSystemFileHandle`) reads via `getFile()` and writes via a
+writable stream:
+
+| Method                                | Description                                                     |
+| ------------------------------------- | --------------------------------------------------------------- |
+| `getFile()`                           | Returns a `File` (use `.text()`, `.arrayBuffer()`, `.stream()`) |
+| `createWritable({keepExistingData?})` | Opens a `FileSystemWritableFileStream`                          |
+| `createSyncAccessHandle()`            | Synchronous read/write handle (only when `syncHandleAllowed`)   |
+
+## Writable streams
+
+`createWritable()` returns a `FileSystemWritableFileStream`. Write plain data,
+or structured write commands to seek and truncate:
+
+```ts
+const file = await dir.getFileHandle('log.csv', { create: true });
+const writable = await file.createWritable();
+
+await writable.write('timestamp,level\n'); // append data
+await writable.write({ type: 'write', position: 0, data: 'X' }); // write at offset
+await writable.write({ type: 'seek', position: 4 }); // move cursor
+await writable.write({ type: 'truncate', size: 10 }); // resize
+await writable.close(); // commit
+```
+
+```jj.note
+Writable streams take a **lock** on the file for the duration. A second
+`createWritable()` on the same file while one is open is rejected --- matching
+browser behaviour. The lock is released on `close()` or `abort()`.
+```
+
+## Sync access handles
+
+When `syncHandleAllowed` is set, file handles expose
+`createSyncAccessHandle()` --- the OPFS worker API with
+`read`/`write`/`getSize`/`truncate`/`flush`/`close`:
+
+```ts
+const { dir } = fsa({ mode: 'readwrite', syncHandleAllowed: true });
+const file = await dir.getFileHandle('data.bin', { create: true });
+const access = await file.createSyncAccessHandle();
+
+await access.write(new Uint8Array([1, 2, 3]), { at: 0 });
+await access.getSize(); // 3
+await access.close();
+```
+
+```jj.note
+The browser spec defines the sync-access-handle methods as *synchronous*. This
+in-memory implementation returns promises instead, so `await` them.
+```
+
+To go the other direction --- an `fs`-like API on top of an FSA handle, or FSA
+handles on top of an `fs` filesystem --- see [Adapters](/libs/memfs/adapters).

package/docs/index.ts

@@ -0,0 +1,55 @@
+import type { LibPage } from './types';
+
+export const page: LibPage = {
+  name: 'memfs',
+  title: 'memfs',
+  type: 'lib',
+  subtitle: 'In-memory Node.js fs API and browser File System Access API.',
+  pkg: 'memfs',
+  group: 'tooling',
+  repo: 'streamich/memfs',
+  repoPath: 'tree/master/packages/memfs',
+  tech: 'TypeScript',
+  techIcon: { set: 'lineicons', icon: 'typescript' },
+  showContentsTable: true,
+  children: [
+    {
+      name: 'Node fs API',
+      subtitle: 'The in-memory fs module: fs, vol, Volume, memfs(), and the supported method surface.',
+      // @ts-ignore
+      src: async () => (await import('./node.md')).default,
+    },
+    {
+      name: 'Volumes',
+      subtitle: 'Create volumes from JSON, export them back, and combine memfs with unionfs and fs-monkey.',
+      // @ts-ignore
+      src: async () => (await import('./volumes.md')).default,
+    },
+    {
+      name: 'File System (Access)',
+      subtitle: 'An in-memory implementation of the browser File System (Access) (FSA) API.',
+      // @ts-ignore
+      src: async () => (await import('./fsa.md')).default,
+    },
+    {
+      name: 'Adapters',
+      subtitle: 'Bridge between the Node fs API and the FSA API in either direction, including a sync bridge.',
+      // @ts-ignore
+      src: async () => (await import('./adapters.md')).default,
+    },
+    {
+      name: 'Snapshots',
+      subtitle: 'POJO, CBOR, and JSON snapshots of any fs directory, preserving symlinks and binary data.',
+      // @ts-ignore
+      src: async () => (await import('./snapshot.md')).default,
+    },
+    {
+      name: 'Tree printing',
+      subtitle: 'Render an ASCII tree of any fs directory.',
+      // @ts-ignore
+      src: async () => (await import('./print.md')).default,
+    },
+  ],
+  // @ts-ignore
+  src: async () => (await import('./text.md')).default,
+};

package/docs/node.md

@@ -0,0 +1,207 @@
+`memfs` implements [Node's `fs` API](https://nodejs.org/api/fs.html) in memory:
+synchronous, callback, and promise-based methods; read/write streams; file and
+directory watching; hard links and symlinks; i-nodes; file descriptors; and the
+`fs.constants`. It throws same errors as Node (with `.code` set, e.g.
+`ENOENT`), so code that branches on error codes keeps working.
+
+```ts
+import { fs } from 'memfs';
+
+fs.writeFileSync('/hello.txt', 'World!');
+fs.readFileSync('/hello.txt', 'utf8'); // 'World!'
+```
+
+## `memfs()` --- isolated instances
+
+`fs`/`vol` are a single shared default volume. For tests, prefer `memfs()`,
+which returns a brand-new, isolated pair so volumes never leak into each other:
+
+```ts
+import { memfs } from 'memfs';
+
+const { fs, vol } = memfs();
+```
+
+Seed it from a [nested JSON tree](/libs/memfs/volumes):
+
+```ts
+const { fs } = memfs({
+  '/app': {
+    'index.js': 'console.log(1)',
+    'package.json': '{"name": "app"}',
+  },
+});
+
+fs.readdirSync('/app'); // ['index.js', 'package.json']
+```
+
+The second argument is a cwd string or an options object:
+
+```ts
+interface MemfsOptions {
+  /** Working directory for resolving relative paths. Defaults to '/'. */
+  cwd?: string;
+  /** A process-like object controlling platform, uid, gid, and cwd(). */
+  process?: IProcess;
+}
+
+memfs(json?: NestedDirectoryJSON, cwdOrOpts?: string | MemfsOptions): {fs: IFs; vol: Volume};
+```
+
+```ts
+const { fs } = memfs({ './README.md': '# Hi' }, '/repo');
+fs.readFileSync('/repo/README.md', 'utf8'); // '# Hi'
+```
+
+## `fs` vs `vol`
+
+The package exports both `fs` and `vol`. They back onto the **same storage** but
+differ in shape:
+
+```ts
+import { fs, vol } from 'memfs';
+```
+
+- **`vol`** is a `Volume` instance --- it implements every `fs` method, plus
+  volume helpers like `fromJSON`/`toJSON`/`reset`/`toTree`. Its methods are
+  _not_ bound and it carries no `constants`:
+
+  ```ts
+  vol.writeFileSync('/foo', 'bar');
+  vol.F_OK; // undefined
+  ```
+
+- **`fs`** is an _fs-like_ object built from `vol` with `createFsFromVolume(vol)`.
+  All methods are **bound** (safe to destructure) and
+  it carries `constants`, `Stats`, `Dirent`, `ReadStream`, `promises`, etc. ---
+  identical in shape to `require('fs')`:
+
+  ```ts
+  const { readFileSync, writeFileSync } = fs; // bound, safe to destructure
+  fs.constants.O_RDONLY; // 0
+  ```
+
+Every member of the `fs` object is also re-exported at the top level, so you can
+treat `memfs` itself as the `fs` module:
+
+```ts
+import { readFileSync, F_OK, ReadStream } from 'memfs';
+```
+
+Use `vol` when you want the volume helpers; use `fs` (or `memfs()`) when you want
+a faithful `fs` drop-in.
+
+## `Volume` and `createFsFromVolume`
+
+`memfs()` is sugar over two lower-level pieces you can use directly:
+
+```ts
+import { Volume, createFsFromVolume } from 'memfs';
+
+const vol = new Volume();
+const fs = createFsFromVolume(vol);
+
+fs.writeFileSync('/foo', 'bar');
+```
+
+`new Volume()` is an empty filesystem. `createFsFromVolume(vol)` wraps it into
+the bound, `constants`-carrying `fs`-like object described above. Construct as
+many independent volumes as you need --- see [Volumes](/libs/memfs/volumes).
+
+## The promises API
+
+`fs.promises` (equivalently `vol.promises`) mirrors `fs/promises`:
+
+```ts
+const { fs } = memfs();
+
+await fs.promises.writeFile('/note.txt', 'hi');
+await fs.promises.readFile('/note.txt', 'utf8'); // 'hi'
+
+const handle = await fs.promises.open('/note.txt', 'r');
+const { bytesRead, buffer } = await handle.read(Buffer.alloc(2), 0, 2, 0);
+await handle.close();
+```
+
+## Streams
+
+`createReadStream` and `createWriteStream` return Node-compatible streams:
+
+```ts
+const { fs } = memfs({ '/in.txt': 'stream me' });
+
+const out = fs.createWriteStream('/out.txt');
+fs.createReadStream('/in.txt').pipe(out);
+out.on('finish', () => fs.readFileSync('/out.txt', 'utf8')); // 'stream me'
+```
+
+## Watching
+
+Both `fs.watch` (inode events) and `fs.watchFile` (stat polling) are
+implemented:
+
+```ts
+const { fs } = memfs({ '/log.txt': '' });
+
+const watcher = fs.watch('/log.txt', (eventType, filename) => {
+  // eventType: 'change' | 'rename'
+});
+
+fs.appendFileSync('/log.txt', 'entry\n');
+watcher.close();
+```
+
+## Supporting objects
+
+These are available both as named exports and as properties of the `fs` object.
+
+| Object        | Description                                                                                                                                                                                                        |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Stats`       | Result of `stat`/`lstat`/`fstat`. `Stats<bigint>` when `{bigint: true}`                                                                                                                                            |
+| `Dirent`      | Directory entry from `readdir({withFileTypes: true})` and `Dir`. Exposes `name`, `parentPath`, and `isFile()`/`isDirectory()`/`isSymbolicLink()`/... (the legacy `path` getter is deprecated --- use `parentPath`) |
+| `Dir`         | Async directory iterator from `opendir`. Implements `AsyncIterable<Dirent>` and `Symbol.asyncDispose`, so it works with `await using`                                                                              |
+| `StatFs`      | Result of `statfs`/`statfsSync`                                                                                                                                                                                    |
+| `FileHandle`  | Returned by `fs.promises.open()`                                                                                                                                                                                   |
+| `StatWatcher` | Returned by `watchFile`                                                                                                                                                                                            |
+| `FSWatcher`   | Returned by `watch`                                                                                                                                                                                                |
+
+`Dir` with `await using` (auto-closes on scope exit):
+
+```ts
+const { fs } = memfs({ '/d': { a: '', b: '' } });
+
+await using dir = await fs.promises.opendir('/d');
+for await (const entry of dir) {
+  entry.name; // 'a' then 'b'
+  entry.parentPath; // '/d'
+  entry.isFile(); // true
+}
+```
+
+## Relative paths
+
+Absolute paths behave as you would expect. **Relative** paths are resolved
+against `process.cwd()` --- which points at your _on-disk_ working directory,
+a folder that almost certainly does not exist inside the in-memory volume. The
+safe choice is to always use absolute paths.
+
+If you must use relative paths, either create the cwd inside the volume:
+
+```ts
+vol.mkdirSync(process.cwd(), { recursive: true });
+```
+
+or point the process at `/`, which exists in every volume:
+
+```ts
+process.chdir('/');
+```
+
+(You can also pass a `cwd` to [`memfs()`](/libs/memfs/node-fs-api) or a custom
+`process` object to control this per volume.)
+
+## Dependencies
+
+The Node `fs` implementation relies on the `buffer`, `events`, `stream`, and
+`path` built-ins, and uses the `process` and `setImmediate` globals (mocking
+them when unavailable), so it bundles cleanly for the browser.

package/docs/print.md

@@ -0,0 +1,78 @@
+`toTreeSync` renders an ASCII tree of a directory from any `fs`-like
+filesystem. Pass the filesystem and a starting folder; get back a string.
+
+It is published as its own package, which `memfs` already depends on:
+
+```ts
+import { toTreeSync } from '@jsonjoy.com/fs-print';
+```
+
+```ts
+import * as fs from 'fs';
+import { toTreeSync } from '@jsonjoy.com/fs-print';
+
+console.log(toTreeSync(fs, { dir: process.cwd() + '/src' }));
+// src/
+// ├─ __tests__/
+// │  ├─ index.test.ts
+// │  └─ node.test.ts
+// ├─ Dirent.ts
+// ├─ Stats.ts
+// ...
+```
+
+Any `fs` implementation works, including an in-memory `memfs` instance:
+
+```ts
+import { memfs } from 'memfs';
+import { toTreeSync } from '@jsonjoy.com/fs-print';
+
+const { fs } = memfs({
+  '/src': {
+    'index.ts': '...',
+    util: { 'print.ts': '...' },
+  },
+});
+
+console.log(toTreeSync(fs, { dir: '/src' }));
+// src/
+// ├─ index.ts
+// └─ util/
+//    └─ print.ts
+```
+
+Symlinks are rendered with an arrow to their target:
+
+```ts
+// /
+// ├─ a/
+// │  └─ b/
+// │     └─ file.txt
+// └─ goto → /a/b/file.txt
+```
+
+## Options
+
+```ts
+toTreeSync(fs: FsSynchronousApi, opts?: ToTreeOptions): string;
+
+interface ToTreeOptions {
+  dir?: string;            // starting directory, default '/'
+  depth?: number;          // max recursion depth, default 10
+  separator?: '/' | '\\';  // path separator, default '/'
+  tab?: string;            // prefix prepended to every line, default ''
+  sort?: boolean;          // sort entries (dirs first), default true
+}
+```
+
+By default entries are sorted alphabetically with folders first. Set
+`sort: false` to print them in raw filesystem order:
+
+```ts
+console.log(toTreeSync(fs, { sort: false }));
+```
+
+```jj.note
+`toTreeSync` is synchronous only --- there is no async variant. A `Volume` also
+has a built-in [`toTree()`](/libs/memfs/volumes) for the common in-memory case.
+```

package/docs/snapshot.md

@@ -0,0 +1,124 @@
+The snapshot utility captures a directory (or single file) from any `fs`-like
+filesystem into a portable value, and restores it later --- recursively, and
+preserving **symlinks** and **binary** content. It comes in three encodings:
+a plain POJO, a compact CBOR `Uint8Array`, and a JSON `Uint8Array`.
+
+It is published as its own package, which `memfs` already depends on:
+
+```ts
+import * as snapshot from '@jsonjoy.com/fs-snapshot';
+```
+
+```jj.note
+For the simple "string/Buffer contents only" case, a `Volume` has built-in
+[`toJSON` / `fromJSON`](/libs/memfs/volumes). Reach for snapshots when you need
+to preserve symlinks, round-trip binary data faithfully, or serialize to bytes
+(CBOR / JSON) for storage or transport.
+```
+
+## Options
+
+Every function takes a target descriptor. The synchronous functions want a
+synchronous `fs`; the async ones want a promises API:
+
+```ts
+// sync functions
+{fs: FsSynchronousApi, path?: string, separator?: '/' | '\\'}
+// async functions
+{fs: FsPromisesApi, path?: string, separator?: '/' | '\\'}
+```
+
+`path` defaults to `'/'`. Any `fs`-like object works --- `memfs`, the real
+`fs`, or an [adapter](/libs/memfs/adapters).
+
+## POJO snapshot
+
+`toSnapshot*` returns a `SnapshotNode` (a nested tuple, see below);
+`fromSnapshot*` writes it back into a filesystem.
+
+```ts
+const snap = snapshot.toSnapshotSync({ fs, path: '/app' });
+snapshot.fromSnapshotSync(snap, { fs: fs2, path: '/restored' });
+```
+
+```ts
+const snap = await snapshot.toSnapshot({ fs: fs.promises, path: '/app' });
+await snapshot.fromSnapshot(snap, { fs: fs2.promises, path: '/restored' });
+```
+
+## Binary snapshot (CBOR)
+
+Encoded as a CBOR `Uint8Array` --- compact and binary-safe, good for storing or
+sending a whole tree over the wire.
+
+```ts
+const bytes = snapshot.toBinarySnapshotSync({ fs, path: '/app' }); // Uint8Array
+snapshot.fromBinarySnapshotSync(bytes, { fs: fs2, path: '/app' });
+```
+
+```ts
+const bytes = await snapshot.toBinarySnapshot({ fs: fs.promises, path: '/app' });
+await snapshot.fromBinarySnapshot(bytes, { fs: fs2.promises, path: '/app' });
+```
+
+## JSON snapshot
+
+Same idea, JSON-encoded into a `Uint8Array`. Binary file contents are carried as
+Base64 data-URL strings, so the result is valid JSON yet still round-trips
+binary data.
+
+```ts
+const bytes = snapshot.toJsonSnapshotSync({ fs, path: '/app' }); // Uint8Array
+snapshot.fromJsonSnapshotSync(bytes, { fs: fs2, path: '/app' });
+```
+
+## Function reference
+
+| Format | To snapshot                                 | From snapshot                                   | Returns        |
+| ------ | ------------------------------------------- | ----------------------------------------------- | -------------- |
+| POJO   | `toSnapshotSync` / `toSnapshot`             | `fromSnapshotSync` / `fromSnapshot`             | `SnapshotNode` |
+| CBOR   | `toBinarySnapshotSync` / `toBinarySnapshot` | `fromBinarySnapshotSync` / `fromBinarySnapshot` | `Uint8Array`   |
+| JSON   | `toJsonSnapshotSync` / `toJsonSnapshot`     | `fromJsonSnapshotSync` / `fromJsonSnapshot`     | `Uint8Array`   |
+
+The `*Sync` variants take a synchronous `fs`; the others take `fs.promises` and
+return a `Promise`.
+
+## Encoding format
+
+A snapshot follows the [Compact JSON](https://jsonjoy.com/specs/compact-json)
+scheme: each node is a tuple whose first element is its type.
+
+```ts
+const enum SnapshotNodeType {
+  Folder = 0,
+  File = 1,
+  Symlink = 2,
+}
+```
+
+**Folder** --- type, metadata, and a map of children:
+
+```ts
+[
+  0,
+  {},
+  {
+    'file.bin': [1, {}, new Uint8Array([1, 2, 3])],
+  },
+];
+```
+
+**File** --- type, metadata, and contents as a `Uint8Array`:
+
+```ts
+[1, {}, new Uint8Array([1, 2, 3])];
+```
+
+**Symlink** --- type and metadata carrying the link `target`:
+
+```ts
+[2, { target: 'file.bin' }];
+```
+
+Because the format is structural and stable, a snapshot taken, restored into a
+fresh filesystem, and snapshotted again is deep-equal to the original.

package/docs/text.md

@@ -0,0 +1,71 @@
+`memfs` is an in-memory file system. It implements two APIs:
+
+- **Node's [`fs` module](https://nodejs.org/api/fs.html)** --- a drop-in
+  replacement you can use anywhere the `fs` module is expected (tests, mocks,
+  bundlers, sandboxes). Files live in memory instead of on disk.
+- **The browser [File System Access (FSA) API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_Access_API)**
+  --- the same `FileSystemDirectoryHandle` interface a browser exposes, backed
+  by memory.
+
+It also ships adapters that translate _between_ those two APIs, so you can run `fs`-based
+code in the browser on top of a real directory, or expose an `fs`-like filesystem through
+FSA handles. It runs in Node.js, Deno, Bun, and browsers, and stores file contents
+in `Uint8Array` buffers.
+
+```ts
+import { fs } from 'memfs';
+
+fs.writeFileSync('/hello.txt', 'Hello, World!');
+fs.readFileSync('/hello.txt', 'utf8'); // 'Hello, World!'
+
+fs.mkdirSync('/dir');
+fs.readdirSync('/'); // ['dir', 'hello.txt']
+```
+
+## Install
+
+```
+npm install memfs
+```
+
+## Two ways in
+
+The default export gives you a ready-to-use filesystem. `fs` is a bound, `require('fs')`-shaped
+object --- `vol` is the `Volume` behind it. They share the same storage.
+
+```ts
+import { fs, vol } from 'memfs';
+
+fs.writeFileSync('/script.sh', 'sudo rm -rf *');
+vol.toJSON(); // {'/script.sh': 'sudo rm -rf *'}
+```
+
+For an isolated filesystem (recommended for tests, so volumes never bleed into
+each other), call `memfs()` --- it returns a fresh `fs`/`vol` pair, optionally
+seeded from a JSON tree:
+
+```ts
+import { memfs } from 'memfs';
+
+const { fs, vol } = memfs({ '/app/index.js': 'console.log(1)' });
+
+fs.readFileSync('/app/index.js', 'utf8'); // 'console.log(1)'
+```
+
+## Surface map
+
+| Page                                                 | Import                                           | What it covers                                                                      |
+| ---------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| [Node fs API](/libs/memfs/node-fs-api)               | `memfs`                                          | The `fs`/`vol`/`Volume`/`memfs()` model and the full Node `fs` method surface       |
+| [Volumes](/libs/memfs/volumes)                       | `memfs`                                          | Building volumes from JSON, exporting them, and `unionfs` / `fs-monkey` integration |
+| [File System Access](/libs/memfs/file-system-access) | `memfs/lib/fsa`                                  | An in-memory FSA filesystem (`FileSystemDirectoryHandle` and friends)               |
+| [Adapters](/libs/memfs/adapters)                     | `memfs/lib/node-to-fsa`, `memfs/lib/fsa-to-node` | Convert between the `fs` API and the FSA API in either direction                    |
+| [Snapshots](/libs/memfs/snapshots)                   | `@jsonjoy.com/fs-snapshot`                       | POJO / CBOR / JSON snapshots of any `fs` directory                                  |
+| [Tree printing](/libs/memfs/tree-printing)           | `@jsonjoy.com/fs-print`                          | Print an ASCII tree of any `fs` directory                                           |
+
+```jj.note
+`memfs` is built from a set of smaller `@jsonjoy.com/fs-*` packages
+(`fs-node`, `fs-fsa`, `fs-node-to-fsa`, `fs-fsa-to-node`, `fs-snapshot`,
+`fs-print`, ...). Installing `memfs` pulls them all in; the snapshot and
+tree-printing utilities are also publishable on their own.
+```

package/docs/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Minimal, self-contained vendored copy of the `LibPage` / `ContentPage`
+ * documentation types from `@jsonjoy.com/ui`.
+ */
+
+export type PageTypes = 'blog' | 'resource' | 'spec' | 'spec-note' | 'lib';
+
+/** Landing-page category a library belongs to. */
+export type LibGroupId = 'tooling' | 'plain-text' | 'rich-text' | 'ui' | 'sync';
+
+/** Icon reference understood by the site renderer. */
+export interface IconSpec {
+  set: string;
+  icon: string;
+}
+
+/** A node in the documentation page tree. */
+export interface ContentPage {
+  /** Name of the item, shown in menus. Also used to derive the URL slug. */
+  name: string;
+  /** Type of the page. */
+  type?: PageTypes;
+  /** As displayed in the main page title. Defaults to `name`. */
+  title?: string;
+  /** One-line subtitle shown under the page title / in cards. */
+  subtitle?: string;
+  /** Up to a paragraph short description. */
+  about?: string;
+  /** Main Markdown body of the page, loaded lazily. */
+  src?: () => Promise<string>;
+  /** Whether a contents table is shown under the Markdown body. */
+  showContentsTable?: boolean;
+  /** Child pages. */
+  children?: ContentPage[];
+  /** NPM package name. */
+  pkg?: string;
+  /** GitHub repo name, e.g. `streamich/memfs`. */
+  repo?: string;
+  /** Path within the repo, e.g. `tree/master/packages/memfs`. */
+  repoPath?: string;
+}
+
+/** A code-library documentation page (root of a library's docs tree). */
+export interface LibPage extends ContentPage {
+  /** Published npm package name, e.g. `memfs`. */
+  pkg?: string;
+  /** Primary language or runtime, e.g. `TypeScript`, `Node.js`, `Web`. */
+  tech?: string;
+  /** Icon shown next to `tech` in the card. */
+  techIcon?: IconSpec;
+  /** Library technical identifier. */
+  libId?: string;
+  /** Landing-page category. Defaults to `tooling`. */
+  group?: LibGroupId;
+  /** Highlight this lib as a card at the top of the landing page. */
+  featured?: boolean;
+}

package/docs/volumes.md

@@ -0,0 +1,175 @@
+A `Volume` is one isolated in-memory filesystem. You can spin up as many as you
+like, seed them from a plain JSON object, and export their contents back to
+JSON --- which makes `memfs` convenient for fixtures and assertions.
+
+```ts
+import { Volume } from 'memfs';
+
+const vol = Volume.fromJSON({ '/foo': 'bar' });
+vol.readFileSync('/foo', 'utf8'); // 'bar'
+```
+
+## Building from JSON
+
+There are two JSON shapes. **Flat** maps full paths to contents:
+
+```ts
+type DirectoryJSON = { [path: string]: string | Buffer | null };
+```
+
+```ts
+const vol = Volume.fromJSON(
+  {
+    './README.md': '1',
+    './src/index.js': '2',
+    './node_modules/debug/index.js': '3',
+  },
+  '/app', // cwd: resolves the relative keys above
+);
+
+vol.readFileSync('/app/README.md', 'utf8'); // '1'
+vol.readFileSync('/app/src/index.js', 'utf8'); // '2'
+```
+
+**Nested** lets directories nest as objects --- handy for deeper trees:
+
+```ts
+const vol = Volume.fromNestedJSON({
+  '/app': {
+    'index.js': '...',
+    src: {
+      'main.ts': '...',
+      util: { 'log.ts': '...' },
+    },
+  },
+});
+```
+
+In both shapes the value `null` means an **empty directory** and an empty
+string `''` means an **empty file**. Values can be `string` or `Buffer`
+(binary). The instance methods `vol.fromJSON(json, cwd?)` and
+`vol.fromNestedJSON(json, cwd?)` add files into an existing volume; the static
+`Volume.fromJSON` / `Volume.fromNestedJSON` create a new one.
+
+```ts
+const vol = new Volume();
+vol.fromJSON({ '/a.txt': 'A' });
+vol.fromJSON({ '/b.txt': 'B' }); // merges in
+```
+
+```jj.note
+`vol.mountSync(mountpoint, json)` is a legacy alias for adding a flat JSON tree
+rooted at a given path. New code should use `fromJSON` with a cwd.
+```
+
+## Exporting to JSON
+
+`toJSON` walks the volume and returns a flat object --- the inverse of
+`fromJSON`. This is the workhorse for test assertions:
+
+```ts
+vol.writeFileSync('/foo', 'bar');
+vol.toJSON(); // {'/foo': 'bar'}
+```
+
+```ts
+expect(vol.toJSON()).toEqual({ '/foo': 'bar' });
+```
+
+The full signature lets you scope and shape the output:
+
+```ts
+vol.toJSON(
+  paths?: PathLike | PathLike[], // restrict to these paths; omit for everything
+  json?: {},                     // object to populate (for merging exports)
+  isRelative?: boolean,          // emit relative instead of absolute paths
+  asBuffer?: boolean,            // emit Buffer contents instead of strings
+): DirectoryJSON;
+```
+
+```ts
+const vol = Volume.fromJSON({ '/dir/a': 'b', '/dir2/a': 'b', '/dir2/c': 'd' });
+vol.toJSON('/dir2'); // {'/dir2/a': 'b', '/dir2/c': 'd'}
+```
+
+## Reset
+
+`reset()` empties a volume so you can reuse it between tests:
+
+```ts
+vol.fromJSON({ '/index.js': '...' });
+vol.toJSON(); // {'/index.js': '...'}
+vol.reset();
+vol.toJSON(); // {}
+```
+
+## Inspecting as a tree
+
+`toTree()` renders the volume as an ASCII tree (a quick built-in; for arbitrary
+`fs` filesystems and more options see [Tree printing](/libs/memfs/tree-printing)):
+
+```ts
+const { vol } = memfs({
+  '/src': {
+    'index.ts': '...',
+    util: { 'print.ts': '...' },
+  },
+});
+
+console.log(vol.toTree());
+// /
+// └─ src/
+//    ├─ index.ts
+//    └─ util/
+//       └─ print.ts
+```
+
+`toTree(opts?)` accepts a sub-folder, a `depth`, and a `separator`.
+
+## Many volumes
+
+Each `Volume` is fully independent:
+
+```ts
+const a = Volume.fromJSON({ '/foo': 'bar' });
+const b = Volume.fromJSON({ '/foo': 'baz' });
+
+a.readFileSync('/foo', 'utf8'); // 'bar'
+b.readFileSync('/foo', 'utf8'); // 'baz'
+```
+
+Reach for `memfs()` when you also want the bound, `constants`-carrying `fs`
+object alongside the volume --- see the [Node fs API](/libs/memfs/node-fs-api)
+page.
+
+## Combine with the real disk: `unionfs`
+
+[`unionfs`](https://github.com/streamich/unionfs) layers several filesystems
+into one. Overlay an in-memory volume on top of the real disk:
+
+```ts
+import * as realFs from 'fs';
+import { ufs } from 'unionfs';
+import { Volume } from 'memfs';
+
+const vol = Volume.fromJSON({ '/foo': 'bar' });
+
+ufs.use(realFs).use(vol);
+ufs.readFileSync('/foo', 'utf8'); // 'bar', served from the volume
+```
+
+## Patch `require`: `fs-monkey`
+
+[`fs-monkey`](https://github.com/streamich/fs-monkey) can point Node's module
+loader at a volume, so `require()` resolves modules out of memory:
+
+```ts
+import { patchRequire } from 'fs-monkey';
+
+vol.writeFileSync('/index.js', 'console.log("hi world")');
+patchRequire(vol);
+require('/index'); // logs: hi world
+```
+
+`fs-monkey` also exposes `patchFs(vol)` to monkey-patch the global `fs` module
+itself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memfs",
-  "version": "4.57.4",
+  "version": "4.57.5",
   "publishConfig": {
     "access": "public"
   },
@@ -49,6 +49,7 @@
     "lib",
     "dist",
     "README.md",
+    "docs",
     "LICENSE",
     "demo/runkit.js"
   ],
@@ -127,14 +128,14 @@
     "tslib": "2"
   },
   "dependencies": {
-    "@jsonjoy.com/fs-core": "4.57.4",
-    "@jsonjoy.com/fs-fsa": "4.57.4",
-    "@jsonjoy.com/fs-node": "4.57.4",
-    "@jsonjoy.com/fs-node-builtins": "4.57.4",
-    "@jsonjoy.com/fs-node-to-fsa": "4.57.4",
-    "@jsonjoy.com/fs-node-utils": "4.57.4",
-    "@jsonjoy.com/fs-print": "4.57.4",
-    "@jsonjoy.com/fs-snapshot": "4.57.4",
+    "@jsonjoy.com/fs-core": "4.57.5",
+    "@jsonjoy.com/fs-fsa": "4.57.5",
+    "@jsonjoy.com/fs-node": "4.57.5",
+    "@jsonjoy.com/fs-node-builtins": "4.57.5",
+    "@jsonjoy.com/fs-node-to-fsa": "4.57.5",
+    "@jsonjoy.com/fs-node-utils": "4.57.5",
+    "@jsonjoy.com/fs-print": "4.57.5",
+    "@jsonjoy.com/fs-snapshot": "4.57.5",
     "@jsonjoy.com/json-pack": "^1.11.0",
     "@jsonjoy.com/util": "^1.9.0",
     "glob-to-regex.js": "^1.0.1",