opfs-worker 2.1.0 → 2.1.1

package/docs/guides/async.md

@@ -16,7 +16,7 @@ await fs.appendText('/note.txt', '!');
 const text = await fs.readFile('/note.txt', 'utf-8');
 ```
 
-Import from `opfs-worker/async` if you care about bundle size — the main entry also carries the dedicated-worker path.
+Import from `opfs-worker/async` to keep the dedicated-worker code out of the bundle.
 
 ## Raw class
 
@@ -31,6 +31,6 @@ await fs.writeFile('/x.bin', new Uint8Array([1, 2, 3]));
 
 - **Writes** need `createWritable()` — Chrome, Firefox, Safari **26+**. Reads work anywhere OPFS does.
 - **No file descriptors** — `open` / `read` / `write` / … throw `ENOTSUP`.
-- Each write goes through a swap file and commits on close — fine for documents, awkward for tons of tiny random writes.
+- Each write goes through a swap file and commits on close — fine for documents, slow for many tiny random writes.
 
 Streaming still works: [streaming](./streaming.md). For one fs across tabs: [SharedWorker](./sharedworker.md).

package/docs/guides/dedicated.md

@@ -22,7 +22,7 @@ The worker is inlined by default, so you don’t need a special bundler worker s
 
 ## Raw backend
 
-Bytes in, bytes out — no encoding helpers. Same facade, just talk to `backend`:
+Bytes in, bytes out — no encoding helpers. Same facade, via `backend`:
 
 ```typescript
 const fs = createOPFSDedicated({ root: '/my-app' });
@@ -30,7 +30,7 @@ const fs = createOPFSDedicated({ root: '/my-app' });
 await fs.backend.writeFile('/config.json', new TextEncoder().encode('{}'));
 const bytes = await fs.backend.readFile('/config.json');
 
-// Browser Worker, if you ever need it:
+// Browser Worker:
 fs.worker; // Worker
 
 fs.dispose(); // dispose + terminate
@@ -68,9 +68,9 @@ const fs = new OPFSFacade({
 });
 ```
 
-## Heads-up
+## Notes
 
 - Each call gets its own worker. Tabs don’t share state — use [SharedWorker](./sharedworker.md) for that.
-- Sync access handles are a dedicated-worker-only browser API.
+- Sync access handles only work in a dedicated worker.
 
-More: [file descriptors](../file-descriptors.md), [streaming](./streaming.md), [create helpers](../api/create.md).
+Also: [file descriptors](../file-descriptors.md), [streaming](./streaming.md), [create helpers](../api/create.md).

package/docs/guides/hashing.md

@@ -4,7 +4,7 @@ Set once via `hashAlgorithm` / `maxFileSize` in options or `setOptions()`. Shows
 
 | Value | What you get |
 | ----- | ------------ |
-| `'etag'` (default) | Cheap tag from mtime + size — no content read |
+| `'etag'` (default) | Tag from mtime + size — no content read |
 | `'SHA-1'` … `'SHA-512'` | Real content hash (Web Crypto) |
 | `null` / `false` | No `hash` field |
 
@@ -16,7 +16,7 @@ import { createOPFS } from 'opfs-worker';
 const fs = createOPFS();
 
 await fs.writeFile('/data.txt', 'Hello');
-console.log((await fs.stat('/data.txt')).hash); // etag-ish, e.g. "m1abc-c"
+console.log((await fs.stat('/data.txt')).hash); // e.g. "m1abc-c"
 
 await fs.setOptions({ hashAlgorithm: 'SHA-256' });
 console.log((await fs.stat('/data.txt')).hash); // hex digest

package/docs/guides/pure.md

@@ -1,6 +1,6 @@
 # Pure classes
 
-Use the classes directly inside a worker (or thread) you already own. No nested worker, no Comlink `expose()` from this package — wiring to the main thread is on you.
+Use the classes inside a worker (or thread) you already own. This package does not spawn a nested worker or call Comlink `expose()` — main-thread wiring is yours.
 
 ```typescript
 import { OPFSSync, OPFSAsync } from 'opfs-worker/pure';
@@ -26,7 +26,7 @@ const fs = new OPFSSync({
 await fs.writeFile('/config.json', new TextEncoder().encode('{}'));
 ```
 
-`/pure` won’t hijack your worker’s message port.
+`/pure` does not take over your worker’s message port.
 
 ## OPFSAsync in a SharedWorker you write
 
@@ -41,6 +41,6 @@ onconnect = (e) => {
 };
 ```
 
-Or skip the boilerplate and use the [SharedWorker guide](./sharedworker.md).
+Or use the [SharedWorker guide](./sharedworker.md).
 
 Also: [backend API](../api/backend.md), [dedicated](./dedicated.md), [async](./async.md).

package/docs/guides/sharedworker.md

@@ -1,6 +1,6 @@
 # SharedWorker
 
-One `OPFSAsync` for every tab. Locks live in that single instance, so writes don’t stomp each other across tabs. Watch events go out on `BroadcastChannel` like everywhere else.
+One `OPFSAsync` for every tab. Locks live in that instance, so writes across tabs don’t collide. Watch events use `BroadcastChannel` as usual.
 
 Same limits as [async](./async.md): Safari 26+ for writes, no FDs.
 

package/docs/guides/streaming.md

@@ -1,11 +1,11 @@
 # Streaming
 
-Write big files without holding the whole thing in memory.
+Write large files without buffering the whole payload.
 
-| | Method |
-| --- | --- |
-| Facade | `importStream(path, source, options?)` |
-| Backend / raw | `writeStream(path, stream, onProgress?)` |
+|               | Method                                                                         |
+| ------------- | ------------------------------------------------------------------------------ |
+| Facade        | `importStream(path, source, options?)` · `importFiles(entries, options?)`      |
+| Backend / raw | `writeStream(path, stream, onProgress?)` · `importFiles(entries, onProgress?)` |
 
 Both create or overwrite the file, return bytes written, and fire a watch event when done.
 
@@ -27,7 +27,120 @@ const res = await fetch('/large.bin');
 await fs.importStream('/cache/large.bin', res.body!);
 ```
 
-With a worker backend the facade transfers the stream and proxies `onProgress` — you don’t need Comlink `transfer` yourself.
+With a worker backend the facade transfers the stream and proxies `onProgress`.
+
+## `importFiles` (bulk)
+
+Same streaming path for many entries — strings, bytes, Blobs, or Files.
+
+First argument is any iterable of `[path, data]` pairs: an array of tuples, a `Map`, etc.
+
+`onProgress` receives an object (not a bare number):
+
+| Field                              | Meaning                                   |
+| ---------------------------------- | ----------------------------------------- |
+| `path`                             | File currently being written              |
+| `index` / `count`                  | 0-based index and total number of entries |
+| `bytesWritten` / `bytesTotal`      | Progress within the current file          |
+| `totalBytesWritten` / `totalBytes` | Progress across the whole import          |
+
+```typescript
+await fs.importFiles(
+  [
+    ['/a.txt', 'hello'],
+    ['/upload.bin', fileFromInput],
+  ],
+  {
+    onProgress: ({ path, bytesWritten, bytesTotal, totalBytesWritten, totalBytes }) => {
+      console.log(`${path}: ${bytesWritten}/${bytesTotal} (all ${totalBytesWritten}/${totalBytes})`);
+    },
+  }
+);
+// → { paths: ['/a.txt', '/upload.bin'], count: 2, bytesWritten: … }
+
+// Map works too
+await fs.importFiles(new Map([
+  ['/a.txt', 'hello'],
+  ['/b.txt', 'world'],
+]));
+```
+
+`createIndex` is kept as a deprecated alias.
+
+## Uploading files and folders from disk
+
+Getting `File` objects out of the browser is the DOM's job; once you have them, `importFiles` does the rest.
+
+### File / folder picker
+
+A plain `<input type="file">` gives you files. Add `webkitdirectory` and the picker selects a whole folder — each file then carries its relative path in `webkitRelativePath`:
+
+```html
+<input type="file" id="files" multiple />
+<input type="file" id="folder" webkitdirectory multiple />
+```
+
+```typescript
+input.addEventListener('change', async () => {
+    const entries = [...input.files].map((file) => [
+        `/uploads/${file.webkitRelativePath || file.name}`,
+        file,
+    ] as [string, File]);
+
+    await fs.importFiles(entries, {
+        onProgress: ({ path, totalBytesWritten, totalBytes }) => {
+            console.log(`${path}: ${totalBytesWritten}/${totalBytes}`);
+        },
+    });
+});
+```
+
+### Drag and drop
+
+Dropped folders are only reachable through the non-standard (but universally supported) `webkitGetAsEntry` API, which has to be walked recursively:
+
+```typescript
+async function collect(entry: FileSystemEntry, prefix = ''): Promise<[string, File][]> {
+    if (entry.isFile) {
+        const file = await new Promise<File>((res, rej) => (entry as FileSystemFileEntry).file(res, rej));
+
+        return [[`${prefix}${entry.name}`, file]];
+    }
+
+    const reader = (entry as FileSystemDirectoryEntry).createReader();
+    const children: FileSystemEntry[] = [];
+
+    // readEntries returns partial batches — keep calling until it's empty
+    for (;;) {
+        const batch = await new Promise<FileSystemEntry[]>((res, rej) => reader.readEntries(res, rej));
+
+        if (batch.length === 0) break;
+        children.push(...batch);
+    }
+
+    const nested = await Promise.all(children.map((c) => collect(c, `${prefix}${entry.name}/`)));
+
+    return nested.flat();
+}
+
+dropZone.addEventListener('drop', async (e) => {
+    e.preventDefault();
+
+    const entries = [...e.dataTransfer!.items]
+        .map((item) => item.webkitGetAsEntry())
+        .filter((entry): entry is FileSystemEntry => entry !== null);
+
+    const files = (await Promise.all(entries.map((entry) => collect(entry, '/uploads/')))).flat();
+
+    await fs.importFiles(files, {
+        onProgress: ({ path, index, count, bytesWritten, bytesTotal }) => {
+            console.log(`[${index + 1}/${count}] ${path}: ${bytesWritten}/${bytesTotal}`);
+        },
+    });
+});
+```
+
+The [demo](https://kachurun.github.io/opfs-worker/) implements exactly this flow — see `demo/FileBrowser.tsx`.
 
 ## `writeStream` (raw)
 
@@ -38,13 +151,34 @@ const fs = createOPFS();
 await fs.backend.writeStream('/data.bin', someBlob.stream(), (n) => console.log(n));
 ```
 
+## Reading back without buffering: `readBlob`
+
+`readFile` copies the whole file into a `Uint8Array`, which is wasteful for media. `readBlob` returns the disk-backed `Blob` that OPFS already has, so nothing is read until something asks for bytes:
+
+```typescript
+const blob = await fs.readBlob('/media/clip.mp4');
+
+video.src = URL.createObjectURL(blob);
+```
+
+The browser then seeks and buffers only the ranges it plays — a 2 GB video costs no memory up front. The same `Blob` works for `<img>`, `<audio>`, `<iframe>` (PDF), `fetch()` bodies, and `showSaveFilePicker` downloads.
+
+Reading a small header stays cheap too, since `slice()` does not touch the rest of the file:
+
+```typescript
+const magic = new Uint8Array(await blob.slice(0, 4).arrayBuffer());
+```
+
+When the file system runs in a worker, the `Blob` crosses the boundary by reference — structured clone does not copy its contents.
+
 ## When to use what
 
-| API | Good for |
-| --- | -------- |
-| `writeFile` | Stuff already in memory |
-| `importStream` / `writeStream` | Large `File` / `Blob` / network bodies |
-| `createIndex` | Many small entries (Blobs here are still fully buffered) |
+| API                            | Good for                                                     |
+| ------------------------------ | ------------------------------------------------------------ |
+| `writeFile`                    | Data already in memory                                       |
+| `importStream` / `writeStream` | One large `File` / `Blob` / network body                     |
+| `importFiles`                  | Many files / folder uploads (streamed, with total progress)  |
+| `readBlob`                     | Media previews, downloads, anything you can hand a `Blob` to |
 
 Dedicated path chunks through FDs; async path uses `createWritable()` (Safari 26+ for writes).
 

package/docs/guides/watching.md

@@ -28,8 +28,8 @@ stop(); // or fs.unwatch('/')
 
 `watch` returns an unsubscribe function. Options: [`WatchOptions`](../types.md#watchoptions). Payload: [`WatchEvent`](../types.md#watchevent).
 
-## Gotchas
+## Notes
 
-- Into a worker, pass a **channel name** (string). You can’t post a `BroadcastChannel` instance across the wire. On the main thread the facade accepts either.
+- Pass a **channel name** (string) into a worker — a `BroadcastChannel` instance can’t cross the wire. On the main thread the facade accepts either.
 - SharedWorker: one backend + one channel → every listening tab sees the same events.
-- Whether events include `hash` depends on [hashing](./hashing.md) settings.
+- Whether events include `hash` depends on [hashing](./hashing.md).

package/docs/migration.md

@@ -9,7 +9,7 @@
 | `OPFSWorker`             | `OPFSSync`                                                                           |
 | `opfs-worker/raw`        | `opfs-worker/pure`                                                                   |
 | `opfs-worker/raw?worker` | `createOPFSDedicated()` + `fs.backend` / `fs.worker`, or `dedicated.worker.js`       |
-| `fs.sync(entries)`       | `fs.createIndex(entries)`                                                            |
+| `fs.sync(entries)`       | `fs.importFiles(entries)` (`createIndex` alias kept, deprecated)                     |
 
 ```diff
 - import { createWorker, OPFSFileSystem } from 'opfs-worker';
@@ -29,8 +29,8 @@
 - SharedWorker: `createOPFSShared` / `opfs-worker/sharedworker`
 - Prebuilt scripts: `dedicated.worker.js`, `shared.worker.js`
 - Streaming: `importStream` / `writeStream`
-- Escape hatch on every facade: `fs.backend` / `fs.worker`
-- Clearer names: `createOPFSDedicated`, `createOPFSAsync`, `createOPFSShared`
+- `fs.backend` / `fs.worker` on every facade
+- `createOPFSDedicated`, `createOPFSAsync`, `createOPFSShared`
 
 ## Behaviour
 

package/docs/types.md

@@ -1,38 +1,22 @@
 # Types
 
-TypeScript types shipped with the package.
-
-## Core Types
-
-### `FileStat`
-
-File or directory statistics.
+## `FileStat`
 
 ```typescript
 interface FileStat {
     kind: 'file' | 'directory';
     size: number;
-    mtime: string; // ISO string
-    ctime: string; // ISO string
+    mtime: string; // ISO
+    ctime: string; // ISO
     isFile: boolean;
     isDirectory: boolean;
-    hash?: string; // Hash of file content (only for files)
+    hash?: string; // files only, when hashing is enabled
 }
 ```
 
-**Properties:**
-
-- `kind`: Type of the file system entry
-- `size`: Size in bytes (0 for directories)
-- `mtime`: Last modification time as ISO string
-- `ctime`: Creation time as ISO string
-- `isFile`: True if this is a file
-- `isDirectory`: True if this is a directory
-- `hash`: Optional hash of file content (only present for files when hashing is enabled)
+`size` is `0` for directories.
 
-### `DirentData`
-
-Directory entry information.
+## `DirentData`
 
 ```typescript
 interface DirentData {
@@ -43,46 +27,61 @@ interface DirentData {
 }
 ```
 
-**Properties:**
+## `WatchOptions`
 
-- `name`: Name of the file or directory
-- `kind`: Type of the entry
-- `isFile`: True if this is a file
-- `isDirectory`: True if this is a directory
+```typescript
+interface WatchOptions {
+    recursive?: boolean; // default: true
+    include?: string | string[]; // minimatch, default: ['**']
+    exclude?: string | string[]; // minimatch, default: []
+}
+```
 
-### `WatchOptions`
+## `ImportFilesProgress`
 
-Options for file watching operations.
+Fired by `importFiles` / `onProgress` for each chunk written:
 
 ```typescript
-interface WatchOptions {
-    recursive?: boolean; // Whether to watch recursively (default: true)
-    include?: string | string[]; // Glob patterns to include in watching (minimatch syntax, default: ['**'])
-    exclude?: string | string[]; // Glob patterns to exclude from watching (minimatch syntax, default: [])
+interface ImportFilesProgress {
+    path: string;            // file currently being written
+    index: number;           // 0-based
+    count: number;           // total entries
+    bytesWritten: number;    // within current file
+    bytesTotal: number;      // size of current file
+    totalBytesWritten: number;
+    totalBytes: number;      // sum of all entry sizes
 }
 ```
 
-**Properties:**
+## `ImportFilesResult`
+
+Returned when `importFiles` finishes:
+
+```typescript
+interface ImportFilesResult {
+    paths: string[];      // written paths, in order
+    count: number;        // paths.length
+    bytesWritten: number; // total bytes across all files
+}
+```
 
-- `recursive`: Whether to watch the entire directory tree (default: true)
-- `include`: Glob patterns to include in watching (default: all files)
-- `exclude`: Glob patterns to exclude from watching (default: none)
+Entries accept `Iterable<[path, string | Uint8Array | Blob]>` or `Map<string, …>` — see [streaming](./guides/streaming.md).
 
-### `OPFSApi`
+## `OPFSApi`
 
-Promise-based fs API surface shared by all backends — a Comlink proxy to `OPFSSync` in a worker, or an in-process `OPFSAsync` instance. This is what `OPFSFacade` talks to (see `OPFSBackend` in [Create helpers](./api/create.md)).
+Promise-based surface shared by all backends — a Comlink proxy to `OPFSSync`, or an in-process `OPFSAsync`. What `OPFSFacade` talks to (see `OPFSBackend` in [Create helpers](./api/create.md)).
 
 ```typescript
 type OPFSApi = { [K in keyof OPFSSync]: OPFSSync[K] };
 ```
 
-### `PathLike`
+## `PathLike`
 
 ```typescript
 type PathLike = string | URL;
 ```
 
-### `FileOpenOptions`
+## `FileOpenOptions`
 
 ```typescript
 interface FileOpenOptions {
@@ -92,40 +91,26 @@ interface FileOpenOptions {
 }
 ```
 
-## Configuration Types
-
-### `OPFSOptions`
+## `OPFSOptions`
 
-Configuration for all backends. Human-readable table: [Create helpers → Options](./api/create.md#options).
+Table: [Create helpers → Options](./api/create.md#options).
 
 ```typescript
 interface OPFSOptions {
-    /** Root path for the file system (default: '/') */
+    /** Root path (default: '/') */
     root?: string;
-    /** Namespace for the events (default: 'opfs-worker:${root}') */
+    /** Event namespace (default: 'opfs-worker:${root}') */
     namespace?: string;
-    /** Hash algorithm for file hashing, or false/null to disable (default: 'etag') */
+    /** Hash algorithm, or false/null to disable (default: 'etag') */
     hashAlgorithm?: null | false | 'etag' | 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512';
-    /** Maximum file size in bytes for SHA-* hashing (default: 50MB); ignored by 'etag' */
+    /** Max bytes for SHA-* hashing (default: 50MB); ignored by 'etag' */
     maxFileSize?: number;
-    /** Custom name for the broadcast channel (default: 'opfs-worker') */
+    /** Broadcast channel name or instance (default: 'opfs-worker') */
     broadcastChannel?: string | BroadcastChannel | null;
 }
 ```
 
-**Properties:**
-
-- `root`: Root path for the file system
-- `namespace`: Namespace for events and isolation
-- `hashAlgorithm`: `'etag'` (default, mtime+size), `'SHA-*'`, or `null`/`false` to disable
-- `maxFileSize`: Max bytes for SHA-* content hashing (etag ignores this)
-- `broadcastChannel`: Custom broadcast channel name or instance
-
-## Event Types
-
-### `WatchEventType`
-
-Enumeration of file system change event types.
+## `WatchEventType`
 
 ```typescript
 enum WatchEventType {
@@ -135,15 +120,7 @@ enum WatchEventType {
 }
 ```
 
-**Values:**
-
-- `Added`: File or directory was created
-- `Changed`: File or directory was modified
-- `Removed`: File or directory was deleted
-
-### `WatchEvent`
-
-File system change event sent via BroadcastChannel.
+## `WatchEvent`
 
 ```typescript
 interface WatchEvent {
@@ -156,91 +133,52 @@ interface WatchEvent {
 }
 ```
 
-**Properties:**
-
-- `namespace`: Event namespace for isolation
-- `path`: Path of the changed file/directory
-- `type`: Type of change (added, changed, removed)
-- `isDirectory`: Whether the changed item is a directory
-- `timestamp`: ISO timestamp of the change
-- `hash`: Optional hash of the file content (if hashing is enabled)
-
-## Utility Types
-
-### `Kind`
-
-File system entry type.
+## Utility types
 
 ```typescript
 type Kind = 'file' | 'directory';
-```
-
-### `Encoding`
-
-Supported text encodings.
-
-```typescript
 type Encoding = 'utf-8' | 'utf-16le' | 'ascii' | 'latin1' | 'base64' | 'hex' | 'binary';
 ```
 
-## Error Types
-
-The library provides comprehensive error handling with specific error types that are Node.js SystemError compatible:
-
-### Base Error Class
-
-- `OPFSError` - Base error class for all OPFS-related errors (Node.js SystemError compatible)
-
-**Properties:**
-
-- `errno: number` - Numeric error code (e.g., -2 for ENOENT)
-- `syscall?: string` - System call name (e.g., 'open', 'read', 'write')
-- `path?: string` - File path when applicable
-- `name: string` - Error class name ('OPFSError')
-- `message: string` - Human-readable error message
-- `cause?: any` - Underlying error (Node.js 16+ feature)
-
-### Specialized Error Classes
-
-- `OPFSNotSupportedError` - Thrown when OPFS is not supported in the browser
-- `PathError` - Thrown for invalid paths or path traversal attempts
-- `ExistenceError` - Thrown when files or directories don't exist
-  - Usage: `new ExistenceError('File not found: /path/to/file', 'ENOENT', '/path/to/file')`
-- `PermissionError` - Thrown when permission is denied for an operation
-- `StorageError` - Thrown when an operation fails due to insufficient storage
-- `TimeoutError` - Thrown when an operation times out
-- `FileBusyError` - Thrown when a file is busy (locked by another operation)
-- `FileTypeError` - Thrown when file/directory type expectations don't match
-  - Usage: `new FileTypeError('directory', '/path/to/dir')`
-- `ValidationError` - Thrown for validation failures (invalid arguments, formats, etc.)
-  - Usage: `new ValidationError('Invalid size', 'EINVAL', '/path/to/file')`
-- `OperationAbortedError` - Thrown when an operation is aborted
-- `IOError` - Thrown for I/O operation failures
-- `OperationNotSupportedError` - Thrown when an operation is not supported
-- `DirectoryOperationError` - Thrown when directory operations fail
-  - Usage: `new DirectoryOperationError('RM_FAILED', '/path/to/dir')`
-- `InitializationFailedError` - Thrown when OPFS initialization fails
-- `FileSystemOperationError` - Thrown when file system operations fail
-- `PathResolutionFailedError` - Thrown when path resolution fails
-- `AlreadyExistsError` - Thrown when a file or directory already exists
-
-### Error Code Mapping
-
-The library uses standard POSIX error codes with numeric errno mapping:
-
-- `ENOENT` (-2) - No such file or directory
-- `EISDIR` (-21) - Is a directory
-- `ENOTDIR` (-20) - Not a directory
-- `EACCES` (-13) - Permission denied
-- `EEXIST` (-17) - File exists
-- `ENOTEMPTY` (-39) - Directory not empty
-- `EINVAL` (-22) - Invalid argument
-- `EIO` (-5) - I/O error
-- `ENOSPC` (-28) - No space left on device
-- `EBUSY` (-16) - Device or resource busy
-- `EINTR` (-4) - Interrupted system call
-- `ENOTSUP` (-95) - Operation not supported
-- `ERANGE` (-34) - Result too large
-- `EBADF` (-9) - Bad file descriptor
-
-Each error type extends the base `OPFSError` class and provides specific error codes and context information for better debugging.
+## Errors
+
+Node.js SystemError-compatible. Base class: `OPFSError` (`errno`, `syscall?`, `path?`, `cause?`).
+
+| Class                        |                                                                     |
+| ---------------------------- | ------------------------------------------------------------------- |
+| `OPFSNotSupportedError`      | OPFS missing in the browser                                         |
+| `PathError`                  | Bad path / traversal                                                |
+| `ExistenceError`             | Missing entry — `new ExistenceError(msg, 'ENOENT', path)`           |
+| `PermissionError`            | Access denied                                                       |
+| `StorageError`               | Quota / storage full                                                |
+| `TimeoutError`               | Timed out                                                           |
+| `FileBusyError`              | Locked / busy                                                       |
+| `FileTypeError`              | File vs directory mismatch — `new FileTypeError('directory', path)` |
+| `ValidationError`            | Bad args — `new ValidationError(msg, 'EINVAL', path)`               |
+| `OperationAbortedError`      | Aborted                                                             |
+| `IOError`                    | I/O failure                                                         |
+| `OperationNotSupportedError` | Not supported (e.g. FDs on async)                                   |
+| `DirectoryOperationError`    | Dir op failed — `new DirectoryOperationError('RM_FAILED', path)`    |
+| `InitializationFailedError`  | Init failed                                                         |
+| `FileSystemOperationError`   | Generic FS failure                                                  |
+| `PathResolutionFailedError`  | Path resolve failed                                                 |
+| `AlreadyExistsError`         | Already exists                                                      |
+
+### errno
+
+| Code        | errno |                           |
+| ----------- | ----- | ------------------------- |
+| `ENOENT`    | -2    | No such file or directory |
+| `EISDIR`    | -21   | Is a directory            |
+| `ENOTDIR`   | -20   | Not a directory           |
+| `EACCES`    | -13   | Permission denied         |
+| `EEXIST`    | -17   | File exists               |
+| `ENOTEMPTY` | -39   | Directory not empty       |
+| `EINVAL`    | -22   | Invalid argument          |
+| `EIO`       | -5    | I/O error                 |
+| `ENOSPC`    | -28   | No space left             |
+| `EBUSY`     | -16   | Busy                      |
+| `EINTR`     | -4    | Interrupted               |
+| `ENOTSUP`   | -95   | Not supported             |
+| `ERANGE`    | -34   | Result too large          |
+| `EBADF`     | -9    | Bad file descriptor       |