opfs-worker 2.0.0 → 2.1.1

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` to keep the dedicated-worker code out of the bundle.
+
+## 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, 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

@@ -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, via `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:
+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();
+    },
+});
+```
+
+## Notes
+
+- Each call gets its own worker. Tabs don’t share state — use [SharedWorker](./sharedworker.md) for that.
+- Sync access handles only work in a dedicated worker.
+
+Also: [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) | 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); // 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 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';
+```
+
+| 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` does not take over 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 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 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.
+
+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,185 @@
+# Streaming
+
+Write large files without buffering the whole payload.
+
+|               | 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.
+
+## `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`.
+
+## `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)
+
+```typescript
+import { createOPFS } from 'opfs-worker';
+
+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`                    | 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).
+
+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).
+
+## Notes
+
+- 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).

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.importFiles(entries)` (`createIndex` alias kept, deprecated)                     |
+
+```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`
+- `fs.backend` / `fs.worker` on every facade
+- `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).