@componentor/fs 2.0.6 → 2.0.8

package/README.md

@@ -446,20 +446,14 @@ Another tab or operation has the file open. The library uses `navigator.locks` t
 
 ## Changelog
 
-### v2.0.5 (2025)
-
-**Bug Fixes:**
-- Fixed idle timeout condition (`>` to `>=`) - handles now release at exactly 2s instead of ~4s
-
-### v2.0.4 (2025)
-
-**Bug Fixes:**
-- Handle idle timeout now works for both Tier 1 and Tier 2
-- Previously only Tier 1 kernel had idle release; Tier 2 kernel now also releases handles after 2s
-
-### v2.0.3 (2025)
-- Reduced handle idle timeout from 5s to 2s for faster external tool access
-- Added tests verifying handles are properly released after idle timeout
+### v2.0.7 (2025)
+
+**High-Performance Handle Caching with `readwrite-unsafe`:**
+- Uses `readwrite-unsafe` mode (Chrome 121+) - no exclusive locks
+- Zero per-operation overhead: cache lookup is a single Map.get()
+- Browser extensions can access files while handles are cached
+- LRU eviction when cache exceeds 100 handles
+- Falls back to 100ms debounced release on older browsers (handles block)
 
 ### v2.0.2 (2025)
 

package/dist/index.cjs

@@ -430,57 +430,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) {
@@ -488,7 +521,6 @@ function closeHandlesUnder(prefix) {
     if (p === prefix || p.startsWith(prefix + '/')) {
       try { h.close(); } catch {}
       syncHandleCache.delete(p);
-      syncHandleLastAccess.delete(p);
     }
   }
 }
@@ -604,11 +636,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 };
 }
 
@@ -618,7 +649,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 };
@@ -807,8 +837,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();
@@ -837,6 +870,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);
   }
 }
@@ -899,6 +936,9 @@ async function handleMessage(msg) {
     } else {
       self.postMessage({ id, error: errorCode, code: errorCode });
     }
+  } finally {
+    // Schedule handle release (debounced - waits 100ms after last operation)
+    scheduleHandleRelease();
   }
 }
 
@@ -1690,6 +1730,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) {