@pico-brief/race-promises 1.0.0

package/README.md

@@ -0,0 +1,156 @@
+# racePromises
+
+## What is this?
+
+When you call something slow — like an LLM API — things can go wrong in two ways:
+
+1. **It fails** (network error, rate limit, bad response) → you want to **retry**
+2. **It takes too long** → rather than cancelling and waiting, you want to **fire off another call in parallel** and just use whichever one comes back first
+
+`racePromises` handles both. You give it a function that creates a promise (your API call), tell it how many attempts to allow and how long to wait before firing off the next one, and it takes care of the rest. The first successful result wins.
+
+> **Important:** This pattern works best for **idempotent** operations (e.g. reads, LLM inference). For writes or operations with side effects, launching duplicate requests can cause problems.
+
+---
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `generatePromise` | `() => Promise<T>` | Yes | A function that starts your async task and returns a promise. Called once per attempt. |
+| `amount` | `number` | Yes | Maximum number of calls that will ever be started. Must be greater than 0. Set to `1` for a single attempt with no retries. |
+| `waitTimeSeconds` | `number` | Yes | How long to wait (in **seconds**) after starting a call before firing the next one in parallel. Use `0` to launch all attempts simultaneously. |
+| `shouldRetry` | `(e: any) => boolean` | No | Called when a promise rejects. Return `false` to stop all attempts immediately. Defaults to always `true`. |
+| `onBackgroundError` | `(e: any) => void` | No | Called when a promise rejects *after* the function has already returned a result. Use this to avoid unhandled rejection warnings. See notes below. |
+
+---
+
+## How it works
+
+```
+Start call #1
+│
+├── Succeeds?  →  ✅ Return result
+│
+├── shouldRetry(e) === false?  →  🛑 Stop everything, throw RetryAbortedError
+│
+└── No result yet, and either waitTimeSeconds has elapsed
+    OR all current attempts have already failed?
+      │
+      Start next call in parallel  (previous calls still running!)
+      │
+      └── Whoever resolves first wins
+```
+
+The next call starts as soon as *either* condition is met — whichever comes first. You don't always wait the full `waitTimeSeconds` if all current attempts have already failed.
+
+**If every attempt fails**, throws an `AggregateError` — inspect `e.errors` for each individual rejection reason.
+
+**If `shouldRetry` returns `false`**, throws a `RetryAbortedError` immediately — even if other attempts are still in-flight. The triggering error is attached as `.cause`.
+
+---
+
+## Usage
+
+### Basic example
+
+```typescript
+import racePromises from './racePromises';
+
+const result = await racePromises({
+    generatePromise: () => callMyLLM(prompt),
+    amount: 3,             // fire at most 3 calls total
+    waitTimeSeconds: 5,    // if no result after 5s, start another call in parallel
+});
+```
+
+### Launch all attempts simultaneously
+
+```typescript
+const result = await racePromises({
+    generatePromise: () => callMyLLM(prompt),
+    amount: 3,
+    waitTimeSeconds: 0,    // fire all 3 at once, take whoever responds first
+});
+```
+
+### Single attempt, no retries
+
+```typescript
+const result = await racePromises({
+    generatePromise: () => callMyLLM(prompt),
+    amount: 1,
+    waitTimeSeconds: 10,   // waitTimeSeconds is irrelevant with amount: 1
+});
+// equivalent to just: await callMyLLM(prompt)
+// but with consistent error handling via AggregateError on failure
+```
+
+### With a custom retry condition
+
+Stop retrying on errors you know are unrecoverable, like auth failures:
+
+```typescript
+const result = await racePromises({
+    generatePromise: () => callMyLLM(prompt),
+    amount: 5,
+    waitTimeSeconds: 10,
+    shouldRetry: (e) => {
+        if (e?.status === 401 || e?.status === 403) return false;
+        return true;
+    },
+});
+```
+
+### Handling background rejections
+
+Once `racePromises` returns a winner, other in-flight promises keep running. If they later reject, the runtime will surface unhandled rejection warnings. Use `onBackgroundError` to handle them:
+
+```typescript
+const result = await racePromises({
+    generatePromise: () => callMyLLM(prompt),
+    amount: 3,
+    waitTimeSeconds: 5,
+    onBackgroundError: (e) => {
+        console.warn('A losing attempt failed after the winner was found:', e);
+    },
+});
+```
+
+### Handling all failures
+
+```typescript
+import racePromises, { RetryAbortedError } from './racePromises';
+
+try {
+    const result = await racePromises({
+        generatePromise: () => callMyLLM(prompt),
+        amount: 3,
+        waitTimeSeconds: 5,
+    });
+} catch (e) {
+    if (e instanceof RetryAbortedError) {
+        // shouldRetry returned false — e.cause is the error that triggered it
+        console.error('Gave up retrying due to:', e.cause);
+    } else if (e instanceof AggregateError) {
+        // every attempt failed — e.errors contains each individual rejection reason
+        console.error('All attempts failed:', e.errors);
+    }
+}
+```
+
+---
+
+## Important notes
+
+### `shouldRetry` is called per rejection, not per round
+If multiple attempts are in-flight and they all fail at the same time, `shouldRetry` is called once for each rejection. If you implement a failure budget inside `shouldRetry` (e.g. "give up after 3 failures"), it will drain once per individual rejection — not once per stagger interval. Account for this when setting your budget.
+
+### If `shouldRetry` itself throws, its exception becomes `RetryAbortedError.cause`
+If your `shouldRetry` function throws an exception, that exception — not the original rejection that triggered `shouldRetry` — is used as the `cause` on the `RetryAbortedError`. This is intentional: the thrown exception is treated as the meaningful signal. If you see an unexpected `.cause` while debugging, check whether `shouldRetry` may be throwing internally.
+
+### Promises are never cancelled
+`waitTimeSeconds` means "if I haven't heard back in X seconds, start another one alongside it" — not "cancel and retry". A slow call is never stopped. If you need cleanup (e.g. aborting in-flight HTTP requests), pass an `AbortSignal` into your `generatePromise` and abort it once you have a result.
+
+### `onBackgroundError` fires for losing rejections only
+If a slow promise eventually *succeeds* after the function has already returned a winner, it is silently ignored — `onBackgroundError` is not called. It only fires for promises that eventually *fail* after the winner is known.

package/dist/racePromises.d.ts

@@ -0,0 +1,28 @@
+export declare class RetryAbortedError extends Error {
+    readonly cause: any;
+    constructor(cause: any);
+}
+/**
+ * Runs an async task with staggered retries and parallel racing.
+ *
+ * Starts the first attempt immediately. If it doesn't resolve within
+ * `waitTimeSeconds`, a second attempt is started in parallel — both remain
+ * in-flight and the first to succeed wins. This repeats up to `amount` total
+ * attempts. If an attempt fails, `shouldRetry` decides whether to keep going.
+ *
+ * This is useful for long-running or unreliable tasks (e.g. LLM calls) where
+ * you want low latency on success and automatic recovery from failures, without
+ * cancelling slow-but-potentially-valid in-flight requests.
+ *
+ * Throws `RetryAbortedError` if `shouldRetry` returns false.
+ * Throws `AggregateError` if all attempts fail without triggering an abort.
+ * The `AggregateError.errors` array contains each individual rejection reason.
+ */
+export default function racePromises<T>(params: {
+    generatePromise: () => Promise<T>;
+    amount: number;
+    waitTimeSeconds: number;
+    shouldRetry?: (e: any) => boolean;
+    onBackgroundError?: (e: any) => void;
+}): Promise<T>;
+export declare const sleepAsync: (ms: number) => Promise<void>;

package/dist/racePromises.js

@@ -0,0 +1,168 @@
+export class RetryAbortedError extends Error {
+    constructor(cause) {
+        super('racePromises: shouldRetry() returned false. No further attempts will be made.');
+        this.name = 'RetryAbortedError';
+        this.cause = cause;
+    }
+}
+/**
+ * Runs an async task with staggered retries and parallel racing.
+ *
+ * Starts the first attempt immediately. If it doesn't resolve within
+ * `waitTimeSeconds`, a second attempt is started in parallel — both remain
+ * in-flight and the first to succeed wins. This repeats up to `amount` total
+ * attempts. If an attempt fails, `shouldRetry` decides whether to keep going.
+ *
+ * This is useful for long-running or unreliable tasks (e.g. LLM calls) where
+ * you want low latency on success and automatic recovery from failures, without
+ * cancelling slow-but-potentially-valid in-flight requests.
+ *
+ * Throws `RetryAbortedError` if `shouldRetry` returns false.
+ * Throws `AggregateError` if all attempts fail without triggering an abort.
+ * The `AggregateError.errors` array contains each individual rejection reason.
+ */
+export default async function racePromises(params) {
+    const { generatePromise, amount, waitTimeSeconds, onBackgroundError } = params;
+    const shouldRetry = params.shouldRetry ?? (() => true);
+    if (amount <= 0)
+        throw new Error('amount must be greater than 0');
+    if (waitTimeSeconds < 0)
+        throw new Error('waitTimeSeconds must be non-negative'); // 0 is valid: launch all simultaneously
+    const promises = [];
+    // One-shot semaphore: notifyUpdate() wakes the next waitForUpdate() call.
+    // pendingUpdate handles the case where notifyUpdate() fires before waitForUpdate()
+    // has been called — without it, that wakeup would be lost and the loop would sleep
+    // until the deadline unnecessarily.
+    let pendingUpdate = false;
+    let resolveUpdate = null;
+    function notifyUpdate() {
+        if (resolveUpdate) {
+            resolveUpdate();
+            resolveUpdate = null;
+        }
+        else
+            pendingUpdate = true;
+    }
+    function waitForUpdate() {
+        if (pendingUpdate) {
+            pendingUpdate = false;
+            return Promise.resolve();
+        }
+        return new Promise(res => { resolveUpdate = res; });
+    }
+    let hasSucceeded = false;
+    let successValue;
+    let failureCount = 0;
+    let rejections = []; // collected for AggregateError if all attempts fail
+    let keepRetrying = true;
+    let abortCause;
+    let isSettled = false; // true once the function has returned a result
+    function handleError(e) {
+        // First non-retryable error wins; subsequent ones are intentionally ignored since
+        // we've already decided to stop — the first abort signal is what matters.
+        if (keepRetrying) {
+            try {
+                if (!shouldRetry(e)) {
+                    keepRetrying = false;
+                    abortCause = e;
+                }
+            }
+            catch (shouldRetryException) {
+                // shouldRetry itself threw — use that exception as the cause, not the original
+                // error, since the exception from shouldRetry is the meaningful signal here.
+                keepRetrying = false;
+                abortCause = shouldRetryException;
+            }
+        }
+    }
+    function trackPromise(p) {
+        p.then((value) => {
+            if (!hasSucceeded)
+                successValue = value; // only capture the first winner
+            hasSucceeded = true;
+            notifyUpdate();
+        }).catch((e) => {
+            failureCount++;
+            rejections.push(e);
+            if (isSettled) {
+                onBackgroundError?.(e);
+                return;
+            }
+            handleError(e);
+            notifyUpdate();
+        });
+        return p;
+    }
+    function launchAttempt() {
+        try {
+            promises.push(trackPromise(generatePromise()));
+        }
+        catch (e) {
+            // generatePromise threw synchronously — route through trackPromise so that
+            // all counter increments, rejection collection, handleError, and notifyUpdate
+            // are handled consistently with the async failure path.
+            promises.push(trackPromise(Promise.reject(e)));
+        }
+    }
+    for (let i = 0; i < amount; i++) {
+        launchAttempt();
+        const deadline = Date.now() + waitTimeSeconds * 1000;
+        // deadlineSleep is created once and reused across inner loop iterations.
+        // This is intentional: a resolved promise stays resolved, so once the deadline
+        // fires it will keep winning the race and the while condition will end the loop.
+        // When waitTimeSeconds is 0, deadline === Date.now() so this loop never executes —
+        // success/failure is caught by the post-loop checks below.
+        const deadlineSleep = sleepAsync(waitTimeSeconds * 1000);
+        while (Date.now() < deadline) {
+            await Promise.race([waitForUpdate(), deadlineSleep]);
+            if (hasSucceeded) {
+                isSettled = true;
+                return successValue;
+            }
+            if (!keepRetrying) {
+                isSettled = true;
+                throw new RetryAbortedError(abortCause);
+            }
+            if (failureCount === i + 1)
+                break; // all attempts so far failed — start the next one early
+        }
+        if (hasSucceeded) {
+            isSettled = true;
+            return successValue;
+        }
+        if (!keepRetrying) {
+            isSettled = true;
+            throw new RetryAbortedError(abortCause);
+        }
+    }
+    if (!keepRetrying) {
+        isSettled = true;
+        throw new RetryAbortedError(abortCause);
+    }
+    // If every promise has already failed, throw explicitly rather than letting Promise.any
+    // throw an AggregateError opaquely — keeps the error contract consistent and deliberate.
+    if (failureCount === promises.length) {
+        isSettled = true;
+        throw new AggregateError(rejections, 'racePromises: all attempts failed.');
+    }
+    // Some promises are still in-flight. We await rather than returning the promise directly
+    // so that isSettled = true is only set after a winner is known — ensuring any rejections
+    // that arrive after that point are correctly routed to onBackgroundError.
+    // If Promise.any rejects (all in-flight promises ultimately fail), apply our own error
+    // contract: RetryAbortedError if shouldRetry fired, otherwise our custom AggregateError.
+    // This also covers waitTimeSeconds=0, where all attempts launch synchronously before any
+    // .catch() handlers run, so the pre-loop explicit checks above are never reached.
+    try {
+        const winner = await Promise.any(promises);
+        isSettled = true;
+        return winner;
+    }
+    catch (_) {
+        isSettled = true;
+        if (!keepRetrying)
+            throw new RetryAbortedError(abortCause);
+        throw new AggregateError(rejections, 'racePromises: all attempts failed.');
+    }
+}
+// exported for convenience — consider moving to a shared utilities module if you use it elsewhere
+export const sleepAsync = (ms) => new Promise(resolve => setTimeout(resolve, ms));

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@pico-brief/race-promises",
+  "version": "1.0.0",
+  "description": "Async task runner with staggered retries and parallel racing",
+  "type": "module",
+  "main": "./dist/racePromises.js",
+  "types": "./dist/racePromises.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/racePromises.js",
+      "types": "./dist/racePromises.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test racePromises.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "retry",
+    "race",
+    "promises",
+    "async",
+    "llm"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "typescript": "^5.0.0"
+  }
+}