fix: address Copilot review comments (round 5)

- Track last error instead of first error in AsyncSerializer: clear the
  error after each successful execution so the cycle only rejects if
  the final execution fails. A later coalesced success no longer causes
  a spurious rejection.
- Update @returns JSDoc to precisely document the two-contract behavior:
  cycle-starters observe resolve/reject of the full cycle; coalesced
  callers only observe acknowledgement and do not see success/failure.
- Update the coalesced-error test to reflect that promiseA now resolves
  (not rejects) when the coalesced re-run succeeds.

Author: jcouball

src/asyncSerializer.ts

@@ -32,12 +32,16 @@ export class AsyncSerializer {
    * re-execution.
    *
    * @param fn The async operation to execute
-   * @returns A promise that resolves when this call has been acknowledged
-   *          (either executed immediately or queued for a coalesced re-run). Awaiting
-   *          this promise does not guarantee a distinct execution of {@link fn} for
-   *          this call; coalesced calls share execution cycles. The promise rejects
-   *          if any execution performed during this cycle throws, and rethrows the
-   *          first error encountered after pending executions have been processed.
+   * @returns A promise whose meaning depends on whether this call starts a new
+   *          execution cycle. If no execution is in progress, the promise resolves
+   *          after the current execution cycle completes, including any coalesced
+   *          re-execution triggered while it is running, and rejects if the final
+   *          execution of that cycle fails. If an execution is already in progress,
+   *          the promise resolves once this call has been acknowledged and {@link fn}
+   *          has been stored as the latest pending operation; in that case, the
+   *          returned promise does not observe the eventual success or failure of the
+   *          running/coalesced execution and does not guarantee a distinct execution
+   *          of {@link fn}.
    */
   async execute(fn: () => Promise<void>): Promise<void> {
     // If already executing, store latest fn for the coalesced re-run and return immediately
@@ -47,7 +51,7 @@ export class AsyncSerializer {
     }
 
     this._isExecuting = true;
-    let firstError: unknown | undefined;
+    let lastError: unknown | undefined;
     try {
       // Keep executing while new requests come in, always using the latest queued fn
       let nextFn: (() => Promise<void>) | undefined = fn;
@@ -56,11 +60,9 @@ export class AsyncSerializer {
         this._pendingFn = undefined;
         try {
           await toRun();
+          lastError = undefined; // Clear error if a subsequent execution succeeds
         } catch (error) {
-          // Record the first error but continue processing pending executions
-          if (firstError === undefined) {
-            firstError = error;
-          }
+          lastError = error;
         }
         nextFn = this._pendingFn;
       }
@@ -69,8 +71,8 @@ export class AsyncSerializer {
       this._pendingFn = undefined;
     }
 
-    if (firstError !== undefined) {
-      throw firstError;
+    if (lastError !== undefined) {
+      throw lastError;
     }
   }
 }

src/test/unit/asyncSerializer.test.ts

@@ -128,15 +128,17 @@ describe('AsyncSerializer', () => {
       }
     };
 
-    // Start call A (will error after barrier), then dispatch B and C which get coalesced
+    // Start call A (will error partway through but coalesced re-run succeeds),
+    // then dispatch B and C which get coalesced
     const promiseA = serializer.execute(operation);
     const promiseB = serializer.execute(operation);
     const promiseC = serializer.execute(operation);
 
     release();
 
-    // A rejects; B and C already resolved immediately (coalesced)
-    await promiseA.catch(() => {});
+    // promiseA resolves (not rejects) because the coalesced re-run succeeded,
+    // clearing the error from the first execution
+    await promiseA;
     await promiseB;
     await promiseC;