@componentor/fs 2.0.4 → 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

@@ -567,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) {
@@ -776,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);
@@ -789,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);
   }
 }
@@ -2029,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 ---
@@ -2354,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);
@@ -2395,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;
@@ -2448,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);
           }
         }
@@ -2455,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;
@@ -2463,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)) {