opfs-worker 2.1.0 → 2.1.2

package/docs/guides/dedicated.md

@@ -2,7 +2,7 @@
 
 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).
+See also [API](../api/README.md).
 
 ## Facade
 
@@ -16,13 +16,13 @@ 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.
+`createOPFS` is the same thing with a shorter name (also from `opfs-worker/sync`).
 
 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`:
+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,11 @@ 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.
+- Same `root` (and same `url`) on one page reuses one Worker; different roots get different Workers. `dispose()` drops your port and terminates the Worker only when the last facade for that pool entry is gone.
+- Tabs don’t share a dedicated Worker — use [SharedWorker](./sharedworker.md) for that.
+- Sync access handles only work in a dedicated worker.
+- `setOptions` hits the shared instance for a pooled root — keep options consistent.
 
-More: [file descriptors](../file-descriptors.md), [streaming](./streaming.md), [create helpers](../api/create.md).
+Also: [file descriptors](../api/file-descriptors.md), [streaming](./streaming.md), [API](../api/README.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
@@ -31,4 +31,4 @@ const fs = createOPFS({
 });
 ```
 
-Full options table: [`create` helpers](../api/create.md#options).
+Full options table: [API → Options](../api/README.md#options).

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).
+Also: [dedicated](./dedicated.md), [async](./async.md), [API](../api/README.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.
 
@@ -54,4 +54,4 @@ fs.dispose(); // closes this tab’s port only
 - `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).
+Also: [async](./async.md), [watching](./watching.md), [API](../api/README.md).

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/components/FileBrowser/`.
 
 ## `writeStream` (raw)
 
@@ -38,14 +151,35 @@ 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).
 
-Also: [facade](../api/facade.md), [backend](../api/backend.md).
+Also: [facade](../api/README.md#facade).

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

@@ -2,14 +2,13 @@
 
 ## 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)`                                                            |
+| Was                       | Now                                                  |
+| ------------------------- | ---------------------------------------------------- |
+| `createWorker`            | `createOPFS` (deprecated alias kept)                 |
+| `OPFSFileSystem`          | `OPFSFacade` (deprecated alias kept)                 |
+| `OPFSWorker`              | `OPFSSync`                                           |
+| `opfs-worker/raw`         | `opfs-worker/pure`                                   |
+| `fs.createIndex(entries)` | `fs.importFiles(entries)` (`createIndex` alias kept) |
 
 ```diff
 - import { createWorker, OPFSFileSystem } from 'opfs-worker';
@@ -29,8 +28,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
 
@@ -38,4 +37,4 @@
 - 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).
+Full entry map: [API](./api/README.md).