opfs-worker 1.3.2 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # OPFS Worker
 
-[![npm version](https://img.shields.io/npm/v/opfs-worker)](https://www.npmjs.com/package/opfs-worker)
+[npm version](https://www.npmjs.com/package/opfs-worker)
 
 A robust TypeScript library for working with Origin Private File System (OPFS) through Web Workers, providing a Node.js-like file system API for browser environments.
 
@@ -41,7 +41,7 @@ A robust TypeScript library for working with Origin Private File System (OPFS) t
 
 - **Complete API**: `readFile`, `writeFile`, `mkdir`, `remove`, `copy`, `rename`, and more
 - **Binary file support**: Handle images, documents, and any binary data seamlessly
-- **Hash support**: Built-in file hash calculation (SHA-1, SHA-256, SHA-384, SHA-512)
+- **Hash support**: Cheap `etag` by default (`mtime-size`), plus optional content hashes (SHA-1 / SHA-256 / SHA-384 / SHA-512)
 - **File indexing**: Complete file system indexing with metadata and search
 
 ### 🔄 **Advanced Features**
@@ -115,37 +115,43 @@ npm install opfs-worker
 
 **Dependencies:**
 
-- `comlink` - Required for both modes (automatically included with inline mode)
-- A bundler with Web Worker support (Vite, Webpack, Rollup, etc.) - Required for manual worker setup
+- Modes 1 and 2 depend on `comlink` (worker communication is handled for you)
+- Mode 3 does not use Comlink — you run the class inside your own worker
+- Modes 1 and 2 ship an inlined worker, so your bundler does not need a `?worker` setup
 
 ## Quick Start
 
-This library provides two ways to use OPFS with Web Workers:
+OPFS sync I/O only works inside a dedicated Web Worker. The library covers three common setups:
 
-### Inline Worker (Recommended)
+|            | Import                                  | Best when                                                         |
+| ---------- | --------------------------------------- | ----------------------------------------------------------------- |
+| **Mode 1** | `createOPFS()` from `opfs-worker`       | You want a Node-like `fs` API on the main thread                  |
+| **Mode 2** | `createOPFSWorker()` from `opfs-worker` | You want the low-level worker API, but still from the main thread |
+| **Mode 3** | `OPFSWorker` from `opfs-worker/pure`    | Your code already runs inside a worker                            |
 
-The easiest way to get started - just import and use:
+Modes 1 and 2 both pull Comlink. Mode 3 does not.
+
+### Mode 1: Node-like facade (recommended)
+
+The usual path. `createOPFS()` starts an inlined worker and returns a facade with a Node-like API — strings, encodings, auto-detection. Comlink stays under the hood.
+
+> 1.x alias: `createWorker` still works and returns the same facade — prefer `createOPFS`.
 
 ```typescript
-import { createWorker } from 'opfs-worker';
+import { createOPFS } from 'opfs-worker';
 
 async function basicExample() {
-    // Create a file system instance with default root path '/'
-    const fs = await createWorker();
+    const fs = createOPFS();
 
-    // Write a file
     await fs.writeFile('/config.json', JSON.stringify({ theme: 'dark' }));
-
-    // Read the file back
     const config = await fs.readFile('/config.json');
-    console.log(JSON.parse(config));
+    console.log(JSON.parse(config as string));
 }
 
-// Extended example with all options
 async function extendedExample() {
     const broadcastChannel = new BroadcastChannel('my-app-events');
 
-    const fs = await createWorker({
+    const fs = createOPFS({
         root: '/my-app',
         namespace: 'my-app:fs',
         hashAlgorithm: 'SHA-256',
@@ -153,16 +159,13 @@ async function extendedExample() {
         broadcastChannel
     });
 
-    // Handle binary files
-    const imageData = new Uint8Array([58, /* binary data */]);
+    const imageData = new Uint8Array([58 /* binary data */]);
     await fs.writeFile('/image.png', imageData);
     const binaryData = await fs.readFile('/image.png', 'binary');
 
-    // Text files are automatically handled
     await fs.writeFile('/config.txt', 'Hello, World!');
-    const textContent = await fs.readFile('/config.txt'); // Returns string
+    const textContent = await fs.readFile('/config.txt'); // string
 
-    // Use file watching with BroadcastChannel
     await fs.watch('/', {
         recursive: true,
         include: ['*.json'],
@@ -170,97 +173,85 @@ async function extendedExample() {
     });
 
     broadcastChannel.onmessage = (event) => {
-        console.log(`File changed: `, event.data);
+        console.log('File changed:', event.data);
     };
 
-    // Get file statistics with hashing
     const stats = await fs.stat('/image.png');
-
-    console.log(
-      `File size: ${stats.size} bytes`,
-      `Hash: ${stats.hash}`
-    );
+    console.log(`File size: ${stats.size} bytes`, `Hash: ${stats.hash}`);
 }
 ```
 
-> **Note:** File change events are sent via BroadcastChannel. Set the `broadcastChannel` option to customize the channel name, or use the default 'opfs-worker' channel. The watch system only sends events for watched paths, making it efficient and focused.
+> Watch events go over `BroadcastChannel` (default name `opfs-worker`). Pass `broadcastChannel` to customize. Only watched paths emit events.
 
-### Manual Worker Setup
+### Mode 2: Raw worker API from the main thread
 
-For more control over the worker lifecycle, use the worker directly with your bundler:
+Same package entry, same inlined worker but without the facade. You get a Comlink proxy to `OPFSWorker`: bytes in, bytes out. Useful if you want to wrap it yourself or prefer the lower-level API.
 
 ```typescript
-import OPFSWorker from 'opfs-worker/raw?worker';
-import { wrap } from 'comlink';
+import { createOPFSWorker } from 'opfs-worker';
 
-async function basicExample() {
-    // Create and wrap the worker with default root path '/'
-    const worker = wrap(new OPFSWorker());
+const { fs, dispose } = createOPFSWorker({
+    root: '/my-app',
+    namespace: 'my-app:fs',
+    hashAlgorithm: 'SHA-256',
+    maxFileSize: 100 * 1024 * 1024,
+    broadcastChannel: 'my-app-events',
+});
 
-    // Use the file system
-    await worker.writeFile('/config.json', JSON.stringify({ theme: 'dark' }));
-    const config = await worker.readFile('/config.json');
-    console.log(JSON.parse(config));
-}
+await fs.writeFile('/config.json', new TextEncoder().encode(JSON.stringify({ theme: 'dark' })));
+const bytes = await fs.readFile('/config.json');
+console.log(JSON.parse(new TextDecoder().decode(bytes)));
 
-// Extended example with all options
-async function extendedExample() {
-    // Create with all available options
-    const worker = wrap(new OPFSWorker({
-        root: '/my-app',
-        namespace: 'my-app:fs',
-        hashAlgorithm: 'SHA-256',
-        maxFileSize: 100 * 1024 * 1024, // 100MB
-        broadcastChannel: 'my-app-events' // You can't pass a BroadcastChannel instance to the worker, so you must use a broadcast channel name here
-    }));
-
-    // Bulk sync from external data
-    const entries = [
-        ['/data/config.json', JSON.stringify({ version: '1.0' })],
-        ['/data/users.json', JSON.stringify([{ id: 1, name: 'John' }])]
-    ];
-    await worker.sync(entries, { cleanBefore: true });
+dispose(); // worker.dispose() + terminate()
+```
 
-    // Create directories
-    await worker.mkdir('/data/logs', { recursive: true });
+> Want your own facade? Our `OPFSFacade` is built on `createOPFSWorker` — copy [`src/OPFSFacade.ts`](src/OPFSFacade.ts), swap the imports to `opfs-worker` and change what you need.
 
-    // Append to log files (worker works with bytes)
-    const logEntry = new TextEncoder().encode(`${new Date().toISOString()}: App started\n`);
-    await worker.appendFile('/data/logs/app.log', logEntry);
+### Mode 3: `OPFSWorker` inside your own worker
 
-    // Watch for changes
-    await worker.watch('/data', { recursive: true });
+If you already have a worker (or want full control over it), import the class and use it directly. No nested worker, no Comlink. Bundling that worker and talking to the main thread — if you need that at all — is up to you.
 
-    const channel = new BroadcastChannel('my-app-events');
-    channel.onmessage = (event) => {
-        console.log('File changed:', event.data);
-    };
-}
+```typescript
+// my-app.worker.ts  (this file IS the worker)
+import { OPFSWorker } from 'opfs-worker/pure';
+
+const fs = new OPFSWorker({
+    root: '/my-app',
+    namespace: 'my-app:fs',
+    hashAlgorithm: 'SHA-256',
+    broadcastChannel: 'my-app-events', // name only — BroadcastChannel instances can't cross the wire
+});
+
+await fs.writeFile('/config.json', new TextEncoder().encode(JSON.stringify({ theme: 'dark' })));
+const bytes = await fs.readFile('/config.json');
+console.log(JSON.parse(new TextDecoder().decode(bytes)));
 ```
 
-**Note:** Manual worker setup requires a bundler that supports Web Workers (like Vite, Webpack, Rollup, etc.) and the `comlink` package for communication between the main thread and worker.
+`opfs-worker/pure` does not call Comlink `expose()`, so it will not take over your worker's message port.
 
 ### Hash Algorithm Configuration
 
-The file system supports global hash algorithm configuration. Instead of passing hash options to individual methods, you can set the hash algorithm once and it will be used for all file operations that support hashing.
+Set once via options / `setOptions()` — used by `stat()`, `index()`, and watch events.
+
+Default is `'etag'`: a cheap weak tag from `File.lastModified` + size (no content read). Switch to a SHA algorithm when you need a real content hash.
 
 ```typescript
-import { createWorker } from 'opfs-worker';
+import { createOPFS } from 'opfs-worker';
 
 async function hashExample() {
-    const fs = await createWorker();
-
-    // Enable SHA-256 hashing globally
-    fs.setOptions({ hashAlgorithm: 'SHA-256' });
-
-    // Write a file
+    // Default: etag (fast, no content read)
+    const fs = createOPFS();
     await fs.writeFile('/data.txt', 'Hello World');
 
-    // Get stats - hash will be included automatically
-    const stats = await fs.stat('/data.txt');
-    console.log(`Hash: ${stats.hash}`); // SHA-256 hash
+    const etagStat = await fs.stat('/data.txt');
+    console.log(`ETag: ${etagStat.hash}`); // e.g. "m1abc-c"  (mtime36-size36)
+
+    // Opt into a cryptographic content hash
+    await fs.setOptions({ hashAlgorithm: 'SHA-256' });
+    const shaStat = await fs.stat('/data.txt');
+    console.log(`SHA-256: ${shaStat.hash}`);
 
-    // Get file system index - all files will include hashes
+    // Index / watch events also include hash when enabled
     const index = await fs.index();
     for (const [path, stat] of index) {
         if (stat.isFile && stat.hash) {
@@ -268,7 +259,6 @@ async function hashExample() {
         }
     }
 
-    // Watch events will also include hash information
     const channel = new BroadcastChannel('opfs-worker');
     channel.onmessage = (event) => {
         if (event.data.hash) {
@@ -277,52 +267,45 @@ async function hashExample() {
     };
 }
 
-// Configure maximum file size for hashing
+// maxFileSize only applies to SHA-* (content) hashing — etag ignores it
 async function maxFileSizeExample() {
-    const fs = await createWorker();
-
-    // Set custom maximum file size (100MB instead of default 50MB)
-    fs.setOptions({
+    const fs = createOPFS({
         hashAlgorithm: 'SHA-256',
-        maxFileSize: 100 * 1024 * 1024 // 100MB
+        maxFileSize: 100 * 1024 * 1024 // 100MB (default 50MB)
     });
 
-    // Files up to 100MB will be hashed
-    // Files larger than this will not have hash information
     const stats = await fs.stat('/large-file.dat');
     if (stats.hash) {
         console.log(`Hash: ${stats.hash}`);
     } else {
-        console.log('File too large for hashing');
+        console.log('File too large for content hashing');
     }
 }
 ```
 
 **Supported Hash Algorithms:**
 
-- `'SHA-1'` - Fastest, good for general use (default)
-- `'SHA-256'` - More secure, widely supported
-- `'SHA-384'` - Higher security
-- `'SHA-512'` - Highest security
-- `null` - Disable hashing for maximum performance
+- `'etag'` — **default**. Weak tag from mtime + size; free, no content read
+- `'SHA-1'` / `'SHA-256'` / `'SHA-384'` / `'SHA-512'` — content hashes via Web Crypto (bounded by `maxFileSize`)
+- `null` / `false` — disable hashing
 
-**Note:** When hashing is enabled, it affects all file operations including `stat()`, `index()`, and watch events. Set to `null` when you don't need hash information to improve performance.
+**Note:** Prefer `'etag'` for watch / change-detection. Use SHA only when you need integrity of file bytes. Set to `null`/`false` if you don't need `hash` at all.
 
 ### Root Path Configuration
 
 The file system supports configuring the root path through options. The root path determines where in OPFS the file system's root will be created. All file paths passed to the API are relative to this root path.
 
 ```typescript
-import { createWorker } from 'opfs-worker';
+import { createOPFS } from 'opfs-worker';
 
 async function rootPathExample() {
     // Use default root path '/'
-    const fsDefault = await createWorker();
+    const fsDefault = createOPFS();
     await fsDefault.writeFile('/config.json', '{}');
     // This creates /config.json in OPFS root
 
     // Use custom root path
-    const fsCustom = await createWorker({ root: '/my-app' });
+    const fsCustom = createOPFS({ root: '/my-app' });
     await fsCustom.writeFile('/config.json', '{}');
     // This creates /my-app/config.json in OPFS root
 
@@ -360,9 +343,10 @@ The complete API reference is available in the [docs/api-reference.md](docs/api-
 
 **Entry Points:**
 
-- `createWorker(options?)` - Create file system instance with inline worker (recommended)
-- `OPFSFileSystem` - High-level facade with automatic encoding detection
-- `OPFSWorker` - Direct webworker class
+- `createOPFS(options?)` — Mode 1: Node-like facade on the main thread
+- `createOPFSWorker(options?)` — Mode 2: raw `OPFSWorker` proxy on the main thread
+- `OPFSWorker` from `opfs-worker/pure` — Mode 3: use the class inside your own worker
+- `OPFSFacade` — Mode 1 class returned by `createOPFS`
 
 **Core File Operations:**
 
@@ -462,7 +446,6 @@ npm run test:coverage
 
 ```bash
 npm run lint
-npm run lint:fix
 ```
 
 ## License

package/dist/{facade.d.ts → OPFSFacade.d.ts}

@@ -1,11 +1,13 @@
 import type { BinaryEncoding, DirentData, Encoding, FileOpenOptions, FileStat, OPFSOptions, PathLike, RenameOptions, StringEncoding, WatchOptions } from './types';
 /**
- * Facade class that provides a clean interface for communicating with the OPFS worker
- * while hiding Comlink implementation details.
+ * Mode 1: Node-like facade with encoding helpers and string/binary auto-detection,
+ * built on top of the raw worker API from {@link createOPFSWorker}.
+ *
+ * Use {@link createOPFS} to create one.
  */
-export declare class OPFSFileSystem {
+export declare class OPFSFacade {
     #private;
-    promises: OPFSFileSystem;
+    promises: OPFSFacade;
     constructor(options?: OPFSOptions);
     /**
      * Start watching a file or directory for changes
@@ -172,4 +174,19 @@ export declare class OPFSFileSystem {
      */
     dispose(): void;
 }
-//# sourceMappingURL=facade.d.ts.map
+/**
+ * Mode 1: start an inlined worker and get a Node-like `fs` API on top of it.
+ *
+ * For the raw worker API without the facade, use {@link createOPFSWorker}.
+ * To use the worker class inside your own worker, see `opfs-worker/pure`.
+ */
+export declare function createOPFS(options?: OPFSOptions): OPFSFacade;
+/**
+ * @deprecated Use {@link createOPFS}. Kept for 1.x compatibility — still returns the facade.
+ */
+export declare const createWorker: typeof createOPFS;
+/**
+ * @deprecated Use {@link OPFSFacade}.
+ */
+export { OPFSFacade as OPFSFileSystem };
+//# sourceMappingURL=OPFSFacade.d.ts.map

package/dist/OPFSFacade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OPFSFacade.d.ts","sourceRoot":"","sources":["../src/OPFSFacade.ts"],"names":[],"mappings":"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"}

package/dist/{worker.d.ts → OPFSWorker.d.ts}

@@ -8,9 +8,8 @@ import type { DirentData, FileOpenOptions, FileStat, OPFSOptions, RenameOptions,
  *
  * @example
  * ```typescript
- * const fs = new OPFSFileSystem();
- * await fs.init('/my-app');
- * await fs.writeFile('/data/config.json', JSON.stringify({ theme: 'dark' }));
+ * const fs = new OPFSWorker();
+ * await fs.writeFile('/data/config.json', new TextEncoder().encode(JSON.stringify({ theme: 'dark' })));
  * const config = await fs.readFile('/data/config.json');
  * ```
  */
@@ -25,6 +24,8 @@ export declare class OPFSWorker {
     private broadcastChannel;
     /** Configuration options */
     private options;
+    /** Shared sync handles per path (OPFS allows only one handle per file) */
+    private openHandles;
     /** Map of open file descriptors to their metadata */
     private openFiles;
     /** Next available file descriptor number */
@@ -44,7 +45,7 @@ export declare class OPFSWorker {
      */
     private notifyChange;
     /**
-     * Creates a new OPFSFileSystem instance
+     * Creates a new OPFSWorker instance
      *
      * @param options - Optional configuration options
      * @param options.root - Root path for the file system (default: '/')
@@ -65,7 +66,7 @@ export declare class OPFSWorker {
      *
      * @example
      * ```typescript
-     * const fs = new OPFSFileSystem();
+     * const fs = new OPFSWorker();
      *
      * // Use OPFS root (default)
      * await fs.mount();
@@ -471,6 +472,9 @@ export declare class OPFSWorker {
     open(path: string, options?: FileOpenOptions): Promise<number>;
     /**
      * Internal method to open a file (without locking)
+     *
+     * Multiple FDs for the same path share one sync access handle (OPFS limit),
+     * with independent per-FD positions — similar to Node.js.
      * @private
      */
     private _openFile;
@@ -625,4 +629,4 @@ export declare class OPFSWorker {
      */
     createIndex(entries: [string, string | Uint8Array | Blob][]): Promise<void>;
 }
-//# sourceMappingURL=worker.d.ts.map
+//# sourceMappingURL=OPFSWorker.d.ts.map

package/dist/OPFSWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OPFSWorker.d.ts","sourceRoot":"","sources":["../src/OPFSWorker.ts"],"names":[],"mappings":"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"}