opfs-worker 1.0.1 → 1.2.0

package/README.md

@@ -21,6 +21,7 @@ A robust TypeScript library for working with Origin Private File System (OPFS) t
 ### 🚀 **Performance & Architecture**
 
 - **Web Worker-based**: Runs in a separate thread, keeping your main thread responsive
+- **Zero-copy data transfer**: Efficient binary data handling with Comlink transfer
 - **Faster than IndexedDB hacks**: Direct OPFS access without the overhead of database abstractions
 - **Efficient file watching**: Real-time change detection with minimatch patterns, no polling delays
 
@@ -157,6 +158,10 @@ async function extendedExample() {
     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
+
     // Use file watching with BroadcastChannel
     await fs.watch('/', {
         recursive: true,
@@ -219,8 +224,9 @@ async function extendedExample() {
     // Create directories
     await worker.mkdir('/data/logs', { recursive: true });
 
-    // Append to log files
-    await worker.appendFile('/data/logs/app.log', `${new Date().toISOString()}: App started\n`);
+    // 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);
 
     // Watch for changes
     await worker.watch('/data', { recursive: true });
@@ -345,17 +351,29 @@ Check out the live demo powered by Vite and hosted on GitHub Pages.
 
 The complete API reference is available in the [docs/api-reference.md](docs/api-reference.md) file.
 
+**Additional Documentation:**
+
+- [File Descriptors Guide](docs/file-descriptors.md) - Comprehensive guide to low-level file I/O operations
+- [Types Reference](docs/types.md) - Complete TypeScript type definitions
+
 ### Quick API Overview
 
 **Entry Points:**
 
-- `createWorker(options?)` - Create file system instance with inline worker
-- `OPFSWorker` - Direct worker class for manual setup
+- `createWorker(options?)` - Create file system instance with inline worker (recommended)
+- `OPFSFileSystem` - High-level facade with automatic encoding detection
+- `OPFSWorker` - Direct webworker class
 
 **Core File Operations:**
 
-- `readFile(path, encoding?)` - Read files as text or binary
-- `writeFile(path, data, encoding?)` - Write text or binary data
+- `readFile(path, encoding?)` - Read files as text or binary with auto-detection
+- `writeFile(path, data, encoding?)` - Write text or binary data with auto-detection
+- `readText(path, encoding?)` - Read files as text with specified encoding
+- `writeText(path, text, encoding?)` - Write text with specified encoding
+- `appendText(path, text, encoding?)` - Append text with specified encoding
+
+**Common Operations:**
+
 - `mkdir(path, options?)` - Create directories
 - `readDir(path)` - List directory contents
 - `stat(path)` - Get file/directory statistics
@@ -363,6 +381,20 @@ The complete API reference is available in the [docs/api-reference.md](docs/api-
 - `copy(source, destination, options?)` - Copy files/directories
 - `rename(oldPath, newPath)` - Rename files/directories
 
+**File Descriptors (Low-level I/O):**
+
+- `open(path, options?)` - Open file and return descriptor
+- `read(fd, buffer, offset, length, position?)` - Read from descriptor (returns `{bytesRead, buffer}`)
+- `write(fd, buffer, offset?, length?, position?)` - Write to descriptor
+- `fstat(fd)` - Get stats by descriptor
+- `ftruncate(fd, size?)` - Truncate file by descriptor
+- `fsync(fd)` - Sync file data to storage
+- `close(fd)` - Close file descriptor
+
+**Note**: The `read()` method uses `Comlink.transfer()` for efficient buffer handling. **From the main window**, you must transfer buffer ownership to the worker, and **from the worker**, the buffer is transferred back to you. See [File Descriptors Guide](docs/file-descriptors.md) for complete usage examples.
+
+_For detailed file descriptor documentation, see [File Descriptors Guide](docs/file-descriptors.md)_
+
 **Advanced Features:**
 
 - `watch(path, options?)` - Watch for file changes with minimatch patterns