opfs-worker 2.1.1 → 2.1.2

package/src/core/BaseOPFS.ts

@@ -23,11 +23,13 @@ import {
     normalizePath,
     removeEntry,
     resolvePath,
-    splitPath
+    splitPath,
+    withLock
 } from '../utils/helpers';
 
 import type {
     DirentData,
+    FileOpenOptions,
     FileStat,
     ImportFileData,
     ImportFilesEntries,
@@ -43,8 +45,9 @@ import type {
 
 /**
  * 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 */
@@ -135,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>;
 
@@ -151,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.
@@ -682,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 });
     }

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/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: '/') */

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 ?? '/');
 }
 
 /**

package/src/worker/createDedicatedWorker.ts

@@ -1,6 +1,7 @@
 import { wrap } from 'comlink';
 
 import WorkerCtor from './dedicated.worker?worker&inline';
+import { normalizePath } from '../utils/helpers';
 
 import type { OPFSOptions, OPFSSync } from '../types';
 import type { Remote } from 'comlink';
@@ -17,7 +18,7 @@ export interface DedicatedWorkerOptions extends OPFSOptions {
      * prefer the self-contained file (strict CSP without `blob:`, or DIY hosting).
      */
     url?: string | URL;
-    /** Bring your own Worker instance (overrides `url`) */
+    /** Bring your own Worker instance (overrides `url`) — not pooled */
     worker?: Worker;
 }
 
@@ -26,10 +27,22 @@ export interface RawWorker {
     fs: RemoteOPFSSync;
     /** Underlying browser Worker */
     worker: Worker;
-    /** Calls worker `dispose()` then `terminate()` */
+    /** Drops this facade's port; terminates the Worker when the last user of this pool entry disposes */
     dispose: () => void;
 }
 
+interface PoolEntry {
+    worker: Worker;
+    refs: number;
+}
+
+/** Same root (+ same worker url) → one Worker per page. */
+const pool = new Map<string, PoolEntry>();
+
+function poolKey(root: string, url?: string | URL): string {
+    return `${ normalizePath(root) }\0${ url?.toString() ?? 'inline' }`;
+}
+
 /** A `BroadcastChannel` instance can't cross the wire — send its name instead. */
 function applyWorkerOptions(fs: Pick<RemoteOPFSSync, 'setOptions'>, options?: OPFSOptions): void {
     if (!options) {
@@ -43,29 +56,94 @@ function applyWorkerOptions(fs: Pick<RemoteOPFSSync, 'setOptions'>, options?: OP
     void fs.setOptions(options);
 }
 
+function connectProxy(worker: Worker): { fs: RemoteOPFSSync; port: MessagePort } {
+    const { port1, port2 } = new MessageChannel();
+
+    worker.postMessage({ type: 'opfs-connect', port: port2 }, [port2]);
+
+    return { fs: wrap<RemoteOPFSSync>(port1), port: port1 };
+}
+
 /**
- * Internal helper: spawn a dedicated worker and wrap `OPFSSync` with Comlink.
+ * Internal helper: spawn (or reuse) a dedicated worker and wrap `OPFSSync` with Comlink.
  * Prefer {@link createOPFSDedicated}; access the proxy / Worker via
  * `facade.backend` / `facade.worker`.
+ *
+ * Calls with the same `root` (and same `url`, if any) share one Worker on this page.
+ * Different roots get different Workers. Passing `worker` bypasses the pool.
+ *
+ * `setOptions` hits the shared instance — keep options consistent for the same root.
  */
 export function createDedicatedWorker(options: DedicatedWorkerOptions = {}): RawWorker {
     const { url, worker: providedWorker, ...fsOptions } = options;
+    const root = normalizePath(fsOptions.root ?? '/');
+
+    if (providedWorker) {
+        const { fs, port } = connectProxy(providedWorker);
+
+        applyWorkerOptions(fs, fsOptions);
+
+        return {
+            fs,
+            worker: providedWorker,
+            dispose() {
+                port.close();
+            },
+        };
+    }
 
-    const worker = providedWorker
-      ?? (url ? new Worker(url, { type: 'module' }) : new InlineWorker());
-    const fs = wrap<RemoteOPFSSync>(worker);
+    const key = poolKey(root, url);
+    let entry = pool.get(key);
+
+    if (!entry) {
+        entry = {
+            worker: url ? new Worker(url, { type: 'module' }) : new InlineWorker(),
+            refs: 0,
+        };
+        pool.set(key, entry);
+    }
+
+    entry.refs += 1;
+
+    const { worker } = entry;
+    const { fs, port } = connectProxy(worker);
 
     applyWorkerOptions(fs, fsOptions);
 
+    let disposed = false;
+
     return {
         fs,
         worker,
         dispose() {
+            if (disposed) {
+                return;
+            }
+
+            disposed = true;
+
             void (async() => {
+                const current = pool.get(key);
+                const isLast = !!current && current.worker === worker && current.refs <= 1;
+
                 try {
-                    await fs.dispose();
+                    // Only the last facade may dispose the shared OPFSSync backend
+                    if (isLast) {
+                        await fs.dispose();
+                    }
                 }
                 finally {
+                    port.close();
+                }
+
+                if (!current || current.worker !== worker) {
+                    return;
+                }
+
+                current.refs -= 1;
+
+                if (current.refs <= 0) {
+                    pool.delete(key);
                     worker.terminate();
                 }
             })();

package/src/worker/dedicated.worker.ts

@@ -9,5 +9,16 @@ import { OPFSSync } from '../core/OPFSSync';
  * - Inlined into `createOPFSDedicated` via `?worker&inline` (default path)
  * - Self-contained `dist/dedicated.worker.js` → `opfs-worker/dedicated.worker.js`
  *   for DIY `new Worker(url, { type: 'module' })` + Comlink wrap
+ *
+ * Also accepts transferred MessagePorts (`type: 'opfs-connect'`) so one
+ * OPFSSync instance can serve multiple facades on the same page.
  */
-expose(new OPFSSync());
+const fs = new OPFSSync();
+
+expose(fs);
+
+addEventListener('message', (event: MessageEvent) => {
+    if (event.data?.type === 'opfs-connect' && event.data.port instanceof MessagePort) {
+        expose(fs, event.data.port);
+    }
+});