opfs-worker 2.1.0 → 2.1.2

package/dist/createOPFSDedicated-pKTRWLdz.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"createOPFSDedicated-pKTRWLdz.cjs","sources":["../src/worker/createDedicatedWorker.ts","../src/facade/createOPFSDedicated.ts"],"sourcesContent":["import { wrap } from 'comlink';\n\nimport WorkerCtor from './dedicated.worker?worker&inline';\n\nimport type { OPFSOptions, OPFSSync } from '../types';\nimport type { Remote } from 'comlink';\n\nconst InlineWorker = WorkerCtor as new (options?: WorkerOptions) => Worker;\n\ntype RemoteOPFSSync = Remote<OPFSSync>;\n\nexport interface DedicatedWorkerOptions extends OPFSOptions {\n    /**\n     * URL of the worker script, e.g. `import url from 'opfs-worker/dedicated.worker.js?url'` (Vite).\n     *\n     * Defaults to the inlined worker (no URL needed). Pass an explicit url when you\n     * prefer the self-contained file (strict CSP without `blob:`, or DIY hosting).\n     */\n    url?: string | URL;\n    /** Bring your own Worker instance (overrides `url`) */\n    worker?: Worker;\n}\n\nexport interface RawWorker {\n    /** Comlink proxy to `OPFSSync` (bytes in / bytes out) */\n    fs: RemoteOPFSSync;\n    /** Underlying browser Worker */\n    worker: Worker;\n    /** Calls worker `dispose()` then `terminate()` */\n    dispose: () => void;\n}\n\n/** A `BroadcastChannel` instance can't cross the wire — send its name instead. */\nfunction applyWorkerOptions(fs: Pick<RemoteOPFSSync, 'setOptions'>, options?: OPFSOptions): void {\n    if (!options) {\n        return;\n    }\n\n    if (options.broadcastChannel instanceof BroadcastChannel) {\n        options.broadcastChannel = options.broadcastChannel.name;\n    }\n\n    void fs.setOptions(options);\n}\n\n/**\n * Internal helper: spawn a dedicated worker and wrap `OPFSSync` with Comlink.\n * Prefer {@link createOPFSDedicated}; access the proxy / Worker via\n * `facade.backend` / `facade.worker`.\n */\nexport function createDedicatedWorker(options: DedicatedWorkerOptions = {}): RawWorker {\n    const { url, worker: providedWorker, ...fsOptions } = options;\n\n    const worker = providedWorker\n      ?? (url ? new Worker(url, { type: 'module' }) : new InlineWorker());\n    const fs = wrap<RemoteOPFSSync>(worker);\n\n    applyWorkerOptions(fs, fsOptions);\n\n    return {\n        fs,\n        worker,\n        dispose() {\n            void (async() => {\n                try {\n                    await fs.dispose();\n                }\n                finally {\n                    worker.terminate();\n                }\n            })();\n        },\n    };\n}\n","import { OPFSFacade } from './OPFSFacade';\nimport { createDedicatedWorker } from '../worker/createDedicatedWorker';\n\nimport type { DedicatedWorkerOptions } from '../worker/createDedicatedWorker';\n\n/**\n * Dedicated mode: start a dedicated worker and get a Node-like `fs` API\n * backed by `OPFSSync`.\n *\n * Prefer importing from `opfs-worker/sync` when you only need the worker backend\n * (avoids pulling `OPFSAsync` into the graph). Importing from `opfs-worker` works too.\n *\n * By default uses an inlined worker. Pass `url` / `worker` to load\n * `opfs-worker/dedicated.worker.js` instead (see {@link DedicatedWorkerOptions}).\n *\n * Need the raw bytes API or the Worker instance? Use `fs.backend` / `fs.worker`.\n * For the workerless async backend, use {@link createOPFSAsync}.\n */\nexport function createOPFSDedicated(options?: DedicatedWorkerOptions): OPFSFacade {\n    const { fs, worker, dispose } = createDedicatedWorker(options);\n\n    return new OPFSFacade({ fs, worker, dispose });\n}\n"],"names":["InlineWorker","WorkerCtor","applyWorkerOptions","fs","options","createDedicatedWorker","url","providedWorker","fsOptions","worker","wrap","createOPFSDedicated","dispose","OPFSFacade"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qdAOA,MAAMA,EAAeC,EA0BrB,SAASC,EAAmBC,EAAwCC,EAA6B,CACxFA,IAIDA,EAAQ,4BAA4B,mBACpCA,EAAQ,iBAAmBA,EAAQ,iBAAiB,MAGnDD,EAAG,WAAWC,CAAO,EAC9B,CAOO,SAASC,EAAsBD,EAAkC,GAAe,CACnF,KAAM,CAAE,IAAAE,EAAK,OAAQC,EAAgB,GAAGC,GAAcJ,EAEhDK,EAASF,IACTD,EAAM,IAAI,OAAOA,EAAK,CAAE,KAAM,QAAA,CAAU,EAAI,IAAIN,GAChDG,EAAKO,EAAAA,KAAqBD,CAAM,EAEtC,OAAAP,EAAmBC,EAAIK,CAAS,EAEzB,CACH,GAAAL,EACA,OAAAM,EACA,SAAU,EACA,SAAW,CACb,GAAI,CACA,MAAMN,EAAG,QAAA,CACb,QAAA,CAEIM,EAAO,UAAA,CACX,CACJ,GAAA,CACJ,CAAA,CAER,CCvDO,SAASE,EAAoBP,EAA8C,CAC9E,KAAM,CAAE,GAAAD,EAAI,OAAAM,EAAQ,QAAAG,CAAA,EAAYP,EAAsBD,CAAO,EAE7D,OAAO,IAAIS,EAAAA,WAAW,CAAE,GAAAV,EAAI,OAAAM,EAAQ,QAAAG,EAAS,CACjD"}

package/docs/api/backend.md

@@ -1,36 +0,0 @@
-# Backend API
-
-Classes from `opfs-worker/pure` (also re-exported from `/sync`, `/async`, `/sharedworker` where it makes sense). Bytes only — no encoding helpers.
-
-```
-BaseOPFS     mkdir, stat, readDir, watch, index, createIndex, …
-  ├─ OPFSSync   sync access handles + FDs + writeStream
-  └─ OPFSAsync  getFile / createWritable + writeStream (no FDs)
-```
-
-`OPFSApi` = the `OPFSSync` method surface — both backends and Comlink proxies satisfy it.
-
-## Shared methods (`BaseOPFS`)
-
-Path ops: `mkdir`, `stat`, `readDir`, `exists`, `clear`, `remove`, `rename`, `copy`, `realpath`, `index`, `createIndex`, `watch`, `unwatch`, `setOptions`, `dispose`.
-
-Subclasses implement:
-
-- `readFile` / `writeFile` / `appendFile`
-- `writeStream(path, stream, onProgress?)`
-
-## `OPFSSync`
-
-Dedicated-worker backend. Adds FD methods (`open` … `fsync`) and streams via chunked FD writes.
-
-→ [File descriptors](../file-descriptors.md), [dedicated guide](../guides/dedicated.md).
-
-## `OPFSAsync`
-
-Promise File System API. Streams via `createWritable()`. FDs always throw `OperationNotSupportedError`. Writes need Safari 26+ (or Chrome / Firefox).
-
-→ [Async guide](../guides/async.md).
-
-## Comlink
-
-Dedicated and SharedWorker facades expose the same backend surface on `fs.backend` (a Comlink proxy). For FD `read`/`write` from the main thread, transfer buffers with Comlink — the facade does that for you.

package/docs/api/create.md

@@ -1,82 +0,0 @@
-# Create helpers
-
-Factories from the package entries. For when to pick which: [Choosing a mode](../choosing-a-mode.md).
-
-## Facade
-
-| Function                        | From                   | Backend                       |
-| ------------------------------- | ---------------------- | ----------------------------- |
-| `createOPFSDedicated(options?)` | `.` or `/sync`         | Dedicated worker + `OPFSSync` |
-| `createOPFSAsync(options?)`     | `.` or `/async`        | In-process `OPFSAsync`        |
-| `createOPFSShared(options?)`    | `.` or `/sharedworker` | SharedWorker + `OPFSAsync`    |
-
-All return [`OPFSFacade`](./facade.md).
-
-```typescript
-import { createOPFSDedicated, createOPFSAsync, createOPFSShared } from 'opfs-worker';
-```
-
-On the main entry only:
-
-- `createOPFS` → `createOPFSDedicated`
-- `createWorker` → same (deprecated)
-- `OPFSFileSystem` → `OPFSFacade` (deprecated)
-
-## Escape hatch
-
-Every facade exposes:
-
-| Field        | Meaning                                                               |
-| ------------ | --------------------------------------------------------------------- |
-| `fs.backend` | Raw [`OPFSApi`](../types.md#opfsapi) — bytes in / bytes out           |
-| `fs.worker`  | `Worker` / `SharedWorker` when one was created; `undefined` for async |
-
-```typescript
-const fs = createOPFSDedicated({ root: '/my-app' });
-await fs.backend.writeFile('/a.bin', bytes);
-fs.worker; // Worker
-```
-
-## Options
-
-Passed to any `createOPFS*` (and to `setOptions()` later). Full type: [`OPFSOptions`](../types.md#opfsoptions).
-
-| Option             | Default                 | What it does                                                                                                                   |
-| ------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `root`             | `'/'`                   | Scope all paths under this OPFS subdirectory                                                                                   |
-| `namespace`        | `'opfs-worker:${root}'` | Stamp on every [watch](../guides/watching.md) event                                                                            |
-| `hashAlgorithm`    | `'etag'`                | File hash on `stat` / `index` / watch — `'etag'`, `'SHA-*'`, or `null`/`false` to disable. See [hashing](../guides/hashing.md) |
-| `maxFileSize`      | `50MB`                  | Skip SHA-\* hashing above this size (`etag` ignores it)                                                                        |
-| `broadcastChannel` | `'opfs-worker'`         | Channel name, a `BroadcastChannel` instance, or `null` to disable                                                              |
-
-### Dedicated worker only
-
-| Option   | Type            | Default        | What it does                                                                       |
-| -------- | --------------- | -------------- | ---------------------------------------------------------------------------------- |
-| `url`    | `string \| URL` | inlined worker | Script URL for `opfs-worker/dedicated.worker.js` (or your own) instead of the blob |
-| `worker` | `Worker`        | —              | Pass an existing `Worker` (overrides `url`)                                        |
-
-### SharedWorker only
-
-| Option   | Type            | Default             | What it does                                                                                          |
-| -------- | --------------- | ------------------- | ----------------------------------------------------------------------------------------------------- |
-| `url`    | `string \| URL` | next to the package | Script URL for `opfs-worker/shared.worker.js` — with Vite: `import url from '…/shared.worker.js?url'` |
-| `worker` | `SharedWorker`  | —                   | Pass an existing `SharedWorker` (overrides `url`)                                                     |
-| `name`   | `string`        | `'opfs-worker'`     | Tabs with the same script URL + name share one instance                                               |
-
-```typescript
-const fs = createOPFS({
-    root: '/my-app',
-    hashAlgorithm: 'SHA-256',
-    maxFileSize: 10 * 1024 * 1024,
-});
-```
-
-## Prebuilt scripts
-
-| Export                            | Hook up with                                             |
-| --------------------------------- | -------------------------------------------------------- |
-| `opfs-worker/dedicated.worker.js` | `new Worker(url, { type: 'module' })` or `{ url }`       |
-| `opfs-worker/shared.worker.js`    | `new SharedWorker(url, { type: 'module' })` or `{ url }` |
-
-Walkthroughs: [dedicated](../guides/dedicated.md), [sharedworker](../guides/sharedworker.md).

package/docs/api/facade.md

@@ -1,52 +0,0 @@
-# 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 })`.
-
-`fs.promises === fs`.
-
-## Escape hatch
-
-| Field | Notes |
-| ----- | ----- |
-| `backend` | Raw [`OPFSApi`](../types.md#opfsapi) — same methods without encoding helpers |
-| `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 |
-
-## 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][]` |
-
-## Watch & lifecycle
-
-| Method | Notes |
-| ------ | ----- |
-| `watch` | Returns `() => void` |
-| `unwatch` | |
-| `setOptions` | [Hashing](../guides/hashing.md) and friends |
-| `dispose` | Tear down the backend |
-
-## Node aliases
-
-`unlink` / `rm` / `rmdir` → `remove`. `readdir` → `readDir`. `lstat` → `stat`. `chmod` is a no-op (no Unix modes in OPFS).
-
-## File descriptors
-
-`open`, `read`, `write`, `close`, `fstat`, `ftruncate`, `fsync` — dedicated / `OPFSSync` only. Async throws `ENOTSUP`.
-
-Full story: [file descriptors](../file-descriptors.md).

package/docs/choosing-a-mode.md

@@ -1,41 +0,0 @@
-# Choosing a mode
-
-Sync access handles only work in a **dedicated** worker. Async writes (`createWritable`) work on the main thread and in SharedWorkers too, but Safari needs **26+** for writing.
-
-## Package entries
-
-| Entry                             | What you get                                                    |
-| --------------------------------- | --------------------------------------------------------------- |
-| `opfs-worker`                     | Everything (plus 1.x aliases)                                   |
-| `opfs-worker/sync`                | Dedicated worker only — `createOPFSDedicated`, `OPFSSync`       |
-| `opfs-worker/async`               | No worker — `createOPFSAsync`, `OPFSAsync`                      |
-| `opfs-worker/sharedworker`        | SharedWorker helpers                                            |
-| `opfs-worker/pure`                | Classes only — you own the thread                               |
-| `opfs-worker/dedicated.worker.js` | Prebuilt dedicated Worker script                                |
-| `opfs-worker/shared.worker.js`    | Prebuilt SharedWorker script                                    |
-
-## Modes
-
-|       | API                                                       | Reach for it 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     |
-
-Need the raw bytes API or the browser Worker? Use `fs.backend` / `fs.worker` on any facade — no separate factory.
-
-If size matters, import from `/sync`, `/async`, or `/sharedworker` instead of the main barrel.
-
-## Trade-offs
-
-|                           | Dedicated (`OPFSSync`)                                                                 | Async (`OPFSAsync`)            |
-| ------------------------- | -------------------------------------------------------------------------------------- | ------------------------------ |
-| File descriptors          | yes                                                                                    | `ENOTSUP`                      |
-| Safari writes             | yes (via the worker)                                                                   | 26+                            |
-| SharedWorker              | no                                                                                     | yes                            |
-| One instance for all tabs | no (unless you build SharedWorker yourself)                                            | Mode 4                         |
-| Bundle                    | ~80 KB inlined worker, or [prebuilt script](./guides/dedicated.md#diy-prebuilt-script) | small via `/async`             |
-| CSP without `blob:`       | pass `url` / prebuilt script                                                           | no worker, or SharedWorker URL |
-
-Aliases on the main entry: `createOPFS` / `createWorker` → `createOPFSDedicated`, `OPFSFileSystem` → `OPFSFacade`. See [Migration](./migration.md).