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

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

@@ -0,0 +1,3 @@
+Caching build output folders: dist, lib, temp, .rush/temp/operation/build
+Successfully set cache entry.
+Cache key: 63a2c58f11944fdb592459d835a6483c79343b3f

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

@@ -1,75 +1,55 @@
 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] 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 (3.991s) ---- 
+ ---- build finished (25.695s) ---- 
  ---- 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
-[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/localStorageTreeAccessors.test.js (duration: 1.968s, 44 passed, 0 failed)
 [test:jest] START lib/test/unit/fileTreeHelpers.test.js
+[test:jest] PASS lib/test/unit/httpTreeAccessors.test.js (duration: 2.175s, 61 passed, 0 failed)
 [test:jest] START lib/test/unit/fileApiTypes.test.js
+[test:jest] PASS lib/test/unit/fileApiTreeAccessors.test.js (duration: 2.633s, 65 passed, 0 failed)
 [test:jest] START lib/test/unit/urlParams.test.js
+[test:jest] PASS lib/test/unit/fileSystemAccessTreeAccessors.test.js (duration: 1.502s, 44 passed, 0 failed)
 [test:jest] START lib/test/unit/directoryHandleStore.test.js
+[test:jest] PASS lib/test/unit/fileApiTypes.test.js (duration: 1.432s, 36 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/fileTreeHelpers.test.js (duration: 1.702s, 35 passed, 0 failed)
+[test:jest] PASS lib/test/unit/urlParams.test.js (duration: 1.387s, 60 passed, 0 failed)
+[test:jest] PASS lib/test/unit/directoryHandleStore.test.js (duration: 1.409s, 19 passed, 0 failed)
+[test:jest] PASS lib/test/unit/browserHashProvider.test.js (duration: 1.440s, 15 passed, 0 failed)
 [test:jest] 
 [test:jest] Tests finished:
-[test:jest]   Successes: 370
+[test:jest]   Successes: 379
 [test:jest]   Failures: 0
-[test:jest]   Total: 371
+[test:jest]   Total: 380
 -----------------------------------|---------|----------|---------|---------|-------------------
 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.58 |     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.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 (2.336s) ---- 
--------------------- Finished (6.331s) --------------------
+ ---- test finished (8.236s) ---- 
+-------------------- Finished (33.942s) --------------------

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,65 +120,116 @@ 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._dirtyFiles.size === 0 && this._pendingDeletions.size === 0) {
-      return succeed(undefined);
+    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;
     }
 
-    for (const path of this._pendingDeletions) {
-      const query = new URLSearchParams();
-      query.set('path', path);
-      if (this._namespace) {
-        query.set('namespace', this._namespace);
-      }
+    this._syncPromise = this._doSync().finally(() => {
+      this._syncPromise = undefined;
+    });
+    return this._syncPromise;
+  }
 
-      const deleteResult = await this._request<{ deleted: boolean }>(`/file?${query.toString()}`, {
-        method: 'DELETE'
-      });
-      if (deleteResult.isFailure()) {
-        return fail(`delete ${path}: ${deleteResult.message}`);
+  private async _doSync(): Promise<Result<void>> {
+    // 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);
+        }
+
+        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}`);
+        }
       }
-    }
 
-    for (const path of this._dirtyFiles) {
-      const contentsResult = this.getFileContents(path);
-      if (contentsResult.isFailure()) {
-        return fail(`${path}: ${contentsResult.message}`);
+      for (const path of dirty) {
+        const contentsResult = this.getFileContents(path);
+        if (contentsResult.isFailure()) {
+          this._restoreUnsynced(deletions, dirty);
+          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._request<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);
+  }
 
-    this._pendingDeletions.clear();
-    this._dirtyFiles.clear();
-
-    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._request<IHttpStorageSyncResponse>('/sync', {
-      method: 'POST',
-      body: JSON.stringify(syncBody)
-    });
-
-    return syncResult.isFailure() ? fail(syncResult.message) : succeed(undefined);
   }
 
   /**
@@ -269,7 +323,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 +337,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 +447,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 +461,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);
     }