@fgv/ts-web-extras 5.1.0-4 → 5.1.0-5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-web-extras",
-  "version": "5.1.0-4",
+  "version": "5.1.0-5",
   "description": "Browser-compatible utilities and FileTree implementations",
   "main": "lib/index.js",
   "types": "dist/ts-web-extras.d.ts",
@@ -46,19 +46,19 @@
     "@types/react": "~19.2.8",
     "typedoc": "~0.28.16",
     "typedoc-plugin-markdown": "~4.9.0",
-    "@fgv/heft-dual-rig": "5.1.0-4",
-    "@fgv/typedoc-compact-theme": "5.1.0-4",
-    "@fgv/ts-json-base": "5.1.0-4",
-    "@fgv/ts-utils-jest": "5.1.0-4",
-    "@fgv/ts-utils": "5.1.0-4",
-    "@fgv/ts-extras": "5.1.0-4"
+    "@fgv/typedoc-compact-theme": "5.1.0-5",
+    "@fgv/heft-dual-rig": "5.1.0-5",
+    "@fgv/ts-utils": "5.1.0-5",
+    "@fgv/ts-json-base": "5.1.0-5",
+    "@fgv/ts-extras": "5.1.0-5",
+    "@fgv/ts-utils-jest": "5.1.0-5"
   },
   "peerDependencies": {
     "react": ">=18 <20",
     "react-dom": ">=18 <20",
-    "@fgv/ts-json-base": "5.1.0-4",
-    "@fgv/ts-extras": "5.1.0-4",
-    "@fgv/ts-utils": "5.1.0-4"
+    "@fgv/ts-extras": "5.1.0-5",
+    "@fgv/ts-json-base": "5.1.0-5",
+    "@fgv/ts-utils": "5.1.0-5"
   },
   "exports": {
     ".": {

package/rush-logs/ts-web-extras.build.cache.log

@@ -1,3 +1,3 @@
 Caching build output folders: dist, lib, temp, .rush/temp/operation/build
 Successfully set cache entry.
-Cache key: 44b0369e8112f3c6f4248af466a3f35ad626d9d7
+Cache key: 54f89319dd14b2acc47614d70128001f4227d01e

package/rush-logs/ts-web-extras.build.log

@@ -5,34 +5,34 @@ Invoking: heft test --clean
 [build:api-extractor] Using API Extractor version 7.57.7
 [build:api-extractor] Analysis will use the bundled TypeScript version 5.8.2
 [build:api-extractor] *** The target project appears to use TypeScript 5.9.3 which is newer than the bundled compiler engine; consider upgrading API Extractor.
- ---- build finished (24.455s) ---- 
+ ---- build finished (25.483s) ---- 
  ---- test started ---- 
 [test:jest] Using Jest version 29.5.0
 [test:jest] 
 [test:jest] Run start. 9 test suites
-[test:jest] START lib/test/unit/fileApiTreeAccessors.test.js
 [test:jest] START lib/test/unit/httpTreeAccessors.test.js
+[test:jest] START lib/test/unit/fileApiTreeAccessors.test.js
 [test:jest] START lib/test/unit/localStorageTreeAccessors.test.js
 [test:jest] START lib/test/unit/fileSystemAccessTreeAccessors.test.js
-[test:jest] PASS lib/test/unit/httpTreeAccessors.test.js (duration: 1.937s, 57 passed, 0 failed)
+[test:jest] PASS lib/test/unit/localStorageTreeAccessors.test.js (duration: 1.899s, 44 passed, 0 failed)
 [test:jest] START lib/test/unit/fileTreeHelpers.test.js
-[test:jest] PASS lib/test/unit/fileApiTreeAccessors.test.js (duration: 2.182s, 65 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileApiTreeAccessors.test.js (duration: 2.144s, 65 passed, 0 failed)
 [test:jest] START lib/test/unit/fileApiTypes.test.js
-[test:jest] PASS lib/test/unit/localStorageTreeAccessors.test.js (duration: 2.170s, 44 passed, 0 failed)
+[test:jest] PASS lib/test/unit/httpTreeAccessors.test.js (duration: 2.546s, 61 passed, 0 failed)
 [test:jest] START lib/test/unit/urlParams.test.js
-[test:jest] PASS lib/test/unit/fileSystemAccessTreeAccessors.test.js (duration: 1.659s, 44 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileSystemAccessTreeAccessors.test.js (duration: 1.489s, 44 passed, 0 failed)
 [test:jest] START lib/test/unit/directoryHandleStore.test.js
-[test:jest] PASS lib/test/unit/fileApiTypes.test.js (duration: 1.275s, 36 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileTreeHelpers.test.js (duration: 1.864s, 35 passed, 0 failed)
 [test:jest] START lib/test/unit/browserHashProvider.test.js
-[test:jest] PASS lib/test/unit/fileTreeHelpers.test.js (duration: 1.784s, 35 passed, 0 failed)
-[test:jest] PASS lib/test/unit/directoryHandleStore.test.js (duration: 1.140s, 19 passed, 0 failed)
-[test:jest] PASS lib/test/unit/urlParams.test.js (duration: 1.398s, 60 passed, 0 failed)
-[test:jest] PASS lib/test/unit/browserHashProvider.test.js (duration: 1.392s, 15 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileApiTypes.test.js (duration: 1.590s, 36 passed, 0 failed)
+[test:jest] PASS lib/test/unit/urlParams.test.js (duration: 1.224s, 60 passed, 0 failed)
+[test:jest] PASS lib/test/unit/directoryHandleStore.test.js (duration: 1.391s, 19 passed, 0 failed)
+[test:jest] PASS lib/test/unit/browserHashProvider.test.js (duration: 1.278s, 15 passed, 0 failed)
 [test:jest] 
 [test:jest] Tests finished:
-[test:jest]   Successes: 375
+[test:jest]   Successes: 379
 [test:jest]   Failures: 0
-[test:jest]   Total: 376
+[test:jest]   Total: 380
 -----------------------------------|---------|----------|---------|---------|-------------------
 File                               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
 -----------------------------------|---------|----------|---------|---------|-------------------
@@ -40,16 +40,16 @@ All files                          |     100 |    99.62 |     100 |     100 |
  crypto-utils                      |     100 |      100 |     100 |     100 |                   
   browserCryptoProvider.ts         |     100 |      100 |     100 |     100 |                   
   browserHashProvider.ts           |     100 |      100 |     100 |     100 |                   
- file-tree                         |     100 |    99.57 |     100 |     100 |                   
+ file-tree                         |     100 |    99.58 |     100 |     100 |                   
   directoryHandleStore.ts          |     100 |      100 |     100 |     100 |                   
   fileApiTreeAccessors.ts          |     100 |      100 |     100 |     100 |                   
   fileSystemAccessTreeAccessors.ts |     100 |      100 |     100 |     100 |                   
-  httpTreeAccessors.ts             |     100 |    98.41 |     100 |     100 | 339               
+  httpTreeAccessors.ts             |     100 |    98.42 |     100 |     100 | 369               
   localStorageTreeAccessors.ts     |     100 |      100 |     100 |     100 |                   
  helpers                           |     100 |      100 |     100 |     100 |                   
   fileTreeHelpers.ts               |     100 |      100 |     100 |     100 |                   
  url-utils                         |     100 |      100 |     100 |     100 |                   
   urlParams.ts                     |     100 |      100 |     100 |     100 |                   
 -----------------------------------|---------|----------|---------|---------|-------------------
- ---- test finished (7.763s) ---- 
--------------------- Finished (32.236s) --------------------
+ ---- test finished (8.203s) ---- 
+-------------------- Finished (33.696s) --------------------

package/src/packlets/file-tree/httpTreeAccessors.ts

@@ -130,6 +130,8 @@ export class HttpTreeAccessors<TCT extends string = string>
    */
   public async syncToDisk(): Promise<Result<void>> {
     if (this._syncPromise) {
+      // Wait for the in-flight sync — it drains the queue in a loop,
+      // so any items added before it finishes will be included.
       return this._syncPromise;
     }
 
@@ -140,66 +142,94 @@ export class HttpTreeAccessors<TCT extends string = string>
   }
 
   private async _doSync(): Promise<Result<void>> {
-    if (this._dirtyFiles.size === 0 && this._pendingDeletions.size === 0) {
-      return succeed(undefined);
-    }
-
-    // Snapshot and clear dirty sets so that changes arriving during
-    // the async sync are not dropped when we finish.
-    const deletions = new Set(this._pendingDeletions);
-    const dirty = new Set(this._dirtyFiles);
-    this._pendingDeletions.clear();
-    this._dirtyFiles.clear();
+    // Drain loop: keep processing as long as new items arrive.
+    // This is critical for bulk operations (e.g. reset) where many
+    // deleteFile/saveFileContents calls happen synchronously — only
+    // the first may be in the set when we snapshot, but the rest
+    // arrive during the async gaps and must be picked up before
+    // we return.
+    let didWork = false;
+    while (this._dirtyFiles.size > 0 || this._pendingDeletions.size > 0) {
+      didWork = true;
+      // Snapshot and clear so that changes arriving during the async
+      // requests land in the live sets for the next iteration.
+      const deletions = new Set(this._pendingDeletions);
+      const dirty = new Set(this._dirtyFiles);
+      this._pendingDeletions.clear();
+      this._dirtyFiles.clear();
+
+      for (const path of deletions) {
+        const query = new URLSearchParams();
+        query.set('path', path);
+        if (this._namespace) {
+          query.set('namespace', this._namespace);
+        }
 
-    for (const path of deletions) {
-      const query = new URLSearchParams();
-      query.set('path', path);
-      if (this._namespace) {
-        query.set('namespace', this._namespace);
+        const deleteResult = await this._requestWithRetry<{ deleted: boolean }>(`/file?${query.toString()}`, {
+          method: 'DELETE'
+        });
+        if (deleteResult.isFailure()) {
+          this._restoreUnsynced(deletions, dirty);
+          return fail(`delete ${path}: ${deleteResult.message}`);
+        }
       }
 
-      const deleteResult = await this._requestWithRetry<{ deleted: boolean }>(`/file?${query.toString()}`, {
-        method: 'DELETE'
-      });
-      if (deleteResult.isFailure()) {
-        return fail(`delete ${path}: ${deleteResult.message}`);
-      }
-    }
+      for (const path of dirty) {
+        const contentsResult = this.getFileContents(path);
+        if (contentsResult.isFailure()) {
+          this._restoreUnsynced(deletions, dirty);
+          return fail(`${path}: ${contentsResult.message}`);
+        }
 
-    for (const path of dirty) {
-      const contentsResult = this.getFileContents(path);
-      if (contentsResult.isFailure()) {
-        return fail(`${path}: ${contentsResult.message}`);
+        const body: Record<string, unknown> = {
+          path,
+          contents: contentsResult.value
+        };
+        if (this._namespace) {
+          body.namespace = this._namespace;
+        }
+
+        const saveResult = await this._requestWithRetry<IHttpStorageFileResponse>('/file', {
+          method: 'PUT',
+          body: JSON.stringify(body)
+        });
+        if (saveResult.isFailure()) {
+          this._restoreUnsynced(deletions, dirty);
+          return fail(`sync ${path}: ${saveResult.message}`);
+        }
       }
+    }
 
-      const body: Record<string, unknown> = {
-        path,
-        contents: contentsResult.value
-      };
+    if (didWork) {
+      const syncBody: Record<string, unknown> = {};
       if (this._namespace) {
-        body.namespace = this._namespace;
+        syncBody.namespace = this._namespace;
       }
 
-      const saveResult = await this._requestWithRetry<IHttpStorageFileResponse>('/file', {
-        method: 'PUT',
-        body: JSON.stringify(body)
+      const syncResult = await this._requestWithRetry<IHttpStorageSyncResponse>('/sync', {
+        method: 'POST',
+        body: JSON.stringify(syncBody)
       });
-      if (saveResult.isFailure()) {
-        return fail(`sync ${path}: ${saveResult.message}`);
+
+      if (syncResult.isFailure()) {
+        return fail(syncResult.message);
       }
     }
+    return succeed(undefined);
+  }
 
-    const syncBody: Record<string, unknown> = {};
-    if (this._namespace) {
-      syncBody.namespace = this._namespace;
+  /**
+   * Restores snapshotted items back into the live dirty sets so they
+   * are retried on the next sync attempt. Items that were added to
+   * the live sets while the sync was in flight are preserved.
+   */
+  private _restoreUnsynced(deletions: Set<string>, dirty: Set<string>): void {
+    for (const path of deletions) {
+      this._pendingDeletions.add(path);
+    }
+    for (const path of dirty) {
+      this._dirtyFiles.add(path);
     }
-
-    const syncResult = await this._requestWithRetry<IHttpStorageSyncResponse>('/sync', {
-      method: 'POST',
-      body: JSON.stringify(syncBody)
-    });
-
-    return syncResult.isFailure() ? fail(syncResult.message) : succeed(undefined);
   }
 
   /**

package/src/test/unit/httpTreeAccessors.test.ts

@@ -1567,5 +1567,184 @@ describe('HttpTreeAccessors', () => {
       expect(putCalls).toHaveLength(1);
       expect(postCalls).toHaveLength(1);
     });
+
+    test('drains items written during an in-flight sync within the same _doSync call', async () => {
+      // This tests the drain loop fix for the race where:
+      // 1. sync starts, snapshots dirty set {a.json}
+      // 2. during the PUT for a.json, a new write arrives adding a.json back
+      // 3. _doSync loops back, snapshots the new item, and syncs it too
+      // 4. Only one POST /sync is sent at the end, after all items are drained
+      let callCount = 0;
+      let saveHook: (() => void) | undefined;
+
+      const fetchImpl: typeof fetch = (url, init) => {
+        callCount++;
+        const urlStr = url.toString();
+
+        // Calls 1-2: fromHttp load
+        if (callCount <= 2) {
+          if (callCount === 1) {
+            return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('a.json') }));
+          }
+          return Promise.resolve(
+            makeMockResponse({ ok: true, jsonValue: fileResponse('/a.json', '"orig"') })
+          );
+        }
+
+        // Call 3: first PUT /file for a.json — trigger a write mid-sync
+        if (callCount === 3 && init?.method === 'PUT') {
+          saveHook?.();
+          return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/a.json', '"v1"') }));
+        }
+
+        // Call 4: second PUT /file for a.json (drain loop iteration)
+        if (callCount === 4 && init?.method === 'PUT') {
+          return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/a.json', '"v2"') }));
+        }
+
+        // Call 5: single POST /sync after drain loop exits
+        if (callCount === 5 && urlStr.includes('/sync')) {
+          return Promise.resolve(makeMockResponse({ ok: true, jsonValue: { synced: 1 } }));
+        }
+
+        return Promise.reject(new Error(`Unexpected call #${callCount} to ${urlStr}`));
+      };
+
+      const accessors = (
+        await HttpTreeAccessors.fromHttp({
+          baseUrl: 'http://localhost:3000',
+          fetchImpl: fetchImpl as typeof fetch,
+          mutable: true
+        })
+      ).orThrow();
+
+      // Write a.json
+      accessors.saveFileContents('/a.json', '"v1"').orThrow();
+
+      // Set up the hook BEFORE starting sync — the mock fetch for the PUT
+      // runs synchronously within syncToDisk(), so the hook must be in place.
+      saveHook = () => {
+        accessors.saveFileContents('/a.json', '"v2"').orThrow();
+      };
+
+      // Start sync — during the first PUT, saveHook fires and writes v2.
+      // The drain loop in _doSync picks this up and PUTs again before
+      // sending the final POST /sync.
+      const result = await accessors.syncToDisk();
+
+      expect(result).toSucceed();
+      expect(accessors.isDirty()).toBe(false);
+
+      // 5 calls: 2 load + 2 PUTs (v1, v2) + 1 POST /sync
+      expect(callCount).toBe(5);
+    });
+  });
+
+  describe('syncToDisk() error recovery', () => {
+    test('restores dirty files when PUT fails so they can be retried', async () => {
+      const { fetchImpl } = makeMockFetch([
+        { ok: true, jsonValue: rootWithOneFile('data.json') },
+        { ok: true, jsonValue: fileResponse('/data.json', '{}') },
+        // PUT /file fails with non-transient error
+        { ok: false, status: 500, textValue: 'Server Error' }
+      ]);
+
+      const accessors = (
+        await HttpTreeAccessors.fromHttp({
+          baseUrl: 'http://localhost:3000',
+          fetchImpl,
+          mutable: true
+        })
+      ).orThrow();
+
+      accessors.saveFileContents('/data.json', '"updated"').orThrow();
+      expect(accessors.isDirty()).toBe(true);
+
+      const result = await accessors.syncToDisk();
+      expect(result).toFailWith(/sync.*data\.json.*server error/i);
+
+      // The file should still be dirty so a retry is possible
+      expect(accessors.isDirty()).toBe(true);
+      expect(accessors.getDirtyPaths()).toContain('/data.json');
+    });
+
+    test('restores pending deletions when DELETE fails so they can be retried', async () => {
+      const { fetchImpl } = makeMockFetch([
+        { ok: true, jsonValue: rootWithOneFile('data.json') },
+        { ok: true, jsonValue: fileResponse('/data.json', '{}') },
+        // DELETE fails with non-transient error
+        { ok: false, status: 500, textValue: 'Server Error' }
+      ]);
+
+      const accessors = (
+        await HttpTreeAccessors.fromHttp({
+          baseUrl: 'http://localhost:3000',
+          fetchImpl,
+          mutable: true
+        })
+      ).orThrow();
+
+      accessors.deleteFile('/data.json').orThrow();
+      expect(accessors.isDirty()).toBe(true);
+
+      const result = await accessors.syncToDisk();
+      expect(result).toFailWith(/delete.*data\.json.*server error/i);
+
+      // The deletion should still be pending so a retry is possible
+      expect(accessors.isDirty()).toBe(true);
+      expect(accessors.getDirtyPaths()).toContain('/data.json');
+    });
+
+    test('restores dirty files when POST /sync fails so they can be retried', async () => {
+      jest.useFakeTimers();
+      try {
+        let callCount = 0;
+        const fetchImpl: typeof fetch = (_url, _init) => {
+          callCount++;
+          if (callCount === 1) {
+            return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('data.json') }));
+          }
+          if (callCount === 2) {
+            return Promise.resolve(
+              makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '{}') })
+            );
+          }
+          if (callCount === 3) {
+            // PUT succeeds
+            return Promise.resolve(
+              makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '"v2"') })
+            );
+          }
+          // All /sync attempts: persistent 503
+          return Promise.resolve(
+            makeMockResponse({ ok: false, status: 503, textValue: 'Service Unavailable' })
+          );
+        };
+
+        const accessors = (
+          await HttpTreeAccessors.fromHttp({
+            baseUrl: 'http://localhost:3000',
+            fetchImpl,
+            mutable: true
+          })
+        ).orThrow();
+
+        accessors.saveFileContents('/data.json', '"v2"').orThrow();
+
+        const syncPromise = accessors.syncToDisk();
+        await jest.advanceTimersByTimeAsync(1500);
+
+        const result = await syncPromise;
+        expect(result).toFailWith(/service unavailable/i);
+
+        // The PUT succeeded — data is on the server — so the file is no
+        // longer dirty. Only the server-side /sync acknowledgement failed,
+        // which is not something the client can meaningfully retry via
+        // re-sending the file contents.
+        expect(accessors.isDirty()).toBe(false);
+      } finally {
+        jest.useRealTimers();
+      }
+    });
   });
 });