@componentor/fs 3.0.2 → 3.0.3

package/README.md

@@ -311,17 +311,23 @@ await writer.close();
 ### Watch API
 
 ```typescript
-// Watch for changes
-const watcher = fs.watch('/dir', { recursive: true }, (eventType, filename) => {
-  console.log(eventType, filename); // 'change' 'file.txt'
+// Watch for changes (supports recursive + AbortSignal)
+const ac = new AbortController();
+const watcher = fs.watch('/dir', { recursive: true, signal: ac.signal }, (eventType, filename) => {
+  console.log(eventType, filename); // 'rename' 'newfile.txt' or 'change' 'file.txt'
 });
-watcher.close();
+watcher.close(); // or ac.abort()
 
-// Watch specific file with polling
+// Watch specific file with stat polling
 fs.watchFile('/file.txt', { interval: 1000 }, (curr, prev) => {
   console.log('File changed:', curr.mtimeMs !== prev.mtimeMs);
 });
 fs.unwatchFile('/file.txt');
+
+// Async iterable (promises API)
+for await (const event of fs.promises.watch('/dir', { recursive: true })) {
+  console.log(event.eventType, event.filename);
+}
 ```
 
 ### Path Utilities
@@ -412,23 +418,23 @@ await git.commit({
 │               sync-relay Worker (Leader)                         │
 │  ┌────────────────────────────────────────────────────────────┐  │
 │  │                     VFS Engine                             │  │
-│  │  ┌──────────────────┐  ┌─────────────┐  ┌──────────────┐  │  │
-│  │  │  VFS Binary File  │  │  Inode/Path │  │  Block Data  │  │  │
-│  │  │  (.vfs.bin OPFS)  │  │    Table    │  │   Region     │  │  │
-│  │  └──────────────────┘  └─────────────┘  └──────────────┘  │  │
+│  │  ┌──────────────────┐  ┌─────────────┐  ┌──────────────┐   │  │
+│  │  │  VFS Binary File  │  │  Inode/Path │  │  Block Data │   │  │
+│  │  │  (.vfs.bin OPFS)  │  │    Table    │  │   Region    │   │  │
+│  │  └──────────────────┘  └─────────────┘  └──────────────┘   │  │
 │  └────────────────────────────────────────────────────────────┘  │
 │                            │                                     │
-│                    notifyOPFSSync()                               │
-│                     (fire & forget)                               │
+│                    notifyOPFSSync()                              │
+│                     (fire & forget)                              │
 └────────────────────────────┼─────────────────────────────────────┘
                              │
                              ▼
 ┌──────────────────────────────────────────────────────────────────┐
-│                    opfs-sync Worker                               │
+│                    opfs-sync Worker                              │
 │  ┌────────────────────┐  ┌────────────────────────────────────┐  │
-│  │  VFS → OPFS Mirror │  │  FileSystemObserver (OPFS → VFS)  │  │
-│  │  (queue + echo     │  │  External changes detected and    │  │
-│  │   suppression)     │  │  synced back to VFS engine        │  │
+│  │  VFS → OPFS Mirror │  │  FileSystemObserver (OPFS → VFS)   │  │
+│  │  (queue + echo     │  │  External changes detected and     │  │
+│  │   suppression)     │  │  synced back to VFS engine         │  │
 │  └────────────────────┘  └────────────────────────────────────┘  │
 └──────────────────────────────────────────────────────────────────┘
 
@@ -475,6 +481,19 @@ Make sure `opfsSync` is enabled (it's `true` by default). Files are mirrored to
 
 ## Changelog
 
+### v3.0.3 (2026)
+
+**Features:**
+- Implement `fs.watch()`, `fs.watchFile()`, `fs.unwatchFile()`, and `promises.watch()` as Node.js-compatible polyfills
+- Watch events propagate across all tabs via `BroadcastChannel`
+- `fs.watch()` supports `recursive` option and `AbortSignal` for cleanup
+- `fs.watchFile()` supports stat-based polling with configurable `interval` (default 5007ms per Node.js)
+- `promises.watch()` returns an async iterable of watch events
+
+**Internal:**
+- Leader broadcasts `{ eventType, path }` on every successful VFS mutation (no new opcodes or protocol changes)
+- Mutation tracking now runs unconditionally (previously gated on `opfsSync`)
+
 ### v3.0.2 (2026)
 
 **Bug Fixes:**
@@ -529,7 +548,7 @@ git clone https://github.com/componentor/fs
 cd fs
 npm install
 npm run build       # Build the library
-npm test            # Run unit tests (77 tests)
+npm test            # Run unit tests (84 tests)
 npm run benchmark:open  # Run benchmarks in browser
 ```
 

package/dist/index.js

@@ -939,33 +939,233 @@ function format(obj) {
 }
 
 // src/methods/watch.ts
-function watch(_filePath, _options, _listener) {
-  const interval = setInterval(() => {
-  }, 1e3);
+var watchers = /* @__PURE__ */ new Set();
+var fileWatchers = /* @__PURE__ */ new Map();
+var bc = null;
+var bcRefCount = 0;
+function ensureBc() {
+  if (bc) {
+    bcRefCount++;
+    return;
+  }
+  bc = new BroadcastChannel("vfs-watch");
+  bcRefCount = 1;
+  bc.onmessage = onBroadcast;
+}
+function releaseBc() {
+  if (--bcRefCount <= 0 && bc) {
+    bc.close();
+    bc = null;
+    bcRefCount = 0;
+  }
+}
+function onBroadcast(event) {
+  const { eventType, path: mutatedPath } = event.data;
+  for (const entry of watchers) {
+    const filename = matchWatcher(entry, mutatedPath);
+    if (filename !== null) {
+      try {
+        entry.listener(eventType, filename);
+      } catch {
+      }
+    }
+  }
+  const fileSet = fileWatchers.get(mutatedPath);
+  if (fileSet) {
+    for (const entry of fileSet) {
+      triggerWatchFile(entry);
+    }
+  }
+}
+function matchWatcher(entry, mutatedPath) {
+  const { absPath, recursive } = entry;
+  if (mutatedPath === absPath) {
+    return basename(mutatedPath);
+  }
+  if (!mutatedPath.startsWith(absPath) || mutatedPath.charAt(absPath.length) !== "/") {
+    return null;
+  }
+  const relativePath = mutatedPath.substring(absPath.length + 1);
+  if (recursive) return relativePath;
+  return relativePath.indexOf("/") === -1 ? relativePath : null;
+}
+function watch(filePath, options, listener) {
+  const opts = typeof options === "string" ? { } : options ?? {};
+  const cb = listener ?? (() => {
+  });
+  const absPath = resolve(filePath);
+  const signal = opts.signal;
+  const entry = {
+    absPath,
+    recursive: opts.recursive ?? false,
+    listener: cb,
+    signal
+  };
+  ensureBc();
+  watchers.add(entry);
+  if (signal) {
+    const onAbort = () => {
+      watchers.delete(entry);
+      releaseBc();
+      signal.removeEventListener("abort", onAbort);
+    };
+    if (signal.aborted) {
+      onAbort();
+    } else {
+      signal.addEventListener("abort", onAbort);
+    }
+  }
   const watcher = {
-    close: () => clearInterval(interval),
-    ref: () => watcher,
-    unref: () => watcher
+    close() {
+      watchers.delete(entry);
+      releaseBc();
+    },
+    ref() {
+      return watcher;
+    },
+    unref() {
+      return watcher;
+    }
   };
   return watcher;
 }
-async function* watchAsync(asyncRequest, filePath, options) {
-  let lastMtime = 0;
-  const signal = options?.signal;
-  while (!signal?.aborted) {
-    try {
-      const s = await stat(asyncRequest, filePath);
-      if (s.mtimeMs !== lastMtime) {
-        if (lastMtime !== 0) {
-          yield { eventType: "change", filename: basename(filePath) };
-        }
-        lastMtime = s.mtimeMs;
+function watchFile(syncRequest, filePath, optionsOrListener, listener) {
+  let opts;
+  let cb;
+  if (typeof optionsOrListener === "function") {
+    cb = optionsOrListener;
+    opts = {};
+  } else {
+    opts = optionsOrListener ?? {};
+    cb = listener;
+  }
+  if (!cb) return;
+  const absPath = resolve(filePath);
+  const interval = opts.interval ?? 5007;
+  let prevStats = null;
+  try {
+    prevStats = statSync(syncRequest, absPath);
+  } catch {
+  }
+  const entry = {
+    absPath,
+    listener: cb,
+    interval,
+    prevStats,
+    syncRequest,
+    timerId: null
+  };
+  ensureBc();
+  let set = fileWatchers.get(absPath);
+  if (!set) {
+    set = /* @__PURE__ */ new Set();
+    fileWatchers.set(absPath, set);
+  }
+  set.add(entry);
+  entry.timerId = setInterval(() => triggerWatchFile(entry), interval);
+}
+function unwatchFile(filePath, listener) {
+  const absPath = resolve(filePath);
+  const set = fileWatchers.get(absPath);
+  if (!set) return;
+  if (listener) {
+    for (const entry of set) {
+      if (entry.listener === listener) {
+        if (entry.timerId !== null) clearInterval(entry.timerId);
+        set.delete(entry);
+        releaseBc();
+        break;
       }
+    }
+    if (set.size === 0) fileWatchers.delete(absPath);
+  } else {
+    for (const entry of set) {
+      if (entry.timerId !== null) clearInterval(entry.timerId);
+      releaseBc();
+    }
+    fileWatchers.delete(absPath);
+  }
+}
+function triggerWatchFile(entry) {
+  let currStats = null;
+  try {
+    currStats = statSync(entry.syncRequest, entry.absPath);
+  } catch {
+  }
+  const prev = entry.prevStats ?? emptyStats();
+  const curr = currStats ?? emptyStats();
+  if (prev.mtimeMs !== curr.mtimeMs || prev.size !== curr.size || prev.ino !== curr.ino) {
+    entry.prevStats = currStats;
+    try {
+      entry.listener(curr, prev);
     } catch {
-      yield { eventType: "rename", filename: basename(filePath) };
-      return;
     }
-    await new Promise((r) => setTimeout(r, 100));
+  }
+}
+function emptyStats() {
+  const zero = /* @__PURE__ */ new Date(0);
+  return {
+    isFile: () => false,
+    isDirectory: () => false,
+    isBlockDevice: () => false,
+    isCharacterDevice: () => false,
+    isSymbolicLink: () => false,
+    isFIFO: () => false,
+    isSocket: () => false,
+    dev: 0,
+    ino: 0,
+    mode: 0,
+    nlink: 0,
+    uid: 0,
+    gid: 0,
+    rdev: 0,
+    size: 0,
+    blksize: 4096,
+    blocks: 0,
+    atimeMs: 0,
+    mtimeMs: 0,
+    ctimeMs: 0,
+    birthtimeMs: 0,
+    atime: zero,
+    mtime: zero,
+    ctime: zero,
+    birthtime: zero
+  };
+}
+async function* watchAsync(_asyncRequest, filePath, options) {
+  const absPath = resolve(filePath);
+  const recursive = options?.recursive ?? false;
+  const signal = options?.signal;
+  const queue = [];
+  let resolve2 = null;
+  const entry = {
+    absPath,
+    recursive,
+    listener: (eventType, filename) => {
+      queue.push({ eventType, filename });
+      if (resolve2) {
+        resolve2();
+        resolve2 = null;
+      }
+    },
+    signal
+  };
+  ensureBc();
+  watchers.add(entry);
+  try {
+    while (!signal?.aborted) {
+      if (queue.length === 0) {
+        await new Promise((r) => {
+          resolve2 = r;
+        });
+      }
+      while (queue.length > 0) {
+        yield queue.shift();
+      }
+    }
+  } finally {
+    watchers.delete(entry);
+    releaseBc();
   }
 }
 
@@ -1233,9 +1433,9 @@ var VFSFileSystem = class {
         }
       };
       mc.port1.start();
-      const bc = new BroadcastChannel("vfs-leader-change");
-      bc.postMessage({ type: "leader-changed" });
-      bc.close();
+      const bc2 = new BroadcastChannel("vfs-leader-change");
+      bc2.postMessage({ type: "leader-changed" });
+      bc2.close();
     }).catch((err) => {
       console.warn("[VFS] SW broker unavailable, single-tab only:", err.message);
     });
@@ -1501,11 +1701,13 @@ var VFSFileSystem = class {
   }
   // ---- Watch methods ----
   watch(filePath, options, listener) {
-    return watch();
+    return watch(filePath, options, listener);
   }
   watchFile(filePath, optionsOrListener, listener) {
+    watchFile(this._sync, filePath, optionsOrListener, listener);
   }
   unwatchFile(filePath, listener) {
+    unwatchFile(filePath, listener);
   }
   // ---- Stream methods ----
   createReadStream(filePath, options) {