opfs-worker 2.0.0 → 2.1.0

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

@@ -1,6 +1,6 @@
 # Types
 
-This document contains all TypeScript types and interfaces provided by OPFS Worker.
+TypeScript types shipped with the package.
 
 ## Core Types
 
@@ -68,21 +68,35 @@ interface WatchOptions {
 - `include`: Glob patterns to include in watching (default: all files)
 - `exclude`: Glob patterns to exclude from watching (default: none)
 
-### `RemoteOPFSWorker`
+### `OPFSApi`
 
-Remote file system interface type for Comlink communication.
+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 RemoteOPFSWorker = Remote<OPFSWorker>;
+type OPFSApi = { [K in keyof OPFSSync]: OPFSSync[K] };
 ```
 
-This type represents the remote interface when using the worker with Comlink.
+### `PathLike`
+
+```typescript
+type PathLike = string | URL;
+```
+
+### `FileOpenOptions`
+
+```typescript
+interface FileOpenOptions {
+    create?: boolean;
+    exclusive?: boolean;
+    truncate?: boolean;
+}
+```
 
 ## Configuration Types
 
 ### `OPFSOptions`
 
-Configuration options for creating an OPFS Worker instance.
+Configuration for all backends. Human-readable table: [Create helpers → Options](./api/create.md#options).
 
 ```typescript
 interface OPFSOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "opfs-worker",
-    "version": "2.0.0",
+    "version": "2.1.0",
     "description": "A robust TypeScript library for working with Origin Private File System (OPFS) through Web Workers",
     "type": "module",
     "main": "dist/index.js",
@@ -18,7 +18,27 @@
             "source": "./src/index.pure.ts",
             "import": "./dist/index.pure.js",
             "require": "./dist/index.pure.cjs"
-        }
+        },
+        "./sync": {
+            "types": "./dist/index.sync.d.ts",
+            "source": "./src/index.sync.ts",
+            "import": "./dist/index.sync.js",
+            "require": "./dist/index.sync.cjs"
+        },
+        "./async": {
+            "types": "./dist/index.async.d.ts",
+            "source": "./src/index.async.ts",
+            "import": "./dist/index.async.js",
+            "require": "./dist/index.async.cjs"
+        },
+        "./sharedworker": {
+            "types": "./dist/index.sharedworker.d.ts",
+            "source": "./src/index.sharedworker.ts",
+            "import": "./dist/index.sharedworker.js",
+            "require": "./dist/index.sharedworker.cjs"
+        },
+        "./dedicated.worker.js": "./dist/dedicated.worker.js",
+        "./shared.worker.js": "./dist/shared.worker.js"
     },
     "sideEffects": false,
     "files": [
@@ -29,9 +49,15 @@
         "LICENSE"
     ],
     "scripts": {
-        "build": "vite build && tsc -p tsconfig.build.json",
+        "build": "bun run build:lib && bun run build:workers && bun run build:types",
+        "build:lib": "vite build",
+        "build:workers": "bun run build:worker:dedicated && bun run build:worker:shared",
+        "build:worker:dedicated": "OPFS_WORKER=dedicated.worker vite build -c vite.worker.config.ts",
+        "build:worker:shared": "OPFS_WORKER=shared.worker vite build -c vite.worker.config.ts",
+        "build:types": "tsc -p tsconfig.build.json",
         "build:demo": "vite build demo --base=./",
         "dev": "concurrently \"vite build --watch --mode development\" \"tsc -p tsconfig.build.json --watch\"",
+        "dev:demo": "vite demo",
         "preview": "vite preview demo",
         "type-check": "tsc --noEmit",
         "lint": "eslint src --ext .ts,.tsx --fix --max-warnings=9999 --quiet",
@@ -63,18 +89,31 @@
     "homepage": "https://github.com/kachurun/opfs-worker#readme",
     "devDependencies": {
         "@changesets/cli": "^2.29.5",
+        "@codemirror/lang-css": "6.3.1",
+        "@codemirror/lang-html": "6.4.11",
+        "@codemirror/lang-javascript": "6.2.5",
+        "@codemirror/lang-json": "6.0.2",
+        "@codemirror/lang-markdown": "6.5.1",
+        "@codemirror/lang-xml": "6.1.0",
+        "@codemirror/theme-one-dark": "6.1.3",
         "@flexbe/eslint-config": "^1.0.11",
+        "@tailwindcss/vite": "4.3.3",
         "@types/minimatch": "^6.0.0",
         "@types/node": "^24.2.0",
         "@types/react": "^19.1.9",
         "@types/react-dom": "^19.1.7",
         "@typescript-eslint/eslint-plugin": "^8.39.0",
         "@typescript-eslint/parser": "^8.39.0",
+        "@uiw/react-codemirror": "4.25.11",
         "@vitest/coverage-v8": "^3.2.4",
+        "daisyui": "5.7.4",
         "eslint": "^9.32.0",
         "happy-dom": "^18.0.1",
+        "lucide-react": "1.26.0",
         "react": "^19.1.1",
         "react-dom": "^19.1.1",
+        "react-icons": "5.7.0",
+        "tailwindcss": "4.3.3",
         "typescript": "^5.9.2",
         "vite": "^7.0.6",
         "vitest": "^3.2.4"