@rljson/fs-agent 0.0.42 → 0.0.43

package/dist/fs-agent.js

@@ -443,6 +443,10 @@ class FsScanner {
   _cacheLoaded = false;
   /** Entries that vanished mid-scan, counted per {@link scan} for one summary. */
   _vanishedDuringScan = 0;
+  /** The scan pass running right now, if any. See {@link _scanAfterNow}. */
+  _activeScan = null;
+  /** The single follow-up pass everyone who arrived mid-scan is waiting on. */
+  _pendingScan = null;
   constructor(rootPath, options = {}) {
     this._rootPath = rootPath;
     this._options = {
@@ -749,7 +753,7 @@ class FsScanner {
     }
     const prevKey = this._tree ? this._safetyContentKey(this._tree) : null;
     try {
-      await this.scan();
+      await this._scanAfterNow();
     } catch (err) {
       console.warn(
         `[fs-scanner] safety rescan failed: ${FsScanner._errMessage(err)}`
@@ -840,7 +844,7 @@ class FsScanner {
     try {
       if (exists) {
         const existingTree = this._findTreeByPath(relativePath);
-        await this.scan();
+        await this._scanAfterNow();
         await this._notifyChange({
           type: existingTree ? "modified" : "added",
           path: relativePath
@@ -855,12 +859,57 @@ class FsScanner {
         this.stopWatch();
       }
       if (rootExists) {
-        await this.scan();
+        await this._scanAfterNow();
         await this._notifyChange({ type: "deleted", path: relativePath });
       }
     } catch {
     }
   }
+  /**
+   * A scan that is guaranteed to have STARTED after this call, sharing one
+   * pass with everyone else who asked while it was running.
+   *
+   * `scan()` is a whole-tree operation: it walks every directory, stats every
+   * file and writes a blob for anything new. Calling it once per watcher event
+   * therefore costs O(files²) on a burst — and fs.watch does not await its
+   * callback, so those scans all run AT ONCE. Copying 1 200 tiny files into a
+   * watched folder took 1 200 concurrent full scans: the CPU sat 82% idle
+   * waiting on the filesystem, RSS climbed from 263 MB to 785 MB, and after two
+   * minutes the peer had received nothing. On the customer's 3 702-file folder
+   * the same burst wedged the client outright.
+   *
+   * Started-after is the part that cannot be traded away. Joining a scan that
+   * began BEFORE the event would let a push carry a tree that predates the file
+   * that triggered it — which is precisely the partial trees the lab saw
+   * advertised: 64 nodes, then 103, then 204, each a stale snapshot of a folder
+   * that already held twelve hundred files. So a caller either starts a scan
+   * now, or waits for the one that begins when the current pass ends. A burst
+   * of any size collapses to at most two scans, and no change is missed.
+   */
+  _scanAfterNow() {
+    if (!this._activeScan) {
+      const started = (async () => {
+        try {
+          return await this.scan();
+        } finally {
+          this._activeScan = null;
+        }
+      })();
+      this._activeScan = started;
+      return started;
+    }
+    if (this._pendingScan) return this._pendingScan;
+    const queued = (async () => {
+      try {
+        await this._activeScan;
+      } catch {
+      }
+      this._pendingScan = null;
+      return this._scanAfterNow();
+    })();
+    this._pendingScan = queued;
+    return queued;
+  }
   _findTreeByPath(relativePath) {
     if (!this._tree) return void 0;
     for (const tree of this._tree.trees.values()) {

package/dist/fs-scanner.d.ts

@@ -119,6 +119,10 @@ export declare class FsScanner {
     private _cacheLoaded;
     /** Entries that vanished mid-scan, counted per {@link scan} for one summary. */
     private _vanishedDuringScan;
+    /** The scan pass running right now, if any. See {@link _scanAfterNow}. */
+    private _activeScan;
+    /** The single follow-up pass everyone who arrived mid-scan is waiting on. */
+    private _pendingScan;
     constructor(rootPath: string, options?: FsScanOptions);
     get tree(): FsTree | null;
     /** Whether a watcher is currently installed. */
@@ -174,6 +178,28 @@ export declare class FsScanner {
     /** Whether the host is Windows — gates Windows-specific watcher hardening. */
     private static get _isWindows();
     private _handleFileChange;
+    /**
+     * A scan that is guaranteed to have STARTED after this call, sharing one
+     * pass with everyone else who asked while it was running.
+     *
+     * `scan()` is a whole-tree operation: it walks every directory, stats every
+     * file and writes a blob for anything new. Calling it once per watcher event
+     * therefore costs O(files²) on a burst — and fs.watch does not await its
+     * callback, so those scans all run AT ONCE. Copying 1 200 tiny files into a
+     * watched folder took 1 200 concurrent full scans: the CPU sat 82% idle
+     * waiting on the filesystem, RSS climbed from 263 MB to 785 MB, and after two
+     * minutes the peer had received nothing. On the customer's 3 702-file folder
+     * the same burst wedged the client outright.
+     *
+     * Started-after is the part that cannot be traded away. Joining a scan that
+     * began BEFORE the event would let a push carry a tree that predates the file
+     * that triggered it — which is precisely the partial trees the lab saw
+     * advertised: 64 nodes, then 103, then 204, each a stale snapshot of a folder
+     * that already held twelve hundred files. So a caller either starts a scan
+     * now, or waits for the one that begins when the current pass ends. A burst
+     * of any size collapses to at most two scans, and no change is missed.
+     */
+    private _scanAfterNow;
     private _findTreeByPath;
     /**
      * Whether this notification should escape the pause.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/fs-agent",
-  "version": "0.0.42",
+  "version": "0.0.43",
   "description": "Rljson fs-agent description",
   "homepage": "https://github.com/rljson/fs-agent",
   "bugs": "https://github.com/rljson/fs-agent/issues",