opfs-worker 1.3.2 → 2.1.0

package/docs/guides/async.md

@@ -0,0 +1,36 @@
+# Async (no worker)
+
+`OPFSAsync` on the current thread — `getFile()` / `createWritable()`, no Comlink, no worker in the bundle.
+
+Same limits apply as SharedWorker (it’s the same backend).
+
+## Facade
+
+```typescript
+import { createOPFSAsync } from 'opfs-worker/async';
+
+const fs = createOPFSAsync({ root: '/my-app' });
+
+await fs.writeFile('/note.txt', 'hello');
+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.
+
+## Raw class
+
+```typescript
+import { OPFSAsync } from 'opfs-worker/async';
+
+const fs = new OPFSAsync({ root: '/my-app' });
+await fs.writeFile('/x.bin', new Uint8Array([1, 2, 3]));
+```
+
+## Limits
+
+- **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.
+
+Streaming still works: [streaming](./streaming.md). For one fs across tabs: [SharedWorker](./sharedworker.md).

package/docs/guides/dedicated.md

@@ -0,0 +1,76 @@
+# Dedicated worker
+
+The default path: `OPFSSync` inside a dedicated Web Worker. You get file descriptors and the fastest write path the browser allows for OPFS.
+
+See also [Choosing a mode](../choosing-a-mode.md).
+
+## Facade
+
+```typescript
+import { createOPFSDedicated } from 'opfs-worker';
+// or from 'opfs-worker/sync'
+
+const fs = createOPFSDedicated({ root: '/my-app' });
+
+await fs.writeFile('/config.json', JSON.stringify({ theme: 'dark' }));
+const config = await fs.readFile('/config.json'); // string — auto-detected
+```
+
+`createOPFS` is the same thing with a shorter name.
+
+The worker is inlined by default, so you don’t need a special bundler worker setup.
+
+## Raw backend
+
+Bytes in, bytes out — no encoding helpers. Same facade, just talk to `backend`:
+
+```typescript
+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:
+fs.worker; // Worker
+
+fs.dispose(); // dispose + terminate
+```
+
+## Loading a real worker file
+
+Pass `url` or `worker` when you can’t use the inline blob (strict CSP, custom hosting):
+
+```typescript
+import workerUrl from 'opfs-worker/dedicated.worker.js?url'; // Vite
+
+const fs = createOPFSDedicated({ root: '/my-app', url: workerUrl });
+```
+
+## DIY prebuilt script
+
+`opfs-worker/dedicated.worker.js` is a self-contained Worker (Comlink + `OPFSSync` already inside):
+
+```typescript
+import { wrap } from 'comlink';
+import { OPFSFacade } from 'opfs-worker';
+import workerUrl from 'opfs-worker/dedicated.worker.js?url';
+
+const worker = new Worker(workerUrl, { type: 'module' });
+const remote = wrap(worker);
+
+const fs = new OPFSFacade({
+    fs: remote,
+    worker,
+    dispose: () => {
+        void remote.dispose();
+        worker.terminate();
+    },
+});
+```
+
+## Heads-up
+
+- 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.
+
+More: [file descriptors](../file-descriptors.md), [streaming](./streaming.md), [create helpers](../api/create.md).

package/docs/guides/hashing.md

@@ -0,0 +1,34 @@
+# Hashing
+
+Set once via `hashAlgorithm` / `maxFileSize` in options or `setOptions()`. Shows up on `stat()`, `index()`, and [watch](./watching.md) events (files only).
+
+| Value | What you get |
+| ----- | ------------ |
+| `'etag'` (default) | Cheap tag from mtime + size — no content read |
+| `'SHA-1'` … `'SHA-512'` | Real content hash (Web Crypto) |
+| `null` / `false` | No `hash` field |
+
+`maxFileSize` (default 50MB) only limits SHA-\* hashing. Oversized files skip the hash.
+
+```typescript
+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"
+
+await fs.setOptions({ hashAlgorithm: 'SHA-256' });
+console.log((await fs.stat('/data.txt')).hash); // hex digest
+```
+
+`root` scopes you under a subdirectory of OPFS. `namespace` is stamped on every watch event:
+
+```typescript
+const fs = createOPFS({
+    root: '/my-app',
+    namespace: 'my-app:fs',
+});
+```
+
+Full options table: [`create` helpers](../api/create.md#options).

package/docs/guides/pure.md

@@ -0,0 +1,46 @@
+# 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.
+
+```typescript
+import { OPFSSync, OPFSAsync } from 'opfs-worker/pure';
+```
+
+| Class | Runs where | FD |
+| ----- | ---------- | -- |
+| `OPFSSync` | Dedicated worker only | yes |
+| `OPFSAsync` | Main thread, dedicated, or SharedWorker | no |
+| `BaseOPFS` | Shared base — usually you don’t instantiate it | — |
+
+## OPFSSync in your dedicated worker
+
+```typescript
+// my-app.worker.ts
+import { OPFSSync } from 'opfs-worker/pure';
+
+const fs = new OPFSSync({
+    root: '/my-app',
+    broadcastChannel: 'my-app-events', // name only — instances can’t cross the wire
+});
+
+await fs.writeFile('/config.json', new TextEncoder().encode('{}'));
+```
+
+`/pure` won’t hijack your worker’s message port.
+
+## OPFSAsync in a SharedWorker you write
+
+```typescript
+import { expose } from 'comlink';
+import { OPFSAsync } from 'opfs-worker/pure';
+
+const fs = new OPFSAsync({ root: '/my-app' });
+
+onconnect = (e) => {
+    expose(fs, e.ports[0]);
+};
+```
+
+Or skip the boilerplate and use the [SharedWorker guide](./sharedworker.md).
+
+Also: [backend API](../api/backend.md), [dedicated](./dedicated.md), [async](./async.md).

package/docs/guides/sharedworker.md

@@ -0,0 +1,57 @@
+# 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.
+
+Same limits as [async](./async.md): Safari 26+ for writes, no FDs.
+
+SharedWorkers are keyed by **script URL**, so we can’t inline the worker. Use the shipped file: `opfs-worker/shared.worker.js`.
+
+## With a bundler (Vite example)
+
+```typescript
+import workerUrl from 'opfs-worker/shared.worker.js?url';
+import { createOPFSShared } from 'opfs-worker/sharedworker';
+
+const fs = createOPFSShared({ root: '/my-app', url: workerUrl });
+
+await fs.writeText('/shared-config.json', '{}');
+```
+
+## Without a bundler
+
+Default URL looks for `./shared.worker.js` next to the package files:
+
+```typescript
+import { createOPFSShared } from 'opfs-worker/sharedworker';
+
+const fs = createOPFSShared({ root: '/my-app' });
+```
+
+Or pass your own instance:
+
+```typescript
+const worker = new SharedWorker(
+    new URL('opfs-worker/shared.worker.js', import.meta.url),
+    { type: 'module', name: 'opfs-worker' }
+);
+const fs = createOPFSShared({ root: '/my-app', worker });
+```
+
+## Raw backend
+
+```typescript
+const fs = createOPFSShared({ root: '/my-app', url: workerUrl });
+
+await fs.backend.writeFile('/a.bin', bytes);
+fs.worker; // SharedWorker
+
+fs.dispose(); // closes this tab’s port only
+```
+
+## Notes
+
+- `dispose()` does **not** kill the worker for other tabs — only your port.
+- `setOptions` hits the shared instance, so keep options consistent across tabs.
+- Same script URL + `name` (default `'opfs-worker'`) → same instance.
+
+Also: [async](./async.md), [watching](./watching.md), [create helpers](../api/create.md).

package/docs/guides/streaming.md

@@ -0,0 +1,51 @@
+# Streaming
+
+Write big files without holding the whole thing in memory.
+
+| | Method |
+| --- | --- |
+| Facade | `importStream(path, source, options?)` |
+| Backend / raw | `writeStream(path, stream, onProgress?)` |
+
+Both create or overwrite the file, return bytes written, and fire a watch event when done.
+
+## `importStream` (facade)
+
+Takes a `ReadableStream<Uint8Array>`, or a `Blob` / `File` (we call `.stream()` for you):
+
+```typescript
+import { createOPFS } from 'opfs-worker';
+
+const fs = createOPFS({ root: '/my-app' });
+
+const file = input.files[0];
+await fs.importStream(`/uploads/${file.name}`, file, {
+    onProgress: (n) => console.log(`wrote ${n} bytes`),
+});
+
+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.
+
+## `writeStream` (raw)
+
+```typescript
+import { createOPFS } from 'opfs-worker';
+
+const fs = createOPFS();
+await fs.backend.writeStream('/data.bin', someBlob.stream(), (n) => console.log(n));
+```
+
+## 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) |
+
+Dedicated path chunks through FDs; async path uses `createWritable()` (Safari 26+ for writes).
+
+Also: [facade](../api/facade.md), [backend](../api/backend.md).

package/docs/guides/watching.md

@@ -0,0 +1,35 @@
+# Watching
+
+Changes go out on a `BroadcastChannel` (default name `opfs-worker`). Nothing is emitted unless you `watch` a path.
+
+```typescript
+import { createOPFS } from 'opfs-worker';
+
+const channel = new BroadcastChannel('opfs-worker');
+channel.onmessage = (e) => console.log(e.data);
+
+const fs = createOPFS({
+    root: '/my-app',
+    namespace: 'my-app:fs',
+    broadcastChannel: channel, // or just the string 'opfs-worker'
+});
+
+const stop = fs.watch('/', {
+    recursive: true,
+    include: ['**/*.json'],
+    exclude: ['tmp/**'],
+});
+
+await fs.writeFile('/config.json', '{}');
+// → { namespace, path, type: 'added' | 'changed' | 'removed', isDirectory, timestamp, hash? }
+
+stop(); // or fs.unwatch('/')
+```
+
+`watch` returns an unsubscribe function. Options: [`WatchOptions`](../types.md#watchoptions). Payload: [`WatchEvent`](../types.md#watchevent).
+
+## Gotchas
+
+- 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.
+- SharedWorker: one backend + one channel → every listening tab sees the same events.
+- Whether events include `hash` depends on [hashing](./hashing.md) settings.

package/docs/migration.md

@@ -0,0 +1,41 @@
+# Migration (1.x → 2.x)
+
+## Renames
+
+| Was                      | Now                                                                                  |
+| ------------------------ | ------------------------------------------------------------------------------------ |
+| `createWorker`           | `createOPFSDedicated` (`createOPFS` alias; deprecated `createWorker` still exported) |
+| `OPFSFileSystem`         | `OPFSFacade` (deprecated alias kept)                                                 |
+| `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)`                                                            |
+
+```diff
+- import { createWorker, OPFSFileSystem } from 'opfs-worker';
+- const fs: OPFSFileSystem = createWorker({ root: '/my-app' });
++ import { createOPFS, OPFSFacade } from 'opfs-worker';
++ const fs: OPFSFacade = createOPFS({ root: '/my-app' });
+```
+
+```diff
+- import { OPFSWorker } from 'opfs-worker/raw';
++ import { OPFSSync } from 'opfs-worker/pure';
+```
+
+## New in 2.x
+
+- Async: `createOPFSAsync` / `opfs-worker/async`
+- 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`
+
+## Behaviour
+
+- Concurrent `readFile` on one path takes the same exclusive lock as writes
+- Multiple FDs on one path share one sync handle, each with its own cursor
+- Dedicated `dispose()` terminates the browser `Worker`
+
+Full entry map: [Choosing a mode](./choosing-a-mode.md).

package/docs/types.md

@@ -0,0 +1,246 @@
+# Types
+
+TypeScript types shipped with the package.
+
+## Core Types
+
+### `FileStat`
+
+File or directory statistics.
+
+```typescript
+interface FileStat {
+    kind: 'file' | 'directory';
+    size: number;
+    mtime: string; // ISO string
+    ctime: string; // ISO string
+    isFile: boolean;
+    isDirectory: boolean;
+    hash?: string; // Hash of file content (only for files)
+}
+```
+
+**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)
+
+### `DirentData`
+
+Directory entry information.
+
+```typescript
+interface DirentData {
+    name: string;
+    kind: 'file' | 'directory';
+    isFile: boolean;
+    isDirectory: boolean;
+}
+```
+
+**Properties:**
+
+- `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
+
+### `WatchOptions`
+
+Options for file watching operations.
+
+```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: [])
+}
+```
+
+**Properties:**
+
+- `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)
+
+### `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)).
+
+```typescript
+type OPFSApi = { [K in keyof OPFSSync]: OPFSSync[K] };
+```
+
+### `PathLike`
+
+```typescript
+type PathLike = string | URL;
+```
+
+### `FileOpenOptions`
+
+```typescript
+interface FileOpenOptions {
+    create?: boolean;
+    exclusive?: boolean;
+    truncate?: boolean;
+}
+```
+
+## Configuration Types
+
+### `OPFSOptions`
+
+Configuration for all backends. Human-readable table: [Create helpers → Options](./api/create.md#options).
+
+```typescript
+interface OPFSOptions {
+    /** Root path for the file system (default: '/') */
+    root?: string;
+    /** Namespace for the events (default: 'opfs-worker:${root}') */
+    namespace?: string;
+    /** Hash algorithm for file hashing, 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' */
+    maxFileSize?: number;
+    /** Custom name for the broadcast channel (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.
+
+```typescript
+enum WatchEventType {
+    Added = 'added',
+    Changed = 'changed',
+    Removed = 'removed'
+}
+```
+
+**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.
+
+```typescript
+interface WatchEvent {
+    namespace: string;
+    path: string;
+    type: WatchEventType;
+    isDirectory: boolean;
+    timestamp: string;
+    hash?: string;
+}
+```
+
+**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.
+
+```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.