Throw Exponential Backoff error containing all execution errors

test/exponential-backoff.test.ts

@@ -1,5 +1,6 @@
 import { expect, test, vi } from 'vitest';
 import { ExponentialBackoff } from '../source/exponential-backoff.ts';
+import { ExponentialBackoffMaxRetriesHitError } from '../source/errors.ts';
 
 /**
  * Tests that the static {@link ExponentialBackoff.run} helper creates a throwaway instance
@@ -114,7 +115,7 @@ const testExponentialBackoffRetriesUntilSuccess = async (): Promise<void> => {
 
 /**
  * Tests that the onError callback is invoked once for every failed attempt, including the last one
- * before the final rejection is thrown to the caller.
+ * before an ExponentialBackoffMaxRetriesHitError is thrown to the caller.
  */
 const testExponentialBackoffCallsOnErrorForEachFailure = async (): Promise<void> => {
     const error = new Error('temporary failure');
@@ -128,29 +129,35 @@ const testExponentialBackoffCallsOnErrorForEachFailure = async (): Promise<void>
             baseDelay: 0,
             jitter: 0,
             maxAttempts: 3,
-        })).rejects.toThrow('temporary failure');
+        })).rejects.toThrow(ExponentialBackoffMaxRetriesHitError);
 
     expect(onError).toHaveBeenCalledTimes(3);
     expect(onError).toHaveBeenCalledWith(error);
 };
 
 /**
- * Tests that when all attempts are exhausted the caller receives the error from the final attempt,
- * not an earlier one.
+ * Tests that when all attempts are exhausted the caller receives an ExponentialBackoffMaxRetriesHitError
+ * with every task error preserved in order on the cause.
  */
-const testExponentialBackoffThrowsLastErrorWhenExhausted = async (): Promise<void> => {
+const testExponentialBackoffThrowsMaxRetriesHitErrorWhenExhausted = async (): Promise<void> => {
     const firstError = new Error('first');
     const lastError = new Error('last');
 
-    // Two distinct errors so we can prove the last one surfaces.
+    // Two distinct errors so we can prove both are collected, not just the last one.
     const fn = vi.fn().mockRejectedValueOnce(firstError)
 .mockRejectedValueOnce(lastError);
 
-    await expect(ExponentialBackoff.run(fn, () => {}, {
+    try {
+        await ExponentialBackoff.run(fn, () => {}, {
             baseDelay: 0,
             jitter: 0,
             maxAttempts: 2,
-        })).rejects.toThrow('last');
+        });
+        expect.fail('Expected ExponentialBackoffMaxRetriesHitError to be thrown');
+    } catch (error) {
+        expect(error).toBeInstanceOf(ExponentialBackoffMaxRetriesHitError);
+        expect((error as ExponentialBackoffMaxRetriesHitError).cause).toEqual([firstError, lastError]);
+    }
 
     expect(fn).toHaveBeenCalledTimes(2);
 };
@@ -165,11 +172,19 @@ const testExponentialBackoffWrapsNonErrorThrows = async (): Promise<void> => {
     const onError = vi.fn();
 
     // Single attempt — we fail fast and inspect what onError received.
-    await expect(ExponentialBackoff.run(fn, onError, {
+    try {
+        await ExponentialBackoff.run(fn, onError, {
             baseDelay: 0,
             jitter: 0,
             maxAttempts: 1,
-        })).rejects.toThrow('not-an-error');
+        });
+        expect.fail('Expected ExponentialBackoffMaxRetriesHitError to be thrown');
+    } catch (error) {
+        expect(error).toBeInstanceOf(ExponentialBackoffMaxRetriesHitError);
+        const [wrappedError] = (error as ExponentialBackoffMaxRetriesHitError).cause as Error[];
+        expect(wrappedError).toBeInstanceOf(Error);
+        expect(wrappedError.message).toBe('not-an-error');
+    }
 
     expect(onError).toHaveBeenCalledOnce();
     expect(onError.mock.calls[0][0]).toBeInstanceOf(Error);
@@ -340,7 +355,7 @@ const runTests = async (): Promise<void> => {
     test('ExponentialBackoff: returns the result on first success', testExponentialBackoffSucceedsOnFirstAttempt);
     test('ExponentialBackoff: retries until the function succeeds', testExponentialBackoffRetriesUntilSuccess);
     test('ExponentialBackoff: calls onError for each failed attempt', testExponentialBackoffCallsOnErrorForEachFailure);
-    test('ExponentialBackoff: throws the last error when max attempts are exhausted', testExponentialBackoffThrowsLastErrorWhenExhausted);
+    test('ExponentialBackoff: throws ExponentialBackoffMaxRetriesHitError when max attempts are exhausted', testExponentialBackoffThrowsMaxRetriesHitErrorWhenExhausted);
     test('ExponentialBackoff: wraps non-Error throws before calling onError', testExponentialBackoffWrapsNonErrorThrows);
     test('ExponentialBackoff: works via from and instance run', testExponentialBackoffFromAndInstanceRun);
     test('ExponentialBackoff: retries indefinitely when maxAttempts is 0', testExponentialBackoffRetriesIndefinitelyWhenMaxAttemptsIsZero);