opfs-worker 2.1.0 → 2.1.1

package/dist/types.d.ts

@@ -56,6 +56,39 @@ export interface OPFSOptions {
     /** Custom name for the broadcast channel (default: 'opfs-worker') */
     broadcastChannel?: string | BroadcastChannel | null;
 }
+/** Payload accepted by {@link importFiles} for a single entry. */
+export type ImportFileData = string | Uint8Array | Blob;
+/**
+ * Entries for {@link importFiles}: an array of `[path, data]` tuples, a `Map`,
+ * or any iterable that yields the same pairs.
+ */
+export type ImportFilesEntries = Iterable<[string, ImportFileData]> | Map<string, ImportFileData>;
+/** Progress event fired while {@link importFiles} writes entries. */
+export interface ImportFilesProgress {
+    /** Path of the file currently being written */
+    path: string;
+    /** 0-based index of the current file */
+    index: number;
+    /** Total number of entries in this import */
+    count: number;
+    /** Bytes written for the current file so far */
+    bytesWritten: number;
+    /** Size of the current file in bytes */
+    bytesTotal: number;
+    /** Bytes written across all files so far */
+    totalBytesWritten: number;
+    /** Sum of all entry sizes in bytes */
+    totalBytes: number;
+}
+/** Result of a finished {@link importFiles} call. */
+export interface ImportFilesResult {
+    /** Paths written, in import order */
+    paths: string[];
+    /** Number of files imported (`paths.length`) */
+    count: number;
+    /** Total bytes written across all files */
+    bytesWritten: number;
+}
 export interface RenameOptions {
     /** Whether to overwrite existing files (default: false) */
     overwrite?: boolean;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,GAAG,CAAC;AAEpC,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,WAAW,CAAC;AAExC,MAAM,MAAM,cAAc,GAAG,OAAO,GAChC,MAAM,GACN,OAAO,GACP,SAAS,GACT,UAAU,GACV,MAAM,GACN,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,KAAK,CAAC;AAEV,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEtC,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,cAAc,CAAC;AAEvD,MAAM,WAAW,QAAQ;IACrB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACxB;AAED,oBAAY,cAAc;IACtB,KAAK,UAAU;IACf,OAAO,YAAY;IACnB,OAAO,YAAY;CACtB;AAED,MAAM,WAAW,UAAU;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,YAAY,EAAE,QAAQ,EAAE,CAAC;AAEzB;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG;KAAG,CAAC,IAAI,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC;CAAE,CAAC;AAE7D,MAAM,WAAW,WAAW;IACxB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,aAAa,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACpF,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;CACvD;AAED,MAAM,WAAW,aAAa;IAC1B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IACzB,mDAAmD;IACnD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/docs/api/backend.md

@@ -1,9 +1,9 @@
 # Backend API
 
-Classes from `opfs-worker/pure` (also re-exported from `/sync`, `/async`, `/sharedworker` where it makes sense). Bytes only — no encoding helpers.
+Classes from `opfs-worker/pure` (also re-exported from `/sync`, `/async`, `/sharedworker`). Bytes only — no encoding helpers.
 
 ```
-BaseOPFS     mkdir, stat, readDir, watch, index, createIndex, …
+BaseOPFS     mkdir, stat, readDir, watch, index, importFiles, …
   ├─ OPFSSync   sync access handles + FDs + writeStream
   └─ OPFSAsync  getFile / createWritable + writeStream (no FDs)
 ```
@@ -12,7 +12,7 @@ BaseOPFS     mkdir, stat, readDir, watch, index, createIndex, …
 
 ## Shared methods (`BaseOPFS`)
 
-Path ops: `mkdir`, `stat`, `readDir`, `exists`, `clear`, `remove`, `rename`, `copy`, `realpath`, `index`, `createIndex`, `watch`, `unwatch`, `setOptions`, `dispose`.
+Path ops: `mkdir`, `stat`, `readDir`, `exists`, `clear`, `remove`, `rename`, `copy`, `realpath`, `index`, `readBlob`, `importFiles`, `watch`, `unwatch`, `setOptions`, `dispose`.
 
 Subclasses implement:
 

package/docs/api/create.md

@@ -22,7 +22,7 @@ On the main entry only:
 - `createWorker` → same (deprecated)
 - `OPFSFileSystem` → `OPFSFacade` (deprecated)
 
-## Escape hatch
+## Backend access
 
 Every facade exposes:
 

package/docs/api/facade.md

@@ -1,45 +1,46 @@
 # OPFSFacade
 
-Node-ish API: encodings, auto-detect by extension, path as `string` or `URL`. You normally get one from [`createOPFS*`](./create.md); you can also `new OPFSFacade({ fs, worker?, dispose })`.
+Node-like API: encodings, auto-detect by extension, path as `string` or `URL`. Usually from [`createOPFS*`](./create.md); or `new OPFSFacade({ fs, worker?, dispose })`.
 
 `fs.promises === fs`.
 
-## Escape hatch
+## Backend access
 
-| Field | Notes |
-| ----- | ----- |
+| Field     | Notes                                                                        |
+| --------- | ---------------------------------------------------------------------------- |
 | `backend` | Raw [`OPFSApi`](../types.md#opfsapi) — same methods without encoding helpers |
-| `worker` | `Worker` / `SharedWorker` if this facade owns one; `undefined` for async |
+| `worker`  | `Worker` / `SharedWorker` if this facade owns one; `undefined` for async     |
 
 ## File I/O
 
-| Method | Notes |
-| ------ | ----- |
-| `readFile` / `writeFile` / `appendFile` | Encoding as string, `{ encoding }`, or auto |
-| `importStream` | Stream / Blob / File — [streaming](../guides/streaming.md) |
-| `readText` / `writeText` / `appendText` | UTF-8 by default |
+| Method                                  | Notes                                                                                         |
+| --------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `readFile` / `writeFile` / `appendFile` | Encoding as string, `{ encoding }`, or auto                                                   |
+| `readBlob`                              | Disk-backed `Blob`, nothing copied into memory — [streaming](../guides/streaming.md)          |
+| `importStream`                          | Stream / Blob / File — [streaming](../guides/streaming.md)                                    |
+| `importFiles`                           | Bulk array / `Map` of `[path, data]` with rich progress — [streaming](../guides/streaming.md) |
+| `readText` / `writeText` / `appendText` | UTF-8 by default                                                                              |
 
 ## Directories & metadata
 
-| Method | Notes |
-| ------ | ----- |
-| `mkdir` | `{ recursive }`; numeric mode is accepted and ignored |
-| `readDir` | `DirentData[]` |
-| `stat` / `exists` / `realpath` | |
-| `remove` | `{ recursive, force }` |
-| `rename` / `copy` | `copy` takes `{ recursive, overwrite }` |
-| `clear` | Empty a dir (default `/`) |
-| `index` | `Map<path, FileStat>` |
-| `createIndex` | Bulk `[path, string \| Uint8Array \| Blob][]` |
+| Method                         | Notes                                                 |
+| ------------------------------ | ----------------------------------------------------- |
+| `mkdir`                        | `{ recursive }`; numeric mode is accepted and ignored |
+| `readDir`                      | `DirentData[]`                                        |
+| `stat` / `exists` / `realpath` |                                                       |
+| `remove`                       | `{ recursive, force }`                                |
+| `rename` / `copy`              | `copy` takes `{ recursive, overwrite }`               |
+| `clear`                        | Empty a dir (default `/`)                             |
+| `index`                        | `Map<path, FileStat>`                                 |
 
 ## Watch & lifecycle
 
-| Method | Notes |
-| ------ | ----- |
-| `watch` | Returns `() => void` |
-| `unwatch` | |
-| `setOptions` | [Hashing](../guides/hashing.md) and friends |
-| `dispose` | Tear down the backend |
+| Method       | Notes                               |
+| ------------ | ----------------------------------- |
+| `watch`      | Returns `() => void`                |
+| `unwatch`    |                                     |
+| `setOptions` | See [hashing](../guides/hashing.md) |
+| `dispose`    | Dispose the backend                 |
 
 ## Node aliases
 
@@ -49,4 +50,4 @@ Node-ish API: encodings, auto-detect by extension, path as `string` or `URL`. Yo
 
 `open`, `read`, `write`, `close`, `fstat`, `ftruncate`, `fsync` — dedicated / `OPFSSync` only. Async throws `ENOTSUP`.
 
-Full story: [file descriptors](../file-descriptors.md).
+Details: [file descriptors](../file-descriptors.md).

package/docs/choosing-a-mode.md

@@ -16,14 +16,14 @@ Sync access handles only work in a **dedicated** worker. Async writes (`createWr
 
 ## Modes
 
-|       | API                                                       | Reach for it when…              | FD        | Comlink |
+|       | API                                                       | When                            | FD        | Comlink |
 | ----- | --------------------------------------------------------- | ------------------------------- | --------- | ------- |
-| **1** | [`createOPFSDedicated()`](./guides/dedicated.md)          | You want a normal `fs`-like API | yes       | yes     |
-| **2** | [`OPFSSync` / `OPFSAsync` from `/pure`](./guides/pure.md) | You’re already in a worker      | sync only | no      |
-| **3** | [`createOPFSAsync()`](./guides/async.md)                  | You don’t want a worker at all  | no        | no      |
-| **4** | [`createOPFSShared()`](./guides/sharedworker.md)          | All tabs should share one fs    | no        | yes     |
+| **1** | [`createOPFSDedicated()`](./guides/dedicated.md)          | Normal `fs`-like API            | yes       | yes     |
+| **2** | [`OPFSSync` / `OPFSAsync` from `/pure`](./guides/pure.md) | Already in a worker             | sync only | no      |
+| **3** | [`createOPFSAsync()`](./guides/async.md)                  | No worker                       | no        | no      |
+| **4** | [`createOPFSShared()`](./guides/sharedworker.md)          | One fs shared by all tabs       | no        | yes     |
 
-Need the raw bytes API or the browser Worker? Use `fs.backend` / `fs.worker` on any facade — no separate factory.
+For the raw bytes API or the browser Worker, use `fs.backend` / `fs.worker` on any facade.
 
 If size matters, import from `/sync`, `/async`, or `/sharedworker` instead of the main barrel.