@componentor/fs 2.0.4 → 2.0.5

package/README.md

@@ -446,11 +446,13 @@ Another tab or operation has the file open. The library uses `navigator.locks` t
 
 ## Changelog
 
-### v2.0.3 (2025)
+### 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
 

package/dist/index.cjs

@@ -571,6 +571,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) {
@@ -780,6 +821,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);
@@ -793,6 +835,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);
   }
 }
@@ -2033,6 +2077,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 ---
@@ -2358,8 +2418,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);
@@ -2399,26 +2460,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;
@@ -2452,6 +2525,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);
           }
         }
@@ -2459,6 +2533,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;
@@ -2467,6 +2542,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)) {