opfs-worker 2.1.0 → 2.1.2

package/src/core/BaseOPFS.ts

@@ -16,7 +16,6 @@ import {
     basename,
     calculateFileHash,
     checkOPFSSupport,
-    convertBlobToUint8Array,
     dirname,
     joinPath,
     matchMinimatch,
@@ -24,16 +23,31 @@ import {
     normalizePath,
     removeEntry,
     resolvePath,
-    splitPath
+    splitPath,
+    withLock
 } from '../utils/helpers';
 
-import type { DirentData, FileStat, OPFSOptions, RenameOptions, WatchEvent, WatchOptions, WatchSnapshot } from '../types';
+import type {
+    DirentData,
+    FileOpenOptions,
+    FileStat,
+    ImportFileData,
+    ImportFilesEntries,
+    ImportFilesProgress,
+    ImportFilesResult,
+    OPFSOptions,
+    RenameOptions,
+    WatchEvent,
+    WatchOptions,
+    WatchSnapshot,
+} from '../types';
 
 
 /**
  * Shared OPFS logic (directories, meta, watch, high-level helpers).
- * File I/O backends implement {@link readFile}, {@link writeFile}, {@link appendFile},
- * and {@link writeStream}.
+ *
+ * Subclasses implement byte I/O and file descriptors. Together those methods
+ * are the {@link OPFSApi} contract used by the facade and Comlink proxies.
  */
 export abstract class BaseOPFS {
     /** Root directory handle for the file system */
@@ -124,6 +138,11 @@ export abstract class BaseOPFS {
         }
     }
 
+    /** Exclusive path lock keyed by absolute OPFS path (`root` + API path). */
+    protected async withPathLock<T>(path: string, fn: () => Promise<T>): Promise<T> {
+        return withLock(path, fn, this.options.root);
+    }
+
     /** Read file contents as bytes */
     abstract readFile(path: string): Promise<Uint8Array>;
 
@@ -140,6 +159,40 @@ export abstract class BaseOPFS {
         onProgress?: (bytesWritten: number) => unknown
     ): Promise<number>;
 
+    /** Open a file and return a file descriptor */
+    abstract open(path: string, options?: FileOpenOptions): Promise<number>;
+
+    /** Close a file descriptor */
+    abstract close(fd: number): Promise<void>;
+
+    /** Read from a file descriptor into a buffer */
+    abstract read(
+        fd: number,
+        buffer: Uint8Array,
+        offset: number,
+        length: number,
+        position: number | null | undefined
+    ): Promise<{ bytesRead: number; buffer: Uint8Array }>;
+
+    /** Write from a buffer to a file descriptor */
+    abstract write(
+        fd: number,
+        buffer: Uint8Array,
+        offset?: number,
+        length?: number,
+        position?: number | null | undefined,
+        emitEvent?: boolean
+    ): Promise<number>;
+
+    /** File stats by descriptor */
+    abstract fstat(fd: number): Promise<FileStat>;
+
+    /** Truncate a file by descriptor */
+    abstract ftruncate(fd: number, size?: number): Promise<void>;
+
+    /** Flush a file descriptor to storage */
+    abstract fsync(fd: number): Promise<void>;
+
     /**
      * Initialize the file system within a given directory.
      * If no root is specified, uses the OPFS root directory.
@@ -671,7 +724,7 @@ export abstract class BaseOPFS {
         const parent = await this.getDirectoryHandle(dirname(path), false);
         const stat = await this.stat(path);
 
-        await removeEntry(parent, path, { recursive, force });
+        await removeEntry(parent, path, { recursive, force, root: this.options.root });
 
         await this.notifyChange({ path, type: WatchEventType.Removed, isDirectory: stat.isDirectory });
     }
@@ -891,42 +944,105 @@ export abstract class BaseOPFS {
     }
 
     /**
-     * Bulk-create files from `[path, data]` entries (strings, bytes, or Blobs).
+     * Read a file as a `Blob` without copying its bytes into memory.
      *
-     * @param entries - Array of `[path, data]` tuples
-     * @throws {OPFSError} If a write fails
+     * OPFS hands back a disk-backed `File`, so the browser can stream it on
+     * demand — pass it to `URL.createObjectURL()` for `<video>` / `<audio>` /
+     * `<img>` and only the played range is actually read. Structured clone keeps
+     * the reference intact when the file system runs in a worker.
+     *
+     * @param path - Path to the file
+     * @returns Lazy `File` handle backed by OPFS storage
+     * @throws {OPFSError} If the path is missing or is a directory
      *
      * @example
      * ```typescript
-     * 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' })],
-     * ]);
+     * const blob = await fs.readBlob('/media/clip.mp4');
+     * video.src = URL.createObjectURL(blob);
      * ```
      */
-    async createIndex(entries: [string, string | Uint8Array | Blob][]): Promise<void> {
+    async readBlob(path: string): Promise<Blob> {
         await this.mount();
 
         try {
-            for (const [path, data] of entries) {
-                const normalizedPath = normalizePath(path);
+            const fileHandle = await this.getFileHandle(path, false);
 
-                let fileData: Uint8Array;
+            return await fileHandle.getFile();
+        }
+        catch (error: any) {
+            if (error instanceof OPFSError) {
+                throw error;
+            }
 
-                if (data instanceof Blob) {
-                    fileData = await convertBlobToUint8Array(data);
-                }
-                else if (typeof data === 'string') {
-                    // Convert string to Uint8Array using UTF-8 encoding
-                    fileData = new TextEncoder().encode(data);
-                }
-                else {
-                    fileData = data;
-                }
+            throw mapDomError(error, { path, isDirectory: error?.name === 'TypeMismatchError' });
+        }
+    }
 
-                await this.writeFile(normalizedPath, fileData);
+    /**
+     * Bulk-import files from `[path, data]` entries (strings, bytes, Blobs, or Files).
+     * Each entry is written via {@link writeStream} so large Blobs/Files are not
+     * fully buffered in memory.
+     *
+     * Accepts an array of tuples, a `Map`, or any iterable of `[path, data]` pairs.
+     *
+     * @param entries - Files to write
+     * @param onProgress - Per-chunk progress with path, index, and byte counts
+     * @returns Written paths, count, and total bytes
+     * @throws {OPFSError} If a write fails
+     *
+     * @example
+     * ```typescript
+     * const result = await fs.importFiles([
+     *   ['/config.json', JSON.stringify({ theme: 'dark' })],
+     *   ['/data/binary.dat', new Uint8Array([1, 2, 3, 4])],
+     *   ['/upload.txt', fileFromInput],
+     * ], (p) => console.log(`${p.path}: ${p.bytesWritten}/${p.bytesTotal}`));
+     *
+     * console.log(result.count, result.bytesWritten, result.paths);
+     * ```
+     */
+    async importFiles(
+        entries: ImportFilesEntries,
+        onProgress?: (progress: ImportFilesProgress) => unknown
+    ): Promise<ImportFilesResult> {
+        await this.mount();
+
+        const list = [...entries].map(([path, data]) => [normalizePath(path), data] as [string, ImportFileData]);
+        const count = list.length;
+        const paths = list.map(([path]) => path);
+        const totalBytes = list.reduce((sum, [, data]) => sum + importEntryByteLength(data), 0);
+        let totalBytesWritten = 0;
+
+        try {
+            for (let index = 0; index < count; index++) {
+                const [path, data] = list[index]!;
+                const { stream, size: bytesTotal } = toImportStream(data);
+                const base = totalBytesWritten;
+
+                const written = await this.writeStream(
+                    path,
+                    stream,
+                    onProgress
+                        ? bytesWritten => onProgress({
+                            path,
+                            index,
+                            count,
+                            bytesWritten,
+                            bytesTotal,
+                            totalBytesWritten: base + bytesWritten,
+                            totalBytes,
+                        })
+                        : undefined
+                );
+
+                totalBytesWritten += written;
             }
+
+            return {
+                paths,
+                count,
+                bytesWritten: totalBytesWritten,
+            };
         }
         catch (error) {
             if (error instanceof OPFSError) {
@@ -937,6 +1053,14 @@ export abstract class BaseOPFS {
         }
     }
 
+    /**
+     * @deprecated Use {@link importFiles} instead.
+     */
+    async createIndex(entries: ImportFilesEntries): Promise<void> {
+        warnCreateIndexDeprecated();
+        await this.importFiles(entries);
+    }
+
     /**
      * Dispose of resources and clean up the file system instance
      */
@@ -949,3 +1073,44 @@ export abstract class BaseOPFS {
         this.watchers.clear();
     }
 }
+
+function importEntryByteLength(data: ImportFileData): number {
+    if (typeof data === 'string') {
+        return new TextEncoder().encode(data).byteLength;
+    }
+
+    if (data instanceof Blob) {
+        return data.size;
+    }
+
+    return data.byteLength;
+}
+
+function toImportStream(data: ImportFileData): { stream: ReadableStream<Uint8Array>; size: number } {
+    if (data instanceof Blob) {
+        return { stream: data.stream(), size: data.size };
+    }
+
+    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+
+    return {
+        size: bytes.byteLength,
+        stream: new ReadableStream({
+            start(controller) {
+                controller.enqueue(bytes);
+                controller.close();
+            },
+        }),
+    };
+}
+
+let createIndexWarned = false;
+
+function warnCreateIndexDeprecated(): void {
+    if (createIndexWarned) {
+        return;
+    }
+
+    createIndexWarned = true;
+    console.warn('[opfs-worker] createIndex() is deprecated; use importFiles() instead');
+}

package/src/core/OPFSAsync.ts

@@ -3,7 +3,6 @@ import { transfer } from 'comlink';
 import { BaseOPFS } from './BaseOPFS';
 import { WatchEventType } from '../types';
 import { OPFSError, OperationNotSupportedError, mapDomError } from '../utils/errors';
-import { withLock } from '../utils/helpers';
 
 import type { FileOpenOptions, FileStat } from '../types';
 
@@ -37,7 +36,7 @@ export class OPFSAsync extends BaseOPFS {
         await this.mount();
 
         try {
-            return await withLock(path, async() => {
+            return await this.withPathLock(path, async() => {
                 const fileHandle = await this.getFileHandle(path, false);
                 const file = await fileHandle.getFile();
                 const buffer = new Uint8Array(await file.arrayBuffer());
@@ -63,7 +62,7 @@ export class OPFSAsync extends BaseOPFS {
         const buffer = data instanceof Uint8Array ? data : new Uint8Array(data);
 
         try {
-            await withLock(path, async() => {
+            await this.withPathLock(path, async() => {
                 const existed = await this.exists(path);
                 const fileHandle = await this.getFileHandle(path, true);
 
@@ -92,7 +91,7 @@ export class OPFSAsync extends BaseOPFS {
         const buffer = data instanceof Uint8Array ? data : new Uint8Array(data);
 
         try {
-            await withLock(path, async() => {
+            await this.withPathLock(path, async() => {
                 const fileHandle = await this.getFileHandle(path, true);
                 const { size } = await fileHandle.getFile();
 
@@ -122,7 +121,7 @@ export class OPFSAsync extends BaseOPFS {
         await this.mount();
 
         try {
-            return await withLock(path, async() => {
+            return await this.withPathLock(path, async() => {
                 const existed = await this.exists(path);
                 const fileHandle = await this.getFileHandle(path, true);
                 const reader = stream.getReader();

package/src/core/OPFSSync.ts

@@ -16,8 +16,7 @@ import {
     normalizePath,
     resolvePath,
     safeCloseSyncHandle,
-    validateReadWriteArgs,
-    withLock
+    validateReadWriteArgs
 } from '../utils/helpers';
 
 import type { FileOpenOptions, FileStat, OPFSOptions } from '../types';
@@ -77,7 +76,7 @@ export class OPFSSync extends BaseOPFS {
         await this.mount();
 
         try {
-            return await withLock(path, async() => {
+            return await this.withPathLock(path, async() => {
                 const fd = await this.open(path);
 
                 try {
@@ -112,7 +111,7 @@ export class OPFSSync extends BaseOPFS {
 
         const buffer = data instanceof Uint8Array ? data : new Uint8Array(data);
 
-        await withLock(path, async() => {
+        await this.withPathLock(path, async() => {
             const existed = await this.exists(path);
             const fd = await this.open(path, { create: true, truncate: true });
 
@@ -136,7 +135,7 @@ export class OPFSSync extends BaseOPFS {
 
         const buffer = data instanceof Uint8Array ? data : new Uint8Array(data);
 
-        await withLock(path, async() => {
+        await this.withPathLock(path, async() => {
             const fd = await this.open(path, { create: true });
 
             try {
@@ -160,7 +159,7 @@ export class OPFSSync extends BaseOPFS {
     ): Promise<number> {
         await this.mount();
 
-        return withLock(path, async() => {
+        return this.withPathLock(path, async() => {
             const existed = await this.exists(path);
             const fd = await this.open(path, { create: true, truncate: true });
             const reader = stream.getReader();
@@ -224,7 +223,7 @@ export class OPFSSync extends BaseOPFS {
         try {
             // Use lock for atomic operations when creating files
             if (create && exclusive) {
-                return await withLock(normalizedPath, async() => {
+                return await this.withPathLock(normalizedPath, async() => {
                     const exists = await this.exists(normalizedPath);
 
                     if (exists) {

package/src/facade/OPFSFacade.ts

@@ -8,6 +8,9 @@ import type {
     Encoding,
     FileOpenOptions,
     FileStat,
+    ImportFileData,
+    ImportFilesProgress,
+    ImportFilesResult,
     OPFSApi,
     OPFSOptions,
     PathLike,
@@ -28,6 +31,17 @@ function normalizePath(path: PathLike): string {
     return path;
 }
 
+let createIndexWarned = false;
+
+function warnCreateIndexDeprecated(): void {
+    if (createIndexWarned) {
+        return;
+    }
+
+    createIndexWarned = true;
+    console.warn('[opfs-worker] createIndex() is deprecated; use importFiles() instead');
+}
+
 /** Backend the facade talks to: an fs implementation plus its cleanup. */
 export interface OPFSBackend {
     fs: OPFSApi;
@@ -442,12 +456,45 @@ export class OPFSFacade {
     }
 
     /**
-     * Synchronize the file system with external data
+     * Read a file as a lazy, disk-backed `Blob` without copying the data to memory.
+     *
+     * Ideal for `URL.createObjectURL()`: the browser streams `<video>` / `<audio>`
+     * on demand instead of loading the whole file first.
      */
-    async createIndex(entries: [PathLike, string | Uint8Array | Blob][]): Promise<void> {
-        const normalizedEntries = entries.map(([path, data]) => [normalizePath(path), data] as [string, string | Uint8Array | Blob]);
+    async readBlob(path: PathLike): Promise<Blob> {
+        return this.#fs.readBlob(normalizePath(path));
+    }
 
-        return this.#fs.createIndex(normalizedEntries);
+    /**
+     * Bulk-import files from `[path, data]` entries (strings, bytes, Blobs, or Files).
+     * Each entry is streamed via {@link importStream} / `writeStream` so large
+     * Blobs/Files are not fully buffered in memory.
+     *
+     * Accepts an array of tuples, a `Map`, or any iterable of `[path, data]` pairs.
+     * Returns written paths, count, and total bytes.
+     */
+    async importFiles(
+        entries: Iterable<[PathLike, ImportFileData]> | Map<string, ImportFileData>,
+        options?: { onProgress?: (progress: ImportFilesProgress) => void }
+    ): Promise<ImportFilesResult> {
+        const normalizedEntries = [...entries].map(([path, data]) => [
+            normalizePath(path),
+            data,
+        ] as [string, ImportFileData]);
+
+        const onProgress = options?.onProgress
+            ? proxy((progress: ImportFilesProgress) => options.onProgress!(progress))
+            : undefined;
+
+        return this.#fs.importFiles(normalizedEntries, onProgress);
+    }
+
+    /**
+     * @deprecated Use {@link importFiles} instead.
+     */
+    async createIndex(entries: Iterable<[PathLike, ImportFileData]> | Map<string, ImportFileData>): Promise<void> {
+        warnCreateIndexDeprecated();
+        await this.importFiles(entries);
     }
 
     /**

package/src/facade/createOPFSDedicated.ts

@@ -10,8 +10,10 @@ import type { DedicatedWorkerOptions } from '../worker/createDedicatedWorker';
  * Prefer importing from `opfs-worker/sync` when you only need the worker backend
  * (avoids pulling `OPFSAsync` into the graph). Importing from `opfs-worker` works too.
  *
- * By default uses an inlined worker. Pass `url` / `worker` to load
- * `opfs-worker/dedicated.worker.js` instead (see {@link DedicatedWorkerOptions}).
+ * By default uses an inlined worker. Calls with the same `root` (and same `url`)
+ * reuse one Worker on this page; different roots get different Workers.
+ * Pass `url` / `worker` to load `opfs-worker/dedicated.worker.js` instead
+ * (see {@link DedicatedWorkerOptions}).
  *
  * Need the raw bytes API or the Worker instance? Use `fs.backend` / `fs.worker`.
  * For the workerless async backend, use {@link createOPFSAsync}.

package/src/index.sync.ts

@@ -9,4 +9,6 @@ export { OPFSFacade } from './facade/OPFSFacade';
 export type { OPFSBackend } from './facade/OPFSFacade';
 
 export { createOPFSDedicated } from './facade/createOPFSDedicated';
+/** Short alias for {@link createOPFSDedicated} */
+export { createOPFSDedicated as createOPFS } from './facade/createOPFSDedicated';
 export type { DedicatedWorkerOptions } from './worker/createDedicatedWorker';

package/src/index.ts

@@ -7,6 +7,7 @@ export {
     BaseOPFS,
     OPFSFacade,
     OPFSSync,
+    createOPFS,
     createOPFSDedicated,
 } from './index.sync';
 
@@ -28,11 +29,6 @@ export type {
     SharedWorkerOptions,
 } from './index.sharedworker';
 
-/**
- * Kept as a short alias for a default Sync backend
- */
-export { createOPFSDedicated as createOPFS } from './index.sync';
-
 /**
  * @deprecated Use {@link createOPFSDedicated}. Kept for 1.x → 2.x migration.
  */

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { BaseOPFS } from './core/BaseOPFS';
 import type { OPFSSync } from './core/OPFSSync';
 
 /**
@@ -58,10 +59,11 @@ export interface WatchEvent {
 export type { OPFSSync };
 
 /**
- * Promise-based fs API surface shared by all backends: a Comlink proxy to
- * `OPFSSync` in a worker, or an in-process `OPFSAsync` instance.
+ * Public bytes API shared by all backends (`OPFSSync`, `OPFSAsync`, or a
+ * Comlink proxy to one of them). Declared on {@link BaseOPFS}; subclasses
+ * implement the abstract I/O and FD methods.
  */
-export type OPFSApi = { [K in keyof OPFSSync]: OPFSSync[K] };
+export type OPFSApi = Pick<BaseOPFS, keyof BaseOPFS>;
 
 export interface OPFSOptions {
     /** Root path for the file system (default: '/') */
@@ -76,6 +78,43 @@ export interface OPFSOptions {
     broadcastChannel?: string | BroadcastChannel | null;
 }
 
+/** Payload accepted by {@link importFiles} for a single entry. */
+export type ImportFileData = string | Uint8Array | Blob;
+
+/**
+ * Entries for {@link importFiles}: an array of `[path, data]` tuples, a `Map`,
+ * or any iterable that yields the same pairs.
+ */
+export type ImportFilesEntries = Iterable<[string, ImportFileData]> | Map<string, ImportFileData>;
+
+/** Progress event fired while {@link importFiles} writes entries. */
+export interface ImportFilesProgress {
+    /** Path of the file currently being written */
+    path: string;
+    /** 0-based index of the current file */
+    index: number;
+    /** Total number of entries in this import */
+    count: number;
+    /** Bytes written for the current file so far */
+    bytesWritten: number;
+    /** Size of the current file in bytes */
+    bytesTotal: number;
+    /** Bytes written across all files so far */
+    totalBytesWritten: number;
+    /** Sum of all entry sizes in bytes */
+    totalBytes: number;
+}
+
+/** Result of a finished {@link importFiles} call. */
+export interface ImportFilesResult {
+    /** Paths written, in import order */
+    paths: string[];
+    /** Number of files imported (`paths.length`) */
+    count: number;
+    /** Total bytes written across all files */
+    bytesWritten: number;
+}
+
 export interface RenameOptions {
     /** Whether to overwrite existing files (default: false) */
     overwrite?: boolean;

package/src/utils/helpers.ts

@@ -21,22 +21,48 @@ export function checkOPFSSupport(): void {
     }
 }
 
+/**
+ * Join a mount `root` with an API path into an absolute OPFS path.
+ *
+ * Lock keys and cross-instance coordination use this so `/x.txt` under
+ * `root: '/app'` and `/app/x.txt` under `root: '/'` resolve to the same file.
+ */
+export function absoluteOpfsPath(root: string, path: string): string {
+    const r = normalizePath(root || '/');
+    const p = normalizePath(resolvePath(path));
+
+    if (r === '/') {
+        return p;
+    }
+
+    if (p === '/') {
+        return r;
+    }
+
+    return `${ r.replace(/\/$/, '') }${ p }`;
+}
+
 /**
  * Run a callback while holding an exclusive lock on a path
  *
  * Locks are always exclusive: OPFS permits a single sync access handle per file,
- * so readers can't share access either.
+ * so readers can't share access either. The lock key is the absolute OPFS path
+ * (`root` + API `path`) so different mounts of the same file serialize correctly.
  *
- * @param path - The path to lock
+ * @param path - The API path to lock (relative to `root`)
  * @param fn - The callback to run while holding the lock
+ * @param root - Mount root (default: `/`)
  * @returns The value returned by the callback
  */
 export async function withLock<T>(
     path: string,
-    fn: () => Promise<T>
+    fn: () => Promise<T>,
+    root: string = '/'
 ): Promise<T> {
     if (typeof navigator !== 'undefined' && navigator.locks?.request) {
-        return navigator.locks.request(`opfs:${ path.replace(/\/+/g, '/') }`, { mode: 'exclusive' }, fn);
+        const key = absoluteOpfsPath(root, path).replace(/\/+/g, '/');
+
+        return navigator.locks.request(`opfs:${ key }`, { mode: 'exclusive' }, fn);
     }
 
     return fn();
@@ -343,7 +369,7 @@ export async function convertBlobToUint8Array(blob: Blob): Promise<Uint8Array> {
 export async function removeEntry(
     parentHandle: FileSystemDirectoryHandle,
     path: string,
-    options: { recursive?: boolean; force?: boolean; useTrash?: boolean } = {}
+    options: { recursive?: boolean; force?: boolean; useTrash?: boolean; root?: string } = {}
 ): Promise<void> {
     const name = basename(path);
 
@@ -367,7 +393,7 @@ export async function removeEntry(
                 isDirectory,
             });
         }
-    });
+    }, options.root ?? '/');
 }
 
 /**