opfs-worker 0.2.5 → 0.3.0

package/README.md

@@ -29,6 +29,7 @@ A robust TypeScript library for working with Origin Private File System (OPFS) t
 - 📊 **File indexing**: Complete file system indexing with metadata
 - 🔄 **Sync operations**: Bulk file synchronization from external data
 - 👀 **File watching**: Polling-based change detection for files and directories
+- 📡 **Event broadcasting**: Broadcast file system changes to other contexts (tabs, workers, etc.)
 - 🛡️ **Error handling**: Comprehensive error types and handling
 
 ## Installation
@@ -114,7 +115,10 @@ async function example() {
 async function exampleWithWatch() {
     const worker = wrap(new OPFSWorker(
         (event) => console.log('File changed:', event),
-        { watchInterval: 500 }
+        { 
+            watchInterval: 500,
+            hashAlgorithm: 'SHA-1'
+        }
     ));
 
     await worker.mount('/my-app');
@@ -122,7 +126,7 @@ async function exampleWithWatch() {
 }
 ```
 
-**Note:** Manual worker setup requires a bundler that supports Web Workers (like Vite, Webpack, or Rollup) and the `comlink` package for communication between the main thread and worker.
+**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.
 
 **Watch Callbacks:** File watching with callbacks is available with both `createWorker()` and raw worker usage. The `createWorker()` function uses Comlink.proxy to handle function serialization across worker boundaries.
 
@@ -152,11 +156,12 @@ async function advancedExample() {
     await fs.appendFile('/data/logs/app.log', `${new Date().toISOString()}: User logged in\n`);
 
     // Get file statistics with hash
-    const stats = await fs.stat('/data/config.json', {
-        includeHash: true,
-        hashAlgorithm: 'SHA-1'
-    });
-    console.log(`File size: ${stats.size} bytes, Hash: ${stats.hash}`);
+    const stats = await fs.stat('/data/config.json');
+    
+    console.log(`File size: ${stats.size} bytes`);
+    if (stats.hash) {
+        console.log(`Hash: ${stats.hash}`);
+    }
 
     // List directory contents
     const files = await fs.readdir('/data', { withFileTypes: true });
@@ -168,6 +173,73 @@ async function advancedExample() {
 }
 ```
 
+### Hash Algorithm Configuration
+
+The file system now 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.
+
+```typescript
+import { createWorker } from 'opfs-worker';
+
+async function hashExample() {
+    const fs = await createWorker();
+    
+    // Enable SHA-256 hashing globally
+    fs.setOptions({ hashAlgorithm: 'SHA-256' });
+    
+    // Write a file
+    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
+    
+    // Get file system index - all files will include hashes
+    const index = await fs.index();
+    for (const [path, stat] of index) {
+        if (stat.isFile && stat.hash) {
+            console.log(`${path}: ${stat.hash}`);
+        }
+    }
+    
+    // Watch events will also include hash information
+    const channel = new BroadcastChannel('opfs-worker');
+    channel.onmessage = (event) => {
+        if (event.data.hash) {
+            console.log(`File ${event.data.path} changed, hash: ${event.data.hash}`);
+        }
+    };
+}
+
+// Configure maximum file size for hashing
+async function maxFileSizeExample() {
+    const fs = await createWorker();
+    
+    // Set custom maximum file size (100MB instead of default 50MB)
+    fs.setOptions({ 
+        hashAlgorithm: 'SHA-256',
+        maxFileSize: 100 * 1024 * 1024 // 100MB
+    });
+    
+    // Now 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');
+    }
+}
+```
+
+**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
+
+**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.
+
 ## Demo
 
 Check out the live demo powered by Vite and hosted on GitHub Pages.
@@ -176,43 +248,120 @@ Check out the live demo powered by Vite and hosted on GitHub Pages.
 
 ## API Reference
 
-- [Entry Points](#entry-points)
-  - [`createWorker()`](#createworker)
-- [Core Methods](#core-methods)
-  - [Mount](#mountroot-string-watch-event-watch-event--void-options--watchinterval-number--promiseboolean)
-  - [Read File](#readfilepath-string-encoding-bufferencoding--binary-promisestring--uint8array)
-  - [Write File](#writefilepath-string-data-string--uint8array--arraybuffer-encoding-bufferencoding-promisevoid)
-  - [Append File](#appendfilepath-string-data-string--uint8array--arraybuffer-encoding-bufferencoding-promisevoid)
-  - [Make Directory](#mkdirpath-string-options--recursive-boolean--promisevoid)
-  - [Read Directory](#readdirpath-string-options--withfiletypes-boolean--promisestring--direntdata)
-  - [File Stat](#statpath-string-options--includehash-boolean-hashalgorithm-string--promisefilestat)
-  - [Exists](#existspath-string-promiseboolean)
-  - [Remove](#removepath-string-options--recursive-boolean-force-boolean--promisevoid)
-  - [Copy](#copysource-string-destination-string-options--recursive-boolean-force-boolean--promisevoid)
-  - [Rename](#renameoldpath-string-newpath-string-promisevoid)
-  - [Clear](#clearpath-string-promisevoid)
-  - [Index](#indexoptions--includehash-boolean-hashalgorithm-string--promisemapstring-filestat)
-  - [Sync](#syncentries-string-string--uint8array--blob-options--cleanbefore-boolean--promisevoid)
-  - [Watch](#watchpath-string-promisevoid)
-  - [Unwatch](#unwatchpath-string-void)
-  - [Real Path](#realpathpath-string-promisestring)
-- [Binary File Handling](#binary-file-handling)
-- [Utility Functions](#utility-functions)
+- [OPFS Worker](#opfs-worker)
+  - [Table of Contents](#table-of-contents)
+  - [Features](#features)
+  - [Installation](#installation)
+  - [Quick Start](#quick-start)
+    - [Inline Worker (Recommended)](#inline-worker-recommended)
+    - [Manual Worker Setup](#manual-worker-setup)
+    - [Advanced Usage](#advanced-usage)
+    - [Hash Algorithm Configuration](#hash-algorithm-configuration)
+  - [Demo](#demo)
+  - [API Reference](#api-reference)
+    - [Entry Points](#entry-points)
+      - [Mode 1: Inline Worker](#mode-1-inline-worker)
+        - [`createWorker(options?: OPFSOptions)`](#createworkeroptions-opfsoptions)
+      - [Mode 2: Manual Worker Setup](#mode-2-manual-worker-setup)
+        - [`OPFSWorker`](#opfsworker)
+    - [Core Methods](#core-methods)
+    - [Mount](#mount)
+      - [`mount(root?: string): Promise<boolean>`](#mountroot-string-promiseboolean)
+    - [Read File](#read-file)
+      - [`readFile(path: string, encoding?: BufferEncoding | 'binary'): Promise<string | Uint8Array>`](#readfilepath-string-encoding-bufferencoding--binary-promisestring--uint8array)
+    - [Write File](#write-file)
+      - [`writeFile(path: string, data: string | Uint8Array | ArrayBuffer, encoding?: BufferEncoding): Promise<void>`](#writefilepath-string-data-string--uint8array--arraybuffer-encoding-bufferencoding-promisevoid)
+    - [Append File](#append-file)
+      - [`appendFile(path: string, data: string | Uint8Array | ArrayBuffer, encoding?: BufferEncoding): Promise<void>`](#appendfilepath-string-data-string--uint8array--arraybuffer-encoding-bufferencoding-promisevoid)
+    - [Create Directory](#create-directory)
+      - [`mkdir(path: string, options?: { recursive?: boolean }): Promise<void>`](#mkdirpath-string-options--recursive-boolean--promisevoid)
+    - [Read Directory](#read-directory)
+      - [`readdir(path: string, options?: { withFileTypes?: boolean }): Promise<string[] | DirentData[]>`](#readdirpath-string-options--withfiletypes-boolean--promisestring--direntdata)
+    - [Get Stats](#get-stats)
+      - [`stat(path: string): Promise<FileStat>`](#statpath-string-promisefilestat)
+    - [Check Existence](#check-existence)
+      - [`exists(path: string): Promise<boolean>`](#existspath-string-promiseboolean)
+    - [Remove Path](#remove-path)
+      - [`remove(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>`](#removepath-string-options--recursive-boolean-force-boolean--promisevoid)
+    - [Copy Path](#copy-path)
+      - [`copy(source: string, destination: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>`](#copysource-string-destination-string-options--recursive-boolean-force-boolean--promisevoid)
+    - [Rename Path](#rename-path)
+      - [`rename(oldPath: string, newPath: string): Promise<void>`](#renameoldpath-string-newpath-string-promisevoid)
+    - [Clear Directory](#clear-directory)
+      - [`clear(path?: string): Promise<void>`](#clearpath-string-promisevoid)
+    - [Index File System](#index-file-system)
+      - [`index(): Promise<Map<string, FileStat>>`](#index-promisemapstring-filestat)
+    - [Sync File System](#sync-file-system)
+      - [`sync(entries: [string, string | Uint8Array | Blob][], options?: { cleanBefore?: boolean }): Promise<void>`](#syncentries-string-string--uint8array--blob-options--cleanbefore-boolean--promisevoid)
+    - [Watch](#watch)
+      - [`watch(path: string): Promise<void>`](#watchpath-string-promisevoid)
+    - [Unwatch](#unwatch)
+      - [`unwatch(path: string): void`](#unwatchpath-string-void)
+    - [Dispose](#dispose)
+      - [`dispose(): void`](#dispose-void)
+    - [Configuration](#configuration)
+      - [`setOptions(options: { watchInterval?: number; hashAlgorithm?: null | 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512'; maxFileSize?: number }): void`](#setoptionsoptions--watchinterval-number-hashalgorithm-null--sha-1--sha-256--sha-384--sha-512-maxfilesize-number--void)
+    - [Resolve Path](#resolve-path)
+      - [`realpath(path: string): Promise<string>`](#realpathpath-string-promisestring)
+  - [Binary File Handling](#binary-file-handling)
+    - [Reading Binary Files](#reading-binary-files)
+    - [Writing Binary Files](#writing-binary-files)
+    - [Working with Different Data Types](#working-with-different-data-types)
+    - [File Upload and Download](#file-upload-and-download)
+    - [Supported Encodings](#supported-encodings)
+  - [Utility Functions](#utility-functions)
+    - [Path Utilities](#path-utilities)
+    - [Data Conversion](#data-conversion)
+    - [File System Utilities](#file-system-utilities)
+  - [Types](#types)
+    - [`FileStat`](#filestat)
+    - [`DirentData`](#direntdata)
+    - [`RemoteOPFSWorker`](#remoteopfsworker)
+  - [Error Types](#error-types)
+  - [Browser Support](#browser-support)
+  - [Development](#development)
+    - [Building](#building)
+    - [Development Server](#development-server)
+    - [Testing](#testing)
+    - [Linting](#linting)
+  - [License](#license)
+  - [Contributing](#contributing)
 
 ### Entry Points
 
 #### Mode 1: Inline Worker
 
-##### `createWorker()`
+##### `createWorker(options?: OPFSOptions)`
 
 Creates a new file system instance with an inline worker.
 
 ```typescript
 import { createWorker } from 'opfs-worker/inline';
 
+// Basic usage
 const fs = await createWorker();
+
+// With options
+const fs = await createWorker({ 
+    watchInterval: 500,
+    hashAlgorithm: 'SHA-256',
+    broadcastChannel: 'my-app-events'
+});
+
+// Listen for file change events via BroadcastChannel
+const channel = new BroadcastChannel('my-app-events');
+channel.onmessage = (event) => {
+    console.log('File changed:', event.data);
+};
 ```
 
+**Parameters:**
+
+- `options` (optional): Configuration options
+  - `watchInterval` (optional): Polling interval in milliseconds for file watching
+  - `hashAlgorithm` (optional): Hash algorithm for file hashing
+  - `broadcastChannel` (optional): Custom name for the broadcast channel (default: 'opfs-worker')
+
 **Returns:** `Promise<RemoteOPFSWorker>` - A remote file system interface
 
 #### Mode 2: Manual Worker Setup
@@ -261,7 +410,7 @@ await fs.mount('/my-app');
 
 **Note:** All file operations will automatically mount the OPFS root if no explicit mount has been performed.
 
-**Watch Callbacks:** File watching with callbacks is only available when using the raw worker directly. The `createWorker()` function does not support watch callbacks due to Comlink limitations with function serialization.
+**File Change Events:** File change events are sent via BroadcastChannel. Set the `broadcastChannel` option to customize the channel name, or use the default 'opfs-worker' channel.
 
 ### Read File
 
@@ -400,9 +549,9 @@ detailed.forEach(item => {
 
 ### Get Stats
 
-#### `stat(path: string, options?: { includeHash?: boolean; hashAlgorithm?: string }): Promise<FileStat>`
+#### `stat(path: string): Promise<FileStat>`
 
-Get file or directory statistics.
+Get file or directory statistics. If hashing is enabled globally, file hashes will be included automatically.
 
 ```typescript
 // Basic stats
@@ -411,22 +560,20 @@ console.log(`File size: ${stats.size} bytes`);
 console.log(`Is file: ${stats.isFile}`);
 console.log(`Modified: ${stats.mtime}`);
 
-// Stats with hash
-const statsWithHash = await fs.stat('/config/settings.json', {
-    includeHash: true,
-    hashAlgorithm: 'SHA-1'
-});
-console.log(`Hash: ${statsWithHash.hash}`);
+// If hashing is enabled globally, hash will be included
+if (stats.hash) {
+    console.log(`Hash: ${stats.hash}`);
+}
 ```
 
 **Parameters:**
 
 - `path`: The path to the file or directory
-- `options.includeHash` (optional): Whether to calculate file hash (default: false)
-- `options.hashAlgorithm` (optional): Hash algorithm to use ('SHA-1', 'SHA-256', 'SHA-384', 'SHA-512', default: 'SHA-1')
 
 **Returns:** `Promise<FileStat>` - File/directory statistics
 
+**Note:** File hashing is controlled globally via the constructor options or `setOptions()` method. When enabled, all file stats will automatically include hash information.
+
 ### Check Existence
 
 #### `exists(path: string): Promise<boolean>`
@@ -522,20 +669,14 @@ await fs.clear('/data');
 
 ### Index File System
 
-#### `index(options?: { includeHash?: boolean; hashAlgorithm?: string }): Promise<Map<string, FileStat>>`
+#### `index(): Promise<Map<string, FileStat>>`
 
-Recursively list all files and directories with their stats.
+Recursively list all files and directories with their stats. If hashing is enabled globally, file hashes will be included automatically.
 
 ```typescript
-// Basic index without hash
+// Get complete file system index
 const index = await fs.index();
 
-// Index with file hash
-const indexWithHash = await fs.index({
-    includeHash: true,
-    hashAlgorithm: 'SHA-1'
-});
-
 // Iterate through all files and directories
 for (const [path, stat] of index) {
     console.log(`${path}: ${stat.isFile ? 'file' : 'directory'} (${stat.size} bytes)`);
@@ -550,13 +691,10 @@ if (fileStats) {
 }
 ```
 
-**Parameters:**
-
-- `options.includeHash` (optional): Whether to calculate file hash (default: false)
-- `options.hashAlgorithm` (optional): Hash algorithm to use (default: 'SHA-1')
-
 **Returns:** `Promise<Map<string, FileStat>>` - Map of path => FileStat
 
+**Note:** File hashing is controlled globally via the constructor options or `setOptions()` method. When enabled, all file stats in the index will automatically include hash information.
+
 ### Sync File System
 
 #### `sync(entries: [string, string | Uint8Array | Blob][], options?: { cleanBefore?: boolean }): Promise<void>`
@@ -611,6 +749,54 @@ Stop watching a previously watched path.
 fs.unwatch('/docs');
 ```
 
+### Dispose
+
+#### `dispose(): void`
+
+Dispose of resources and clean up the file system instance. This method should be called when the file system instance is no longer needed to properly clean up resources like the broadcast channel and watch timers.
+
+```typescript
+// Clean up resources when done
+fs.dispose();
+```
+
+**Note:** This method closes the broadcast channel, clears watch timers, and cleans up all watched paths. Call this when you're done with the file system instance to prevent memory leaks.
+
+### Configuration
+
+#### `setOptions(options: { watchInterval?: number; hashAlgorithm?: null | 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512'; maxFileSize?: number }): void`
+
+Update configuration options for the file system, including watch interval, hash algorithm, and maximum file size for hashing.
+
+```typescript
+// Enable SHA-256 hashing for all file operations
+fs.setOptions({ hashAlgorithm: 'SHA-256' });
+
+// Change watch interval to 100ms for faster change detection
+fs.setOptions({ watchInterval: 100 });
+
+// Set custom maximum file size for hashing (100MB)
+fs.setOptions({ maxFileSize: 100 * 1024 * 1024 });
+
+// Disable hashing
+fs.setOptions({ hashAlgorithm: null });
+
+// Update multiple options at once
+fs.setOptions({ 
+    watchInterval: 200, 
+    hashAlgorithm: 'SHA-1',
+    maxFileSize: 50 * 1024 * 1024 // 50MB
+});
+```
+
+**Parameters:**
+
+- `options.watchInterval` (optional): Polling interval in milliseconds for file watching
+- `options.hashAlgorithm` (optional): Hash algorithm to use, or `null` to disable hashing
+- `options.maxFileSize` (optional): Maximum file size in bytes for hashing (default: 50MB)
+
+**Note:** When a hash algorithm is set, all file operations (`stat`, `index`, watch events) will automatically include hash information for files within the size limit. Files exceeding `maxFileSize` will not have hash information. Set `hashAlgorithm` to `null` to disable hashing and improve performance.
+
 ### Resolve Path
 
 #### `realpath(path: string): Promise<string>`
@@ -898,4 +1084,4 @@ MIT
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! Please feel free to submit a Pull Request.