opfs-worker 1.3.2 → 2.1.0

package/dist/{worker.d.ts → core/BaseOPFS.d.ts}

@@ -1,39 +1,20 @@
-import type { DirentData, FileOpenOptions, FileStat, OPFSOptions, RenameOptions, WatchOptions } from './types';
+import type { DirentData, FileStat, OPFSOptions, RenameOptions, WatchEvent, WatchOptions, WatchSnapshot } from '../types';
 /**
- * OPFS (Origin Private File System) File System implementation
- *
- * This class provides a high-level interface for working with the browser's
- * Origin Private File System API, offering file and directory operations
- * similar to Node.js fs module.
- *
- * @example
- * ```typescript
- * const fs = new OPFSFileSystem();
- * await fs.init('/my-app');
- * await fs.writeFile('/data/config.json', JSON.stringify({ theme: 'dark' }));
- * const config = await fs.readFile('/data/config.json');
- * ```
+ * Shared OPFS logic (directories, meta, watch, high-level helpers).
+ * File I/O backends implement {@link readFile}, {@link writeFile}, {@link appendFile},
+ * and {@link writeStream}.
  */
-export declare class OPFSWorker {
+export declare abstract class BaseOPFS {
     /** Root directory handle for the file system */
-    private root;
+    protected root: FileSystemDirectoryHandle;
     /** Map of watched paths and options */
-    private watchers;
+    protected watchers: Map<string, WatchSnapshot>;
     /** Promise to prevent concurrent mount operations */
-    private mountingPromise;
+    protected mountingPromise: Promise<boolean> | null;
     /** BroadcastChannel instance for sending events */
-    private broadcastChannel;
+    protected broadcastChannel: BroadcastChannel | null;
     /** 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;
+    protected options: Required<OPFSOptions>;
     /**
      * Notify about internal changes to the file system
      *
@@ -42,39 +23,21 @@ export declare class OPFSWorker {
      *
      * @param event - The event describing the change
      */
-    private notifyChange;
-    /**
-     * Creates a new OPFSFileSystem instance
-     *
-     * @param options - Optional configuration options
-     * @param options.root - Root path for the file system (default: '/')
-     * @param options.watchInterval - Polling interval in milliseconds for file watching
-     * @param options.hashAlgorithm - Hash algorithm for file hashing
-     * @param options.maxFileSize - Maximum file size for hashing in bytes (default: 50MB)
-     * @throws {OPFSError} If OPFS is not supported in the current browser
-     */
+    protected notifyChange(event: Omit<WatchEvent, 'timestamp' | 'hash' | 'namespace'>): Promise<void>;
     constructor(options?: OPFSOptions);
+    /** Read file contents as bytes */
+    abstract readFile(path: string): Promise<Uint8Array>;
+    /** Create or overwrite a file with binary data */
+    abstract writeFile(path: string, data: Uint8Array | ArrayBuffer): Promise<void>;
+    /** Append binary data to a file */
+    abstract appendFile(path: string, data: Uint8Array | ArrayBuffer): Promise<void>;
+    /** Create or overwrite a file from a byte stream */
+    abstract writeStream(path: string, stream: ReadableStream<Uint8Array>, onProgress?: (bytesWritten: number) => unknown): Promise<number>;
     /**
-     * Initialize the file system within a given directory
-     *
-     * This method sets up the root directory for all subsequent operations.
-     * If no root is specified, it will use the OPFS root directory.
-     *
-     * @returns Promise that resolves to true if initialization was successful
-     * @throws {OPFSError} If initialization fails
-     *
-     * @example
-     * ```typescript
-     * const fs = new OPFSFileSystem();
-     *
-     * // Use OPFS root (default)
-     * await fs.mount();
-     *
-     * // Use custom directory
-     * await fs.mount('/my-app');
-     * ```
+     * Initialize the file system within a given directory.
+     * If no root is specified, uses the OPFS root directory.
      */
-    private mount;
+    protected mount(): Promise<boolean>;
     /**
      * Update configuration options
      *
@@ -104,7 +67,7 @@ export declare class OPFSWorker {
      * const docsDir2 = await fs.getDirectoryHandle(['users', 'john', 'documents'], true);
      * ```
      */
-    private getDirectoryHandle;
+    protected getDirectoryHandle(path: string | string[], create?: boolean, from?: FileSystemDirectoryHandle | null): Promise<FileSystemDirectoryHandle>;
     /**
      * Get a file handle from a path
      *
@@ -124,7 +87,7 @@ export declare class OPFSWorker {
      * const fileHandle2 = await fs.getFileHandle(['config', 'settings.json'], true);
      * ```
      */
-    private getFileHandle;
+    protected getFileHandle(path: string | string[], create?: boolean, _from?: FileSystemDirectoryHandle | null): Promise<FileSystemFileHandle>;
     /**
      * Get a complete index of all files and directories in the file system
      *
@@ -145,72 +108,6 @@ export declare class OPFSWorker {
      * ```
      */
     index(): Promise<Map<string, FileStat>>;
-    /**
-     * Read a file from the file system
-     *
-     * Reads the contents of a file and returns it as binary data.
-     *
-     * @param path - The path to the file to read
-     * @returns Promise that resolves to the file contents as Uint8Array
-     * @throws {FileNotFoundError} If the file does not exist
-     * @throws {OPFSError} If reading the file fails
-     *
-     * @example
-     * ```typescript
-     * // Read as binary data
-     * const content = await fs.readFile('/config/settings.json');
-     *
-     * // Read binary file
-     * const binaryData = await fs.readFile('/images/logo.png');
-     * ```
-     */
-    readFile(path: string): Promise<Uint8Array>;
-    /**
-     * Write data to a file
-     *
-     * Creates or overwrites a file with the specified binary data. If the file already
-     * exists, it will be truncated before writing.
-     *
-     * @param path - The path to the file to write
-     * @param data - The binary data to write to the file (Uint8Array or ArrayBuffer)
-     * @returns Promise that resolves when the write operation is complete
-     * @throws {OPFSError} If writing the file fails
-     *
-     * @example
-     * ```typescript
-     * // Write binary data
-     * const binaryData = new Uint8Array([1, 2, 3, 4, 5]);
-     * await fs.writeFile('/data/binary.dat', binaryData);
-     *
-     * // Write from ArrayBuffer
-     * const arrayBuffer = new ArrayBuffer(10);
-     * await fs.writeFile('/data/buffer.dat', arrayBuffer);
-     * ```
-     */
-    writeFile(path: string, data: Uint8Array | ArrayBuffer): Promise<void>;
-    /**
-     * Append data to a file
-     *
-     * Adds binary data to the end of an existing file. If the file doesn't exist,
-     * it will be created.
-     *
-     * @param path - The path to the file to append to
-     * @param data - The binary data to append to the file (Uint8Array or ArrayBuffer)
-     * @returns Promise that resolves when the append operation is complete
-     * @throws {OPFSError} If appending to the file fails
-     *
-     * @example
-     * ```typescript
-     * // Append binary data
-     * const additionalData = new Uint8Array([6, 7, 8]);
-     * await fs.appendFile('/data/binary.dat', additionalData);
-     *
-     * // Append from ArrayBuffer
-     * const arrayBuffer = new ArrayBuffer(5);
-     * await fs.appendFile('/data/buffer.dat', arrayBuffer);
-     * ```
-     */
-    appendFile(path: string, data: Uint8Array | ArrayBuffer): Promise<void>;
     /**
      * Create a directory
      *
@@ -442,187 +339,24 @@ export declare class OPFSWorker {
      */
     unwatch(path: string): void;
     /**
-     * Open a file and return a file descriptor
+     * Bulk-create files from `[path, data]` entries (strings, bytes, or Blobs).
      *
-     * @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
+     * @param entries - Array of `[path, data]` tuples
+     * @throws {OPFSError} If a write 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)
-     * @param emitEvent - Whether to emit a change event (default: true)
-     * @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, emitEvent?: boolean): 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
+     * await fs.createIndex([
+     *   ['/config.json', JSON.stringify({ theme: 'dark' })],
+     *   ['/data/binary.dat', new Uint8Array([1, 2, 3, 4])],
+     *   ['/upload.txt', new Blob(['file content'], { type: 'text/plain' })],
+     * ]);
      * ```
      */
-    fsync(fd: number): Promise<void>;
+    createIndex(entries: [string, string | Uint8Array | Blob][]): Promise<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.
      */
     dispose(): void;
-    /**
-     * Synchronize the file system with external data
-     *
-     * Syncs the file system with an array of entries containing paths and data.
-     * This is useful for importing data from external sources or syncing with remote data.
-     *
-     * @param entries - Array of [path, data] tuples to sync
-     * @returns Promise that resolves when synchronization is complete
-     * @throws {OPFSError} If the synchronization fails
-     *
-     * @example
-     * ```typescript
-     * // Sync with external data
-     * const entries: [string, string | Uint8Array | Blob][] = [
-     *   ['/config.json', JSON.stringify({ theme: 'dark' })],
-     *   ['/data/binary.dat', new Uint8Array([1, 2, 3, 4])],
-     *   ['/upload.txt', new Blob(['file content'], { type: 'text/plain' })]
-     * ];
-     *
-     * // Sync without clearing existing files
-     * await fs.sync(entries);
-     *
-     * // Clean file system and then sync
-     * await fs.sync(entries, { cleanBefore: true });
-     * ```
-     */
-    createIndex(entries: [string, string | Uint8Array | Blob][]): Promise<void>;
 }
-//# sourceMappingURL=worker.d.ts.map
+//# sourceMappingURL=BaseOPFS.d.ts.map

package/dist/core/BaseOPFS.d.ts.map

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

package/dist/core/OPFSAsync.d.ts

@@ -0,0 +1,55 @@
+import { BaseOPFS } from './BaseOPFS';
+import type { FileOpenOptions, FileStat } from '../types';
+/**
+ * Async OPFS backend using the promise-based File System API
+ * (`getFile()` / `createWritable()`).
+ *
+ * Unlike `OPFSSync`, it does not require a dedicated worker: it works on the
+ * main thread and inside any worker type (including SharedWorker).
+ *
+ * Requirements and limitations:
+ * - Writing needs `FileSystemFileHandle.createWritable()` — Chrome, Firefox, Safari 26+.
+ *   Reading works in older Safari too.
+ * - No file descriptors / positional I/O: `open`, `read`, `write`, `close`,
+ *   `fstat`, `ftruncate` and `fsync` always throw `OperationNotSupportedError`.
+ *
+ * @example
+ * ```typescript
+ * import { OPFSAsync } from 'opfs-worker/pure';
+ * // or: 'opfs-worker' / 'opfs-worker/async'
+ *
+ * const fs = new OPFSAsync({ root: '/my-app' });
+ * await fs.writeFile('/config.json', new TextEncoder().encode('{}'));
+ * const config = await fs.readFile('/config.json');
+ * ```
+ */
+export declare class OPFSAsync extends BaseOPFS {
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array | ArrayBuffer): Promise<void>;
+    appendFile(path: string, data: Uint8Array | ArrayBuffer): Promise<void>;
+    writeStream(path: string, stream: ReadableStream<Uint8Array>, onProgress?: (bytesWritten: number) => unknown): Promise<number>;
+    /**
+     * Open a writable stream, run the write callback and commit via close().
+     * Aborts the stream (discarding the swap file) if the callback fails.
+     * @private
+     */
+    private _writeStream;
+    /** @throws {OperationNotSupportedError} Always — no FD support in the async backend */
+    open(_path: string, _options?: FileOpenOptions): Promise<number>;
+    /** @throws {OperationNotSupportedError} Always — no FD support in the async backend */
+    close(_fd: number): Promise<void>;
+    /** @throws {OperationNotSupportedError} Always — no FD support in the async backend */
+    read(_fd: number, _buffer: Uint8Array, _offset: number, _length: number, _position: number | null | undefined): Promise<{
+        bytesRead: number;
+        buffer: Uint8Array;
+    }>;
+    /** @throws {OperationNotSupportedError} Always — no FD support in the async backend */
+    write(_fd: number, _buffer: Uint8Array, _offset?: number, _length?: number, _position?: number | null | undefined, _emitEvent?: boolean): Promise<number>;
+    /** @throws {OperationNotSupportedError} Always — no FD support in the async backend */
+    fstat(_fd: number): Promise<FileStat>;
+    /** @throws {OperationNotSupportedError} Always — no FD support in the async backend */
+    ftruncate(_fd: number, _size?: number): Promise<void>;
+    /** @throws {OperationNotSupportedError} Always — no FD support in the async backend */
+    fsync(_fd: number): Promise<void>;
+}
+//# sourceMappingURL=OPFSAsync.d.ts.map

package/dist/core/OPFSAsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OPFSAsync.d.ts","sourceRoot":"","sources":["../../src/core/OPFSAsync.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKtC,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,SAAU,SAAQ,QAAQ;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAqB3C,SAAS,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,GAAG,WAAW,GAC/B,OAAO,CAAC,IAAI,CAAC;IA0BV,UAAU,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,GAAG,WAAW,GAC/B,OAAO,CAAC,IAAI,CAAC;IA4BV,WAAW,CACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,UAAU,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/C,OAAO,CAAC,MAAM,CAAC;IAoDlB;;;;OAIG;YACW,YAAY;IAuB1B,uFAAuF;IACjF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAItE,uFAAuF;IACjF,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,uFAAuF;IACjF,IAAI,CACN,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,UAAU,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,CAAC;IAIrD,uFAAuF;IACjF,KAAK,CACP,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,UAAU,EACnB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACrC,UAAU,CAAC,EAAE,OAAO,GACrB,OAAO,CAAC,MAAM,CAAC;IAIlB,uFAAuF;IACjF,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI3C,uFAAuF;IACjF,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D,uFAAuF;IACjF,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C"}

package/dist/core/OPFSSync.d.ts

@@ -0,0 +1,54 @@
+import { BaseOPFS } from './BaseOPFS';
+import type { FileOpenOptions, FileStat, OPFSOptions } from '../types';
+/**
+ * Sync OPFS backend using `FileSystemSyncAccessHandle` (dedicated worker only).
+ *
+ * Provides high-level file I/O and Node-like file descriptors.
+ *
+ * @example
+ * ```typescript
+ * import { OPFSSync } from 'opfs-worker/pure';
+ *
+ * const fs = new OPFSSync();
+ * await fs.writeFile('/data/config.json', new TextEncoder().encode(JSON.stringify({ theme: 'dark' })));
+ * const config = await fs.readFile('/data/config.json');
+ * ```
+ */
+export declare class OPFSSync extends BaseOPFS {
+    /** 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 */
+    private nextFd;
+    constructor(options?: OPFSOptions);
+    /**
+     * Get file info by descriptor with validation
+     * @private
+     */
+    private _getFileDescriptor;
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array | ArrayBuffer): Promise<void>;
+    appendFile(path: string, data: Uint8Array | ArrayBuffer): Promise<void>;
+    writeStream(path: string, stream: ReadableStream<Uint8Array>, onProgress?: (bytesWritten: number) => unknown): Promise<number>;
+    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;
+    close(fd: number): Promise<void>;
+    read(fd: number, buffer: Uint8Array, offset: number, length: number, position: number | null | undefined): Promise<{
+        bytesRead: number;
+        buffer: Uint8Array;
+    }>;
+    write(fd: number, buffer: Uint8Array, offset?: number, length?: number, position?: number | null | undefined, emitEvent?: boolean): Promise<number>;
+    fstat(fd: number): Promise<FileStat>;
+    ftruncate(fd: number, size?: number): Promise<void>;
+    fsync(fd: number): Promise<void>;
+    dispose(): void;
+}
+//# sourceMappingURL=OPFSSync.d.ts.map

package/dist/core/OPFSSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OPFSSync.d.ts","sourceRoot":"","sources":["../../src/core/OPFSSync.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAoBtC,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AACH,qBAAa,QAAS,SAAQ,QAAQ;IAClC,0EAA0E;IAC1E,OAAO,CAAC,WAAW,CAId;IAEL,qDAAqD;IACrD,OAAO,CAAC,SAAS,CAKZ;IAEL,4CAA4C;IAC5C,OAAO,CAAC,MAAM,CAAK;gBAEP,OAAO,CAAC,EAAE,WAAW;IAIjC;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAUpB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA+B3C,SAAS,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,GAAG,WAAW,GAC/B,OAAO,CAAC,IAAI,CAAC;IAqBV,UAAU,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,GAAG,WAAW,GAC/B,OAAO,CAAC,IAAI,CAAC;IAsBV,WAAW,CACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,UAAU,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,GAC/C,OAAO,CAAC,MAAM,CAAC;IAwDZ,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAwCpE;;;;;;OAMG;YACW,SAAS;IAuCjB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBhC,IAAI,CACN,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACpC,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,CAAC;IAmC/C,KAAK,CACP,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,MAAU,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,SAAS,GAAE,OAAc,GAC1B,OAAO,CAAC,MAAM,CAAC;IAoCZ,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAOpC,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBtD,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW7B,OAAO,IAAI,IAAI;CAY3B"}

package/dist/createOPFSAsync-BwKDmHsy.cjs

@@ -0,0 +1,2 @@
+"use strict";const c=require("./OPFSFacade-DePnNRgt.cjs"),n=require("./OPFSAsync-s2P7y3sw.cjs");function r(s){const e=new n.OPFSAsync(s);return new c.OPFSFacade({fs:e,dispose:()=>e.dispose()})}exports.createOPFSAsync=r;
+//# sourceMappingURL=createOPFSAsync-BwKDmHsy.cjs.map

package/dist/createOPFSAsync-BwKDmHsy.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createOPFSAsync-BwKDmHsy.cjs","sources":["../src/facade/createOPFSAsync.ts"],"sourcesContent":["import { OPFSFacade } from './OPFSFacade';\nimport { OPFSAsync } from '../core/OPFSAsync';\n\nimport type { OPFSOptions } from '../types';\n\n/**\n * Async mode: Node-like `fs` API over the promise-based File System API,\n * without any worker.\n *\n * Prefer importing from `opfs-worker/async` when you care about bundle size\n * (avoids the inlined dedicated worker). Importing from `opfs-worker` works too.\n *\n * Writing requires `FileSystemFileHandle.createWritable()` — Chrome, Firefox,\n * Safari 26+. File descriptors (`open`/`read`/`write`/...) are not supported\n * and throw `OperationNotSupportedError` — use `createOPFSDedicated` from `opfs-worker`\n * or `opfs-worker/sync` for positional I/O.\n */\nexport function createOPFSAsync(options?: OPFSOptions): OPFSFacade {\n    const fs = new OPFSAsync(options);\n\n    return new OPFSFacade({ fs, dispose: () => fs.dispose() });\n}\n"],"names":["createOPFSAsync","options","fs","OPFSAsync","OPFSFacade"],"mappings":"gGAiBO,SAASA,EAAgBC,EAAmC,CAC/D,MAAMC,EAAK,IAAIC,EAAAA,UAAUF,CAAO,EAEhC,OAAO,IAAIG,EAAAA,WAAW,CAAE,GAAAF,EAAI,QAAS,IAAMA,EAAG,QAAA,EAAW,CAC7D"}

package/dist/createOPFSAsync-Y4Mg6qte.js

@@ -0,0 +1,10 @@
+import { O as o } from "./OPFSFacade-XohWlHuu.js";
+import { O as n } from "./OPFSAsync-BKSAJJeh.js";
+function t(e) {
+  const s = new n(e);
+  return new o({ fs: s, dispose: () => s.dispose() });
+}
+export {
+  t as c
+};
+//# sourceMappingURL=createOPFSAsync-Y4Mg6qte.js.map

package/dist/createOPFSAsync-Y4Mg6qte.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createOPFSAsync-Y4Mg6qte.js","sources":["../src/facade/createOPFSAsync.ts"],"sourcesContent":["import { OPFSFacade } from './OPFSFacade';\nimport { OPFSAsync } from '../core/OPFSAsync';\n\nimport type { OPFSOptions } from '../types';\n\n/**\n * Async mode: Node-like `fs` API over the promise-based File System API,\n * without any worker.\n *\n * Prefer importing from `opfs-worker/async` when you care about bundle size\n * (avoids the inlined dedicated worker). Importing from `opfs-worker` works too.\n *\n * Writing requires `FileSystemFileHandle.createWritable()` — Chrome, Firefox,\n * Safari 26+. File descriptors (`open`/`read`/`write`/...) are not supported\n * and throw `OperationNotSupportedError` — use `createOPFSDedicated` from `opfs-worker`\n * or `opfs-worker/sync` for positional I/O.\n */\nexport function createOPFSAsync(options?: OPFSOptions): OPFSFacade {\n    const fs = new OPFSAsync(options);\n\n    return new OPFSFacade({ fs, dispose: () => fs.dispose() });\n}\n"],"names":["createOPFSAsync","options","fs","OPFSAsync","OPFSFacade"],"mappings":";;AAiBO,SAASA,EAAgBC,GAAmC;AAC/D,QAAMC,IAAK,IAAIC,EAAUF,CAAO;AAEhC,SAAO,IAAIG,EAAW,EAAE,IAAAF,GAAI,SAAS,MAAMA,EAAG,QAAA,GAAW;AAC7D;"}