@componentor/fs 2.0.2 → 2.0.5

package/dist/index.d.cts

@@ -373,6 +373,18 @@ declare class OPFSFileSystem {
      * Async purge - clears all kernel caches
      */
     purge(): Promise<void>;
+    /**
+     * Release all cached file handles.
+     * Call this before expecting external tools (OPFS Explorer, browser console, etc.)
+     * to modify files. This allows external access without waiting for the idle timeout.
+     * Unlike purge(), this only releases file handles without clearing directory caches.
+     */
+    releaseAllHandles(): Promise<void>;
+    /**
+     * Release a specific file's handle.
+     * Use this when you know a specific file needs to be externally modified.
+     */
+    releaseHandle(filePath: string): Promise<void>;
     constants: {
         readonly F_OK: 0;
         readonly R_OK: 4;

package/dist/index.d.ts

@@ -373,6 +373,18 @@ declare class OPFSFileSystem {
      * Async purge - clears all kernel caches
      */
     purge(): Promise<void>;
+    /**
+     * Release all cached file handles.
+     * Call this before expecting external tools (OPFS Explorer, browser console, etc.)
+     * to modify files. This allows external access without waiting for the idle timeout.
+     * Unlike purge(), this only releases file handles without clearing directory caches.
+     */
+    releaseAllHandles(): Promise<void>;
+    /**
+     * Release a specific file's handle.
+     * Use this when you know a specific file needs to be externally modified.
+     */
+    releaseHandle(filePath: string): Promise<void>;
     constants: {
         readonly F_OK: 0;
         readonly R_OK: 4;

package/dist/index.js

@@ -427,31 +427,56 @@ 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
 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);
+}
 
 async function getSyncHandle(filePath, create) {
   const cached = syncHandleCache.get(filePath);
-  if (cached) return cached;
+  if (cached) {
+    syncHandleLastAccess.set(filePath, Date.now());
+    return cached;
+  }
 
   // Evict oldest handles if cache is full
   if (syncHandleCache.size >= MAX_HANDLES) {
     const keys = Array.from(syncHandleCache.keys()).slice(0, 10);
     for (const key of keys) {
       const h = syncHandleCache.get(key);
-      if (h) { try { h.close(); } catch {} syncHandleCache.delete(key); }
+      if (h) { try { h.close(); } catch {} syncHandleCache.delete(key); syncHandleLastAccess.delete(key); }
     }
   }
 
   const fh = await getFileHandle(filePath, create);
   const access = await fh.createSyncAccessHandle();
   syncHandleCache.set(filePath, access);
+  syncHandleLastAccess.set(filePath, Date.now());
+  scheduleIdleCleanup();
   return access;
 }
 
 function closeSyncHandle(filePath) {
   const h = syncHandleCache.get(filePath);
-  if (h) { try { h.close(); } catch {} syncHandleCache.delete(filePath); }
+  if (h) { try { h.close(); } catch {} syncHandleCache.delete(filePath); syncHandleLastAccess.delete(filePath); }
 }
 
 function closeHandlesUnder(prefix) {
@@ -459,6 +484,7 @@ function closeHandlesUnder(prefix) {
     if (p === prefix || p.startsWith(prefix + '/')) {
       try { h.close(); } catch {}
       syncHandleCache.delete(p);
+      syncHandleLastAccess.delete(p);
     }
   }
 }
@@ -541,6 +567,47 @@ async function handleRead(filePath, payload) {
   return { data: buf.slice(0, bytesRead) };
 }
 
+// Non-blocking read using getFile() - does NOT lock the file
+// Use this for HMR scenarios where external tools need to modify files
+async function handleReadAsync(filePath, payload) {
+  const parts = parsePath(filePath);
+  const fileName = parts.pop();
+  if (!fileName) throw new Error('Invalid file path');
+  const dir = parts.length > 0 ? await getDirectoryHandle(parts, false) : await getRoot();
+  const fh = await dir.getFileHandle(fileName);
+  const file = await fh.getFile();
+
+  const offset = payload?.offset || 0;
+  const len = payload?.len || (file.size - offset);
+
+  if (offset === 0 && len === file.size) {
+    // Fast path: read entire file
+    const buf = new Uint8Array(await file.arrayBuffer());
+    return { data: buf };
+  }
+
+  // Partial read using slice
+  const slice = file.slice(offset, offset + len);
+  const buf = new Uint8Array(await slice.arrayBuffer());
+  return { data: buf };
+}
+
+// Force release a file handle - allows external tools to modify the file
+function handleReleaseHandle(filePath) {
+  closeSyncHandle(filePath);
+  return { success: true };
+}
+
+// Force release ALL file handles - use before HMR notifications
+function handleReleaseAllHandles() {
+  for (const [p, h] of syncHandleCache) {
+    try { h.close(); } catch {}
+  }
+  syncHandleCache.clear();
+  syncHandleLastAccess.clear();
+  return { success: true };
+}
+
 async function handleWrite(filePath, payload) {
   const access = await getSyncHandle(filePath, true);
   if (payload?.data) {
@@ -750,6 +817,7 @@ async function processMessage(msg) {
   const { type, path, payload } = msg;
   switch (type) {
     case 'read': return handleRead(path, payload);
+    case 'readAsync': return handleReadAsync(path, payload);
     case 'write': return handleWrite(path, payload);
     case 'append': return handleAppend(path, payload);
     case 'truncate': return handleTruncate(path, payload);
@@ -763,6 +831,8 @@ async function processMessage(msg) {
     case 'copy': return handleCopy(path, payload);
     case 'flush': return handleFlush();
     case 'purge': return handlePurge();
+    case 'releaseHandle': return handleReleaseHandle(path);
+    case 'releaseAllHandles': return handleReleaseAllHandles();
     default: throw new Error('Unknown operation: ' + type);
   }
 }
@@ -2003,6 +2073,22 @@ var OPFSFileSystem = class _OPFSFileSystem {
     await this.fastCall("purge", "/");
     this.statCache.clear();
   }
+  /**
+   * Release all cached file handles.
+   * Call this before expecting external tools (OPFS Explorer, browser console, etc.)
+   * to modify files. This allows external access without waiting for the idle timeout.
+   * Unlike purge(), this only releases file handles without clearing directory caches.
+   */
+  async releaseAllHandles() {
+    await this.fastCall("releaseAllHandles", "/");
+  }
+  /**
+   * Release a specific file's handle.
+   * Use this when you know a specific file needs to be externally modified.
+   */
+  async releaseHandle(filePath) {
+    await this.fastCall("releaseHandle", filePath);
+  }
   // Constants
   constants = constants;
   // --- FileHandle Implementation ---
@@ -2328,8 +2414,9 @@ var OPFSFileSystem = class _OPFSFileSystem {
     const self2 = this;
     let observer = null;
     let closed = false;
-    const callback = (records) => {
+    const callback = async (records) => {
       if (closed) return;
+      await self2.releaseAllHandles();
       for (const record of records) {
         if (record.type === "errored" || record.type === "unknown") continue;
         const filename = record.relativePathComponents.length > 0 ? record.relativePathComponents[record.relativePathComponents.length - 1] : basename(absPath);
@@ -2369,26 +2456,38 @@ var OPFSFileSystem = class _OPFSFileSystem {
           const entries = await this.promises.readdir(absPath);
           const currentEntries = new Set(entries);
           if (lastEntries !== null) {
+            let hasChanges = false;
+            const added = [];
+            const removed = [];
             for (const entry of currentEntries) {
               if (!lastEntries.has(entry)) {
-                cb?.("rename", entry);
+                added.push(entry);
+                hasChanges = true;
               }
             }
             for (const entry of lastEntries) {
               if (!currentEntries.has(entry)) {
-                cb?.("rename", entry);
+                removed.push(entry);
+                hasChanges = true;
               }
             }
+            if (hasChanges) {
+              await this.releaseAllHandles();
+              for (const entry of added) cb?.("rename", entry);
+              for (const entry of removed) cb?.("rename", entry);
+            }
           }
           lastEntries = currentEntries;
         } else {
           if (lastMtimeMs !== null && stat.mtimeMs !== lastMtimeMs) {
+            await this.releaseAllHandles();
             cb?.("change", basename(absPath));
           }
           lastMtimeMs = stat.mtimeMs;
         }
       } catch {
         if (lastMtimeMs !== null || lastEntries !== null) {
+          await this.releaseAllHandles();
           cb?.("rename", basename(absPath));
           lastMtimeMs = null;
           lastEntries = null;
@@ -2422,6 +2521,7 @@ var OPFSFileSystem = class _OPFSFileSystem {
         const stat = await this.promises.stat(absPath);
         if (lastStat !== null) {
           if (stat.mtimeMs !== lastStat.mtimeMs || stat.size !== lastStat.size) {
+            await this.releaseAllHandles();
             cb?.(stat, lastStat);
           }
         }
@@ -2429,6 +2529,7 @@ var OPFSFileSystem = class _OPFSFileSystem {
       } catch {
         const emptyStat = createStats({ type: "file", size: 0, mtimeMs: 0, mode: 0 });
         if (lastStat !== null) {
+          await this.releaseAllHandles();
           cb?.(emptyStat, lastStat);
         }
         lastStat = emptyStat;
@@ -2437,6 +2538,7 @@ var OPFSFileSystem = class _OPFSFileSystem {
     if (_OPFSFileSystem.hasNativeObserver && cb) {
       const self2 = this;
       const observerCallback = async () => {
+        await self2.releaseAllHandles();
         try {
           const stat = await self2.promises.stat(absPath);
           if (lastStat !== null && (stat.mtimeMs !== lastStat.mtimeMs || stat.size !== lastStat.size)) {