opfs-worker 2.1.0 → 2.1.1

package/README.md

@@ -1,23 +1,33 @@
 # OPFS Worker
 
-[npm](https://www.npmjs.com/package/opfs-worker)
-[demo](https://kachurun.github.io/opfs-worker/)
+<a href="https://www.npmjs.com/package/opfs-worker" target="_blank" rel="noreferrer"><img src="https://img.shields.io/npm/v/opfs-worker.svg" alt="npm"></a>
+<a href="https://kachurun.github.io/opfs-worker/" target="_blank" rel="noreferrer"><img src="https://img.shields.io/badge/demo-live-brightgreen" alt="demo"></a>
 
 ## What is OPFS?
 
-OPFS ([Origin Private File System](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system)) is a private file store for your origin. No file picker, no permission prompts. It lives under the usual site quota, and clearing site data wipes it.
+OPFS ([Origin Private File System](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system)) is a browser filesystem scoped to your origin. It sits under the usual site quota; clearing site data wipes it. The browser does not show a file picker or ask for access.
 
-This library gives you a real filesystem on top of it — read, write, and watch files with a familiar Node-like API.
+This package puts a Node-like API on top of it.
 
-- **High-level Node-like API.** `readFile`, `writeFile`, `mkdir`, `stat`, `rename`, `copy`, `readDir` — with encodings, auto-detection by extension, and `string | URL` paths. You write `fs` code, not handle plumbing. → [facade API](docs/api/facade.md)
-- **Low-level positional I/O.** `open` / `read` / `write` at an offset, plus `ftruncate` and `fsync` — enough for random-access formats and databases. → [file descriptors](docs/file-descriptors.md)
-- **Sync API by default.** `createOPFS()` runs sync access handles in a dedicated worker: the fastest path OPFS offers, with file descriptors, and it works in every browser that has OPFS — including older Safari. You don't manage `Worker`, Comlink, or handles yourself. → [dedicated](docs/guides/dedicated.md)
-- **Async API for modern browsers / SharedWorkers.** Uses `createWritable()` — runs on the main thread or inside a SharedWorker, no dedicated worker needed. Safari 26+ for writes. → [async](docs/guides/async.md) · [sharedworker](docs/guides/sharedworker.md)
-- **Any way you want to run it.** Inlined dedicated worker, your own worker file, raw classes inside a worker you control, or one SharedWorker for every tab. Same methods in all of them. → [choosing a mode](docs/choosing-a-mode.md)
-- **Memory-friendly for big files.** Streaming support means you can pull in gigabyte-sized files without blowing RAM — `importStream` writes a `ReadableStream`, `Blob`, or `File` chunk by chunk, with optional progress callbacks. → [streaming](docs/guides/streaming.md)
-- **Cross-tab `watch()`.** Changes broadcast over `BroadcastChannel`, so listeners fire in every context that shares the filesystem. → [watching](docs/guides/watching.md)
-- **Built-in file hashing.** `stat()` can carry a cheap etag or a real SHA hash, with a size cap so big files don't get hashed by accident — handy for caching and diffing. → [hashing](docs/guides/hashing.md)
-- **Small and typed.** Full TypeScript types, ESM and CJS, two small runtime deps (`comlink`, `minimatch`) — and the async entry pulls in no worker code at all. → [types](docs/types.md)
+→ **File API** — `readFile`, `writeFile`, `mkdir`, `stat`, `rename`, `copy`, `readDir`; encodings, extension-based detection, `string | URL` paths. [Docs](docs/api/facade.md)
+
+→ **File descriptors** — `open` / `read` / `write` at an offset, plus `ftruncate` and `fsync`. [Docs](docs/file-descriptors.md)
+
+→ **Concurrent access** — operations on the same path are serialized, so parallel reads and writes do not fail because another sync access handle is open.
+
+→ **Dedicated worker (default)** — `createOPFS()` sets up the worker for you. Fastest path, supports FDs, writes work in older Safari too. [Docs](docs/guides/dedicated.md)
+
+→ **Async** — same API on the main thread, no worker. No FDs. Writes need Safari 26+ (Safari 18 and older can only read). [Docs](docs/guides/async.md)
+
+→ **SharedWorker** — one instance shared across tabs. Same limits as async (no FDs, Safari 26+ for writes). [Docs](docs/guides/sharedworker.md)
+
+→ **Bring your own worker** — use it directly in a worker you already run, or load a prebuilt worker script. [Docs](docs/choosing-a-mode.md)
+
+→ **Large files & uploads** — stream a `ReadableStream`, `Blob`, or `File` in chunks with progress, or bulk-import whole folders from a file picker / drag-and-drop via `importFiles`. [Docs](docs/guides/streaming.md)
+
+→ **Watch** — change events over `BroadcastChannel` across tabs / workers. [Docs](docs/guides/watching.md)
+
+→ **Hashing** — `stat()` can include an etag or a SHA hash (SHA skipped above a size cap). [Docs](docs/guides/hashing.md)
 
 ## Installation
 
@@ -30,6 +40,7 @@ npm install opfs-worker
 ```typescript
 import { createOPFS } from 'opfs-worker';
 
+// Starts a dedicated worker and returns a Node-like fs API
 const fs = createOPFS({
   root: '/my-app',
   hashAlgorithm: 'SHA-256'
@@ -41,6 +52,9 @@ await fs.rename('/project/hello.txt', '/project/readme.txt');
 
 const files = await fs.readDir('/project');
 const text = await fs.readFile('/project/readme.txt'); // 'Hello, OPFS!'
+
+// Tear down watches, close the backend, and terminate the worker
+fs.dispose();
 ```
 
 ## Choose a mode
@@ -56,8 +70,13 @@ Trade-offs (FDs, Safari, size, CSP): [Choosing a mode](docs/choosing-a-mode.md).
 
 ## Docs
 
-- [Docs index](docs/README.md)
 - [Choosing a mode](docs/choosing-a-mode.md)
+- API
+  - [Create helpers & options](docs/api/create.md)
+  - [Facade](docs/api/facade.md)
+  - [Backend](docs/api/backend.md)
+  - [File descriptors](docs/file-descriptors.md)
+  - [Types](docs/types.md)
 - Guides
   - [Dedicated worker](docs/guides/dedicated.md)
   - [Async](docs/guides/async.md)
@@ -66,31 +85,25 @@ Trade-offs (FDs, Safari, size, CSP): [Choosing a mode](docs/choosing-a-mode.md).
   - [Streaming](docs/guides/streaming.md)
   - [Watching](docs/guides/watching.md)
   - [Hashing](docs/guides/hashing.md)
-- API
-  - [Create helpers & options](docs/api/create.md)
-  - [Facade](docs/api/facade.md)
-  - [Backend](docs/api/backend.md)
-  - [File descriptors](docs/file-descriptors.md)
-  - [Types](docs/types.md)
 - [Migration from 1.x](docs/migration.md)
 
 ## Development
 
 ```bash
-bun install
-bun run build
-bun run test
-bun run lint
-bun run type-check
+npm install
+npm run build
+npm run test
+npm run lint
+npm run type-check
 ```
 
-Demo app: `bun run dev:demo` / `bun run build:demo` / `bun run preview`.
+Demo: `npm run dev:demo` / `npm run build:demo` / `npm run preview`.
 
 ## License
 
 MIT
 
-## 👤 Maintainer
+## Maintainer
 
 <img src="https://github.com/kachurun.png" width="100" height="100" alt="@kachurun's avatar">