opfs-worker 1.0.1 → 1.1.0

package/dist/worker.d.ts

@@ -1,4 +1,4 @@
-import type { DirentData, Encoding, FileStat, OPFSOptions, RenameOptions, WatchOptions } from './types';
+import type { DirentData, Encoding, FileOpenOptions, FileStat, OPFSOptions, RenameOptions, WatchOptions } from './types';
 import type { BufferEncoding } from 'typescript';
 /**
  * OPFS (Origin Private File System) File System implementation
@@ -26,6 +26,15 @@ export declare class OPFSWorker {
     private broadcastChannel;
     /** Configuration options */
     private options;
+    /** Map of open file descriptors to their metadata */
+    private openFiles;
+    /** Next available file descriptor number */
+    private nextFd;
+    /**
+     * Get file info by descriptor with validation
+     * @private
+     */
+    private _getFileDescriptor;
     /**
      * Notify about internal changes to the file system
      *
@@ -445,6 +454,154 @@ export declare class OPFSWorker {
      * Stop watching a previously watched path
      */
     unwatch(path: string): void;
+    /**
+     * Open a file and return a file descriptor
+     *
+     * @param path - The path to the file to open
+     * @param options - Options for opening the file
+     * @param options.create - Whether to create the file if it doesn't exist (default: false)
+     * @param options.exclusive - If true and create is true, fails if file already exists (default: false)
+     *                            Note: This is best-effort in OPFS, not fully atomic due to browser limitations
+     * @param options.truncate - Whether to truncate the file to zero length (default: false)
+     * @returns Promise that resolves to a file descriptor number
+     * @throws {OPFSError} If opening the file fails
+     *
+     * @example
+     * ```typescript
+     * // Open existing file for reading
+     * const fd = await fs.open('/data/config.json');
+     *
+     * // Create new file for writing
+     * const fd = await fs.open('/data/new.txt', { create: true });
+     *
+     * // Create file exclusively (fails if exists)
+     * const fd = await fs.open('/data/unique.txt', { create: true, exclusive: true });
+     *
+     * // Open and truncate file
+     * const fd = await fs.open('/data/log.txt', { create: true, truncate: true });
+     * ```
+     */
+    open(path: string, options?: FileOpenOptions): Promise<number>;
+    /**
+     * Internal method to open a file (without locking)
+     * @private
+     */
+    private _openFile;
+    /**
+     * Close a file descriptor
+     *
+     * @param fd - The file descriptor to close
+     * @returns Promise that resolves when the file descriptor is closed
+     * @throws {OPFSError} If the file descriptor is invalid or closing fails
+     *
+     * @example
+     * ```typescript
+     * const fd = await fs.open('/data/file.txt');
+     * // ... use the file descriptor ...
+     * await fs.close(fd);
+     * ```
+     */
+    close(fd: number): Promise<void>;
+    /**
+     * Read data from a file descriptor
+     *
+     * @param fd - The file descriptor to read from
+     * @param buffer - The buffer to read data into
+     * @param offset - The offset in the buffer to start writing at
+     * @param length - The number of bytes to read
+     * @param position - The position in the file to read from (null for current position)
+     * @returns Promise that resolves to the number of bytes read and the modified buffer
+     * @throws {OPFSError} If the file descriptor is invalid or reading fails
+     *
+     * @note This method uses Comlink.transfer() to efficiently pass the buffer as a Transferable Object,
+     *       ensuring zero-copy performance across Web Worker boundaries.
+     *
+     * @example
+     * ```typescript
+     * const fd = await fs.open('/data/file.txt');
+     * const buffer = new Uint8Array(1024);
+     * const { bytesRead, buffer: modifiedBuffer } = await fs.read(fd, buffer, 0, 1024, null);
+     * console.log(`Read ${bytesRead} bytes`);
+     * // Use modifiedBuffer which contains the actual data
+     * await fs.close(fd);
+     * ```
+     */
+    read(fd: number, buffer: Uint8Array, offset: number, length: number, position: number | null | undefined): Promise<{
+        bytesRead: number;
+        buffer: Uint8Array;
+    }>;
+    /**
+     * Write data to a file descriptor
+     *
+     * @param fd - The file descriptor to write to
+     * @param buffer - The buffer containing data to write
+     * @param offset - The offset in the buffer to start reading from (default: 0)
+     * @param length - The number of bytes to write (default: entire buffer)
+     * @param position - The position in the file to write to (null/undefined for current position)
+     * @returns Promise that resolves to the number of bytes written
+     * @throws {OPFSError} If the file descriptor is invalid or writing fails
+     *
+     * @example
+     * ```typescript
+     * const fd = await fs.open('/data/file.txt', { create: true });
+     * const data = new TextEncoder().encode('Hello, World!');
+     * const bytesWritten = await fs.write(fd, data, 0, data.length, null);
+     * console.log(`Wrote ${bytesWritten} bytes`);
+     * await fs.close(fd);
+     * ```
+     */
+    write(fd: number, buffer: Uint8Array, offset?: number, length?: number, position?: number | null | undefined): Promise<number>;
+    /**
+     * Get file status information by file descriptor
+     *
+     * @param fd - The file descriptor
+     * @returns Promise that resolves to FileStat object
+     * @throws {OPFSError} If the file descriptor is invalid
+     *
+     * @example
+     * ```typescript
+     * const fd = await fs.open('/data/file.txt');
+     * const stats = await fs.fstat(fd);
+     * console.log(`File size: ${stats.size} bytes`);
+     * console.log(`Last modified: ${stats.mtime}`);
+     *
+     * // If hashing is enabled, hash will be included
+     * if (stats.hash) {
+     *   console.log(`Hash: ${stats.hash}`);
+     * }
+     * ```
+     */
+    fstat(fd: number): Promise<FileStat>;
+    /**
+     * Truncate file to specified size
+     *
+     * @param fd - The file descriptor
+     * @param size - The new size of the file (default: 0)
+     * @returns Promise that resolves when truncation is complete
+     * @throws {OPFSError} If the file descriptor is invalid or truncation fails
+     *
+     * @example
+     * ```typescript
+     * const fd = await fs.open('/data/file.txt', { create: true });
+     * await fs.truncate(fd, 100); // Truncate to 100 bytes
+     * ```
+     */
+    ftruncate(fd: number, size?: number): Promise<void>;
+    /**
+     * Synchronize file data to storage (fsync equivalent)
+     *
+     * @param fd - The file descriptor
+     * @returns Promise that resolves when synchronization is complete
+     * @throws {OPFSError} If the file descriptor is invalid or sync fails
+     *
+     * @example
+     * ```typescript
+     * const fd = await fs.open('/data/file.txt', { create: true });
+     * await fs.write(fd, data);
+     * await fs.fsync(fd); // Ensure data is written to storage
+     * ```
+     */
+    fsync(fd: number): Promise<void>;
     /**
      * Dispose of resources and clean up the file system instance
      *

package/dist/worker.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "opfs-worker",
-    "version": "1.0.1",
+    "version": "1.1.0",
     "description": "A robust TypeScript library for working with Origin Private File System (OPFS) through Web Workers",
     "type": "module",
     "main": "dist/index.js",