@fgv/ts-web-extras 5.1.0-1 → 5.1.0-3

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

@@ -1,14 +1,12 @@
 Invoking: heft test --clean 
  ---- build started ---- 
-[build:clean] Deleted 0 files and 3 folders
 [build:typescript] The TypeScript compiler version 5.9.3 is newer than the latest version that was tested with Heft (5.8); it may not work correctly.
 [build:typescript] Using TypeScript version 5.9.3
 [build:api-extractor] Using API Extractor version 7.57.6
 [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 (3.991s) ---- 
+ ---- build finished (24.830s) ---- 
  ---- test started ---- 
-[test:clean] Deleted 0 files and 1 folder
 [test:jest] Using Jest version 29.5.0
 [test:jest] 
 [test:jest] Run start. 9 test suites
@@ -16,60 +14,42 @@ Invoking: heft test --clean
 [test:jest] START lib/test/unit/httpTreeAccessors.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/localStorageTreeAccessors.test.js (duration: 1.749s, 44 passed, 0 failed)
 [test:jest] START lib/test/unit/fileTreeHelpers.test.js
+[test:jest] PASS lib/test/unit/fileApiTreeAccessors.test.js (duration: 2.021s, 65 passed, 0 failed)
 [test:jest] START lib/test/unit/fileApiTypes.test.js
+[test:jest] PASS lib/test/unit/httpTreeAccessors.test.js (duration: 2.316s, 57 passed, 0 failed)
 [test:jest] START lib/test/unit/urlParams.test.js
+[test:jest] PASS lib/test/unit/fileSystemAccessTreeAccessors.test.js (duration: 1.352s, 44 passed, 0 failed)
 [test:jest] START lib/test/unit/directoryHandleStore.test.js
+[test:jest] PASS lib/test/unit/fileTreeHelpers.test.js (duration: 1.538s, 35 passed, 0 failed)
 [test:jest] START lib/test/unit/browserHashProvider.test.js
-(node:72593) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
-(Use `node --trace-deprecation ...` to show where the warning was created)
-(node:72591) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
-(Use `node --trace-deprecation ...` to show where the warning was created)
-(node:72598) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
-(Use `node --trace-deprecation ...` to show where the warning was created)
-[test:jest] PASS lib/test/unit/httpTreeAccessors.test.js (duration: 0.858s, 52 passed, 0 failed)
-[test:jest] PASS lib/test/unit/fileSystemAccessTreeAccessors.test.js (duration: 0.900s, 44 passed, 0 failed)
-[test:jest] PASS lib/test/unit/browserHashProvider.test.js (duration: 0.969s, 15 passed, 0 failed)
-(node:72594) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
-(Use `node --trace-deprecation ...` to show where the warning was created)
-[test:jest] PASS lib/test/unit/fileTreeHelpers.test.js (duration: 0.968s, 35 passed, 0 failed)
-[test:jest] PASS lib/test/unit/directoryHandleStore.test.js (duration: 0.948s, 19 passed, 0 failed)
-(node:72597) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
-(Use `node --trace-deprecation ...` to show where the warning was created)
-(node:72590) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
-(Use `node --trace-deprecation ...` to show where the warning was created)
-(node:72596) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
-(Use `node --trace-deprecation ...` to show where the warning was created)
-(node:72592) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
-(Use `node --trace-deprecation ...` to show where the warning was created)
-[test:jest] PASS lib/test/unit/urlParams.test.js (duration: 0.916s, 60 passed, 0 failed)
-[test:jest] PASS lib/test/unit/fileApiTreeAccessors.test.js (duration: 0.987s, 65 passed, 0 failed)
-[test:jest] PASS lib/test/unit/localStorageTreeAccessors.test.js (duration: 0.974s, 44 passed, 0 failed)
-(node:72595) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
-(Use `node --trace-deprecation ...` to show where the warning was created)
-[test:jest] PASS lib/test/unit/fileApiTypes.test.js (duration: 0.933s, 36 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileApiTypes.test.js (duration: 1.440s, 36 passed, 0 failed)
+[test:jest] PASS lib/test/unit/urlParams.test.js (duration: 1.637s, 60 passed, 0 failed)
+[test:jest] PASS lib/test/unit/directoryHandleStore.test.js (duration: 1.412s, 19 passed, 0 failed)
+[test:jest] PASS lib/test/unit/browserHashProvider.test.js (duration: 1.586s, 15 passed, 0 failed)
 [test:jest] 
 [test:jest] Tests finished:
-[test:jest]   Successes: 370
+[test:jest]   Successes: 375
 [test:jest]   Failures: 0
-[test:jest]   Total: 371
+[test:jest]   Total: 376
 -----------------------------------|---------|----------|---------|---------|-------------------
 File                               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
 -----------------------------------|---------|----------|---------|---------|-------------------
-All files                          |     100 |      100 |     100 |     100 |                   
+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 |      100 |     100 |     100 |                   
+ file-tree                         |     100 |    99.57 |     100 |     100 |                   
   directoryHandleStore.ts          |     100 |      100 |     100 |     100 |                   
   fileApiTreeAccessors.ts          |     100 |      100 |     100 |     100 |                   
   fileSystemAccessTreeAccessors.ts |     100 |      100 |     100 |     100 |                   
-  httpTreeAccessors.ts             |     100 |      100 |     100 |     100 |                   
+  httpTreeAccessors.ts             |     100 |    98.41 |     100 |     100 | 339               
   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 (2.336s) ---- 
--------------------- Finished (6.331s) --------------------
+ ---- test finished (8.132s) ---- 
+-------------------- Finished (32.975s) --------------------

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

@@ -79,6 +79,9 @@ export class HttpTreeAccessors<TCT extends string = string>
   private readonly _userId: string | undefined;
   private readonly _logger: Logging.LogReporter<unknown>;
 
+  /** Guards against concurrent syncToDisk calls (thundering herd from autoSync). */
+  private _syncPromise: Promise<Result<void>> | undefined;
+
   private constructor(files: FileTree.IInMemoryFile<TCT>[], params: IHttpTreeParams<TCT>) {
     super(files, params);
     this._baseUrl = params.baseUrl.replace(/\/$/, '');
@@ -117,21 +120,45 @@ export class HttpTreeAccessors<TCT extends string = string>
 
   /**
    * Synchronizes all dirty files to the HTTP backend.
+   *
+   * Uses a concurrency guard: if a sync is already in progress, callers
+   * await the existing operation rather than starting a parallel one.
+   * This prevents the thundering herd that occurs when autoSync fires
+   * for every file written during a bulk operation (e.g. restore).
+   *
    * @returns A promise that resolves to a result indicating success or failure.
    */
   public async syncToDisk(): Promise<Result<void>> {
+    if (this._syncPromise) {
+      return this._syncPromise;
+    }
+
+    this._syncPromise = this._doSync().finally(() => {
+      this._syncPromise = undefined;
+    });
+    return this._syncPromise;
+  }
+
+  private async _doSync(): Promise<Result<void>> {
     if (this._dirtyFiles.size === 0 && this._pendingDeletions.size === 0) {
       return succeed(undefined);
     }
 
-    for (const path of this._pendingDeletions) {
+    // 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();
+
+    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._request<{ deleted: boolean }>(`/file?${query.toString()}`, {
+      const deleteResult = await this._requestWithRetry<{ deleted: boolean }>(`/file?${query.toString()}`, {
         method: 'DELETE'
       });
       if (deleteResult.isFailure()) {
@@ -139,7 +166,7 @@ export class HttpTreeAccessors<TCT extends string = string>
       }
     }
 
-    for (const path of this._dirtyFiles) {
+    for (const path of dirty) {
       const contentsResult = this.getFileContents(path);
       if (contentsResult.isFailure()) {
         return fail(`${path}: ${contentsResult.message}`);
@@ -153,7 +180,7 @@ export class HttpTreeAccessors<TCT extends string = string>
         body.namespace = this._namespace;
       }
 
-      const saveResult = await this._request<IHttpStorageFileResponse>('/file', {
+      const saveResult = await this._requestWithRetry<IHttpStorageFileResponse>('/file', {
         method: 'PUT',
         body: JSON.stringify(body)
       });
@@ -162,15 +189,12 @@ export class HttpTreeAccessors<TCT extends string = string>
       }
     }
 
-    this._pendingDeletions.clear();
-    this._dirtyFiles.clear();
-
     const syncBody: Record<string, unknown> = {};
     if (this._namespace) {
       syncBody.namespace = this._namespace;
     }
 
-    const syncResult = await this._request<IHttpStorageSyncResponse>('/sync', {
+    const syncResult = await this._requestWithRetry<IHttpStorageSyncResponse>('/sync', {
       method: 'POST',
       body: JSON.stringify(syncBody)
     });
@@ -269,7 +293,10 @@ export class HttpTreeAccessors<TCT extends string = string>
     }
 
     if (!response.ok) {
-      const message = await response.text().catch(() => `HTTP ${response.status}`);
+      const body = await response.text().catch(() => '');
+      const message = body
+        ? `HTTP ${response.status}: ${body}`
+        : `HTTP ${response.status} ${response.statusText}`;
       return fail(message);
     }
 
@@ -280,6 +307,44 @@ export class HttpTreeAccessors<TCT extends string = string>
     return succeed(json as T);
   }
 
+  /**
+   * Wraps `_request` with retry logic for transient failures
+   * (network errors, 503 service unavailable, etc.).
+   */
+  private async _requestWithRetry<T>(resourcePath: string, init?: RequestInit): Promise<Result<T>> {
+    const maxAttempts = 3;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const result = await this._request<T>(resourcePath, init);
+      if (result.isSuccess() || attempt === maxAttempts) {
+        return result;
+      }
+      // Retry on transient-looking errors
+      const msg = result.message;
+      const lowerMsg = msg.toLowerCase();
+      const isTransient =
+        msg.includes('503') ||
+        msg.includes('502') ||
+        msg.includes('429') ||
+        lowerMsg.includes('disconnect') ||
+        lowerMsg.includes('econnreset') ||
+        lowerMsg.includes('failed to fetch') ||
+        lowerMsg.includes('network');
+      if (!isTransient) {
+        return result;
+      }
+      // Exponential backoff: 500ms, 1000ms
+      const delayMs = 500 * Math.pow(2, attempt - 1);
+      this._logger.detail(
+        `Retrying ${
+          init?.method ?? 'GET'
+        } ${resourcePath} after ${delayMs}ms (attempt ${attempt}/${maxAttempts})`
+      );
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+    /* c8 ignore next 1 - defensive coding: loop always returns */
+    return fail('retry loop exited unexpectedly');
+  }
+
   /**
    * Loads files from the HTTP backend for the specified directory path.
    * @param params - Configuration parameters for the HTTP tree accessors.
@@ -352,8 +417,7 @@ export class HttpTreeAccessors<TCT extends string = string>
     }
 
     const fetchImpl = normalizeFetch(params.fetchImpl);
-    /* c8 ignore next 3 - userId header in static _requestWithParams; covered by userId tests via fromHttp */
-    const userIdHeaders: RequestInit | undefined = params.userId
+    const userIdHeaders: RequestInit | undefined = /* c8 ignore next */ params.userId
       ? { headers: { 'X-User-Id': params.userId } }
       : undefined;
     const response = await fetchImpl(
@@ -367,7 +431,10 @@ export class HttpTreeAccessors<TCT extends string = string>
     }
 
     if (!response.ok) {
-      const message = await response.text().catch(() => `HTTP ${response.status}`);
+      const body = await response.text().catch(() => '');
+      const message = body
+        ? `HTTP ${response.status}: ${body}`
+        : `HTTP ${response.status} ${response.statusText}`;
       return fail(message);
     }