@componentor/fs 2.0.6 → 2.0.8

package/dist/index.d.cts

@@ -315,6 +315,28 @@ declare class OPFSFileSystem {
      * Use between major operations to ensure clean state.
      */
     purgeSync(): void;
+    /**
+     * Enable or disable debug tracing for handle operations.
+     * When enabled, logs handle cache hits, acquisitions, releases, and mode information.
+     * @param enabled - Whether to enable debug tracing
+     * @returns Debug state information including unsafeModeSupported and cache size
+     */
+    setDebugSync(enabled: boolean): {
+        debugTrace: boolean;
+        unsafeModeSupported: boolean;
+        cacheSize: number;
+    };
+    /**
+     * Enable or disable debug tracing for handle operations (async version).
+     * When enabled, logs handle cache hits, acquisitions, releases, and mode information.
+     * @param enabled - Whether to enable debug tracing
+     * @returns Debug state information including unsafeModeSupported and cache size
+     */
+    setDebug(enabled: boolean): Promise<{
+        debugTrace: boolean;
+        unsafeModeSupported: boolean;
+        cacheSize: number;
+    }>;
     accessSync(filePath: string, _mode?: number): void;
     openSync(filePath: string, flags?: string | number): number;
     closeSync(fd: number): void;

package/dist/index.d.ts

@@ -315,6 +315,28 @@ declare class OPFSFileSystem {
      * Use between major operations to ensure clean state.
      */
     purgeSync(): void;
+    /**
+     * Enable or disable debug tracing for handle operations.
+     * When enabled, logs handle cache hits, acquisitions, releases, and mode information.
+     * @param enabled - Whether to enable debug tracing
+     * @returns Debug state information including unsafeModeSupported and cache size
+     */
+    setDebugSync(enabled: boolean): {
+        debugTrace: boolean;
+        unsafeModeSupported: boolean;
+        cacheSize: number;
+    };
+    /**
+     * Enable or disable debug tracing for handle operations (async version).
+     * When enabled, logs handle cache hits, acquisitions, releases, and mode information.
+     * @param enabled - Whether to enable debug tracing
+     * @returns Debug state information including unsafeModeSupported and cache size
+     */
+    setDebug(enabled: boolean): Promise<{
+        debugTrace: boolean;
+        unsafeModeSupported: boolean;
+        cacheSize: number;
+    }>;
     accessSync(filePath: string, _mode?: number): void;
     openSync(filePath: string, flags?: string | number): number;
     closeSync(fd: number): void;

package/dist/index.js

@@ -426,57 +426,90 @@ let isReady = false;
 let cachedRoot = null;
 const dirCache = new Map();
 
-// Sync handle cache - MAJOR performance optimization
-// Handles auto-release after idle timeout to allow external tools to access files
+// Sync handle cache - MAJOR performance optimization (2-5x speedup)
+// Uses readwrite-unsafe mode when available (no exclusive lock, allows external access)
+// Falls back to readwrite with debounced release for older browsers
 const syncHandleCache = new Map();
-const syncHandleLastAccess = new Map();
 const MAX_HANDLES = 100;
-const HANDLE_IDLE_TIMEOUT = 2000;
-let idleCleanupTimer = null;
 
-function scheduleIdleCleanup() {
-  if (idleCleanupTimer) return;
-  idleCleanupTimer = setTimeout(() => {
-    idleCleanupTimer = null;
-    const now = Date.now();
-    for (const [p, lastAccess] of syncHandleLastAccess) {
-      if (now - lastAccess >= HANDLE_IDLE_TIMEOUT) {
-        const h = syncHandleCache.get(p);
-        if (h) { try { h.flush(); h.close(); } catch {} syncHandleCache.delete(p); }
-        syncHandleLastAccess.delete(p);
-      }
-    }
-    if (syncHandleCache.size > 0) scheduleIdleCleanup();
-  }, HANDLE_IDLE_TIMEOUT);
+// Track if readwrite-unsafe mode is supported (detected on first use)
+let unsafeModeSupported = null;
+
+// Debug tracing - set via 'setDebug' message
+let debugTrace = false;
+function trace(...args) {
+  if (debugTrace) console.log('[OPFS-T2]', ...args);
+}
+
+// Minimal timer for legacy mode only
+let releaseTimer = null;
+const LEGACY_RELEASE_DELAY = 100;
+
+function scheduleHandleRelease() {
+  if (unsafeModeSupported) return; // No release needed for readwrite-unsafe
+  if (releaseTimer) return; // Already scheduled
+  releaseTimer = setTimeout(() => {
+    releaseTimer = null;
+    const count = syncHandleCache.size;
+    for (const h of syncHandleCache.values()) {
+      try { h.flush(); h.close(); } catch {}
+    }
+    syncHandleCache.clear();
+    trace('Released ' + count + ' handles (legacy mode debounce)');
+  }, LEGACY_RELEASE_DELAY);
 }
 
 async function getSyncHandle(filePath, create) {
   const cached = syncHandleCache.get(filePath);
   if (cached) {
-    syncHandleLastAccess.set(filePath, Date.now());
+    trace('Handle cache HIT: ' + filePath);
     return cached;
   }
 
   // Evict oldest handles if cache is full
   if (syncHandleCache.size >= MAX_HANDLES) {
     const keys = Array.from(syncHandleCache.keys()).slice(0, 10);
+    trace('LRU evicting ' + keys.length + ' handles');
     for (const key of keys) {
       const h = syncHandleCache.get(key);
-      if (h) { try { h.close(); } catch {} syncHandleCache.delete(key); syncHandleLastAccess.delete(key); }
+      if (h) { try { h.close(); } catch {} syncHandleCache.delete(key); }
     }
   }
 
   const fh = await getFileHandle(filePath, create);
-  const access = await fh.createSyncAccessHandle();
+
+  // Try readwrite-unsafe mode first (no exclusive lock, Chrome 121+)
+  let access;
+  if (unsafeModeSupported === null) {
+    // First time - detect support
+    try {
+      access = await fh.createSyncAccessHandle({ mode: 'readwrite-unsafe' });
+      unsafeModeSupported = true;
+      trace('readwrite-unsafe mode SUPPORTED - handles won\\'t block');
+    } catch {
+      // Not supported, use default mode
+      access = await fh.createSyncAccessHandle();
+      unsafeModeSupported = false;
+      trace('readwrite-unsafe mode NOT supported - using legacy mode');
+    }
+  } else if (unsafeModeSupported) {
+    access = await fh.createSyncAccessHandle({ mode: 'readwrite-unsafe' });
+  } else {
+    access = await fh.createSyncAccessHandle();
+  }
+
   syncHandleCache.set(filePath, access);
-  syncHandleLastAccess.set(filePath, Date.now());
-  scheduleIdleCleanup();
+  trace('Handle ACQUIRED: ' + filePath + ' (cache size: ' + syncHandleCache.size + ')');
   return access;
 }
 
 function closeSyncHandle(filePath) {
   const h = syncHandleCache.get(filePath);
-  if (h) { try { h.close(); } catch {} syncHandleCache.delete(filePath); syncHandleLastAccess.delete(filePath); }
+  if (h) {
+    try { h.close(); } catch {}
+    syncHandleCache.delete(filePath);
+    trace('Handle RELEASED: ' + filePath);
+  }
 }
 
 function closeHandlesUnder(prefix) {
@@ -484,7 +517,6 @@ function closeHandlesUnder(prefix) {
     if (p === prefix || p.startsWith(prefix + '/')) {
       try { h.close(); } catch {}
       syncHandleCache.delete(p);
-      syncHandleLastAccess.delete(p);
     }
   }
 }
@@ -600,11 +632,10 @@ function handleReleaseHandle(filePath) {
 
 // Force release ALL file handles - use before HMR notifications
 function handleReleaseAllHandles() {
-  for (const [p, h] of syncHandleCache) {
+  for (const h of syncHandleCache.values()) {
     try { h.close(); } catch {}
   }
   syncHandleCache.clear();
-  syncHandleLastAccess.clear();
   return { success: true };
 }
 
@@ -614,7 +645,6 @@ async function handleWrite(filePath, payload) {
     const offset = payload.offset ?? 0;
     if (offset === 0) access.truncate(0);
     access.write(payload.data, { at: offset });
-    // Only flush if explicitly requested (default: true for safety)
     if (payload?.flush !== false) access.flush();
   }
   return { success: true };
@@ -803,8 +833,11 @@ function handleFlush() {
 }
 
 function handlePurge() {
-  // Flush and close all cached sync handles
-  for (const [, handle] of syncHandleCache) {
+  if (releaseTimer) {
+    clearTimeout(releaseTimer);
+    releaseTimer = null;
+  }
+  for (const handle of syncHandleCache.values()) {
     try { handle.flush(); handle.close(); } catch {}
   }
   syncHandleCache.clear();
@@ -833,6 +866,10 @@ async function processMessage(msg) {
     case 'purge': return handlePurge();
     case 'releaseHandle': return handleReleaseHandle(path);
     case 'releaseAllHandles': return handleReleaseAllHandles();
+    case 'setDebug':
+      debugTrace = !!payload?.enabled;
+      trace('Debug tracing ' + (debugTrace ? 'ENABLED' : 'DISABLED') + ', unsafeMode: ' + unsafeModeSupported);
+      return { success: true, debugTrace, unsafeModeSupported, cacheSize: syncHandleCache.size };
     default: throw new Error('Unknown operation: ' + type);
   }
 }
@@ -895,6 +932,9 @@ async function handleMessage(msg) {
     } else {
       self.postMessage({ id, error: errorCode, code: errorCode });
     }
+  } finally {
+    // Schedule handle release (debounced - waits 100ms after last operation)
+    scheduleHandleRelease();
   }
 }
 
@@ -1686,6 +1726,24 @@ var OPFSFileSystem = class _OPFSFileSystem {
     this.syncCall("purge", "/");
     this.statCache.clear();
   }
+  /**
+   * Enable or disable debug tracing for handle operations.
+   * When enabled, logs handle cache hits, acquisitions, releases, and mode information.
+   * @param enabled - Whether to enable debug tracing
+   * @returns Debug state information including unsafeModeSupported and cache size
+   */
+  setDebugSync(enabled) {
+    return this.syncCall("setDebug", "/", { enabled });
+  }
+  /**
+   * Enable or disable debug tracing for handle operations (async version).
+   * When enabled, logs handle cache hits, acquisitions, releases, and mode information.
+   * @param enabled - Whether to enable debug tracing
+   * @returns Debug state information including unsafeModeSupported and cache size
+   */
+  async setDebug(enabled) {
+    return this.asyncCall("setDebug", "/", { enabled });
+  }
   accessSync(filePath, _mode) {
     const exists = this.existsSync(filePath);
     if (!exists) {