better-race 0.1.0 → 0.2.0

package/README.md

@@ -5,10 +5,10 @@
 [![CI](https://github.com/lumberjacque/better-race/actions/workflows/ci.yml/badge.svg)](https://github.com/lumberjacque/better-race/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/better-race?logo=npm&label=npm&color=cb3837)](https://www.npmjs.com/package/better-race)
 [![npm downloads](https://img.shields.io/npm/dw/better-race?logo=npm&label=downloads)](https://www.npmjs.com/package/better-race)
-[![coverage: 100%](https://img.shields.io/badge/coverage-100%25-21c55d?logo=vitest&logoColor=white)](#quality-checks)
+[![coverage: 100%](https://img.shields.io/badge/coverage-100%25-21c55d?logo=vitest&logoColor=white)](https://github.com/lumberjacque/better-race/actions/workflows/ci.yml)
 [![TypeScript ≥5.4](https://img.shields.io/badge/TypeScript-%E2%89%A55.4-3178c6?logo=typescript&logoColor=white)](#public-types)
 [![Node ≥22](https://img.shields.io/badge/Node-%E2%89%A522-339933?logo=nodedotjs&logoColor=white)](#installation)
-[![minzipped size](https://img.shields.io/bundlephobia/minzip/better-race?label=minzipped)](https://bundlephobia.com/package/better-race)
+[![tree-shaken bundle size](https://deno.bundlejs.com/badge?q=better-race&treeshake=%5B%2A%5D)](https://deno.bundlejs.com/?q=better-race&treeshake=%5B%2A%5D)
 [![license: MIT](https://img.shields.io/github/license/lumberjacque/better-race)](LICENSE)
 
 `ESM-only` · `zero runtime dependencies` · `tree-shakeable` · `AbortSignal`-native
@@ -18,13 +18,16 @@
 ```ts
 import { race } from "better-race";
 
-const winner = await race({
-  cache: () => readCache(),
-  api: ({ signal }) => fetchUser({ signal }),
-});
+const winner = await race(
+  {
+    eu: ({ signal }) => fetch("https://eu.example.com/user/42", { signal }),
+    us: ({ signal }) => fetch("https://us.example.com/user/42", { signal }),
+  },
+  { abortLosers: true },
+);
 
-if (winner.key === "api") {
-  winner.value; // exactly the return type of fetchUser
+if (winner.key === "eu") {
+  winner.value; // the Response from the EU replica
 }
 ```
 
@@ -33,8 +36,8 @@ if (winner.key === "api") {
 Native `Promise.race()` returns a value union but drops its source:
 
 ```ts
-const value = await Promise.race([readCache(), fetchUser()]);
-// CachedUser | ApiUser
+const value = await Promise.race([readEuReplica(), readUsReplica()]);
+// EuUser | UsUser
 ```
 
 You can restore the source by manually wrapping every promise. `better-race` makes that wrapper the default, preserves the relation as a discriminated union, and can abort cooperative losers when that saves work.
@@ -54,30 +57,33 @@ Pass an object whose string keys name tasks. A task can return a value, a promis
 ```ts
 import { race } from "better-race";
 
-const winner = await race({
-  memory: () => memoryCache.get("user-42"),
-  replica: ({ signal }) => replicaClient.get("user-42", { signal }),
-  primary: ({ signal }) => primaryClient.get("user-42", { signal }),
-});
+const winner = await race(
+  {
+    eu: ({ signal }) => euReplica.get("user-42", { signal }),
+    us: ({ signal }) => usReplica.get("user-42", { signal }),
+    apac: ({ signal }) => apacReplica.get("user-42", { signal }),
+  },
+  { abortLosers: true },
+);
 ```
 
 The result is inferred as:
 
 ```ts
-{ key: "memory"; value: MemoryUser }
-| { key: "replica"; value: ReplicaUser }
-| { key: "primary"; value: PrimaryUser }
+{ key: "eu"; value: EuUser }
+| { key: "us"; value: UsUser }
+| { key: "apac"; value: ApacUser }
 ```
 
 Narrow the key and TypeScript narrows the value:
 
 ```ts
-if (winner.key === "memory") {
-  winner.value; // MemoryUser
-} else if (winner.key === "replica") {
-  winner.value; // ReplicaUser
+if (winner.key === "eu") {
+  winner.value; // EuUser
+} else if (winner.key === "us") {
+  winner.value; // UsUser
 } else {
-  winner.value; // PrimaryUser
+  winner.value; // ApacUser
 }
 ```
 
@@ -100,8 +106,8 @@ By default, losers keep running, exactly like `Promise.race()`:
 
 ```ts
 const winner = await race({
-  cache: readCache,
-  network: ({ signal }) => fetch("/user", { signal }),
+  eu: ({ signal }) => fetch("https://eu.example.com/user/42", { signal }),
+  us: ({ signal }) => fetch("https://us.example.com/user/42", { signal }),
 });
 ```
 
@@ -160,13 +166,107 @@ import type { RaceContext, RaceOptions, RaceResult, RaceTask, RaceTasks } from "
 
 `RaceContext` deliberately contains only `signal`. There are no framework adapters, schedulers, retries, timeouts, hooks, or hidden global state.
 
+## `raceUntil(tasks, options)`
+
+`raceUntil()` starts every task concurrently, but settles only when a fulfilled value passes `accept`. It is for “first usable result” cases where an early `null`, stale response, or unsuitable value should not end the race. It is not a replacement for a normal cache-first lookup: use it only when starting every candidate is an intentional latency or resilience trade-off.
+
+### Keyed, cancellable `Promise.any()`
+
+Use an always-accepting predicate when the first fulfilled result should win. In
+that mode, `raceUntil()` is a keyed, cancellable alternative to `Promise.any()`:
+rejections are skipped while another task can still fulfil, and the winner keeps
+its task key.
+
+```ts
+const winner = await raceUntil(
+  {
+    cache: () => readCache(),
+    api: ({ signal }) => fetchUser({ signal }),
+  },
+  { accept: () => true, abortLosers: true },
+);
+
+if (winner.key === "api") {
+  winner.value; // User
+}
+```
+
+If every task rejects, `raceUntil()` rejects with `NoAcceptedResultError`, which
+extends `AggregateError`. Unlike native `Promise.any()`, its `rejections`
+property retains each task key alongside the original rejection reason.
+
+```ts
+import { raceUntil } from "better-race";
+
+type User = { id: string };
+
+const winner = await raceUntil(
+  {
+    memory: () => memoryCache.get("user-42"), // User | null
+    redis: () => redisCache.get("user-42"), // User | null
+    database: ({ signal }) => fetchUser("user-42", { signal }), // User
+  },
+  {
+    accept: (value): value is User => value !== null,
+    abortLosers: true,
+  },
+);
+
+winner.key; // "memory" | "redis" | "database"
+winner.value; // User
+```
+
+### Semantics
+
+- All tasks start in object property order before any fulfilment, rejection, or acceptance is processed.
+- A fulfilled value for which `accept(value)` is `false` is declined; pending tasks keep racing.
+- A task rejection is recorded and ignored while another task could still provide an accepted value.
+- The first accepted value wins. With `abortLosers: true`, every pending loser receives an abort signal; otherwise it keeps running.
+- If every task settles without an accepted value, `raceUntil()` rejects with `NoAcceptedResultError`.
+- If `accept` throws, `raceUntil()` rejects with that exact error. External abort behaves exactly like `race()` and aborts all pending tasks with the caller’s original `signal.reason`.
+
+`NoAcceptedResultError` extends `AggregateError`. Its `errors` array retains original rejection reasons, and its `rejections` property keeps each reason coupled to the task key:
+
+```ts
+try {
+  await raceUntil(tasks, { accept: isUsable });
+} catch (error) {
+  if (error instanceof NoAcceptedResultError) {
+    error.rejections; // readonly { key: string; reason: unknown }[]
+  }
+}
+```
+
+### Type narrowing
+
+Use an explicit type predicate when the result must be narrowed on TypeScript 5.4 and newer:
+
+```ts
+accept: (value): value is User => value !== null;
+```
+
+A plain boolean callback is always valid, but preserves each task’s original value type. The keyed relationship remains intact in both forms.
+
+### Public types
+
+```ts
+import {
+  NoAcceptedResultError,
+  raceUntil,
+  type RaceUntilOptions,
+  type RaceUntilRejection,
+  type RaceUntilResult,
+} from "better-race";
+```
+
 ## Use cases
 
-- Read from a memory cache, distributed cache, and primary store simultaneously.
+- Query independent read replicas when lower tail latency is worth redundant read work.
 - Query independent replicas and return the fastest response.
 - Race a preferred endpoint against a fallback endpoint, then abort the fallback.
 - Preserve source information for metrics, tracing, or structured logging.
 - Write compact TypeScript that narrows the result without hand-written wrapper objects.
+- Query several stores in parallel until one returns a usable, non-null record.
 
 ## Examples
 
@@ -176,6 +276,7 @@ The executable examples are in [`examples/`](./examples):
 - [`abort-losers.ts`](./examples/abort-losers.ts)
 - [`external-abort.ts`](./examples/external-abort.ts)
 - [`rejection-semantics.ts`](./examples/rejection-semantics.ts)
+- [`until-accepted-result.ts`](./examples/until-accepted-result.ts)
 
 CI compiles and executes these examples against the packed package, not the source tree.
 
@@ -184,20 +285,39 @@ CI compiles and executes these examples against the packed package, not the sour
 A race is not a dependency graph: every task starts immediately. The important moment is the first settlement.
 
 ```text
-Race Timeline — cache wins with abortLosers: true
+Race Timeline — EU replica wins with abortLosers: true
 
 Task       │ 0ms                 72ms                                  400ms
 ───────────┼─────────────────────┼──────────────────────────────────────────
-cache      │ ███████████████████ ● fulfilled winner
-api        │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ × abort signal received
-replica    │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ × abort signal received
+eu         │ ███████████████████ ● fulfilled winner
+us         │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ × abort signal received
+apac       │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ × abort signal received
                               ↑
                        first settlement wins
 
 Legend: █ active fulfilled work · ▓ active rejected work · ▒ active work aborted by the race
 ```
 
-Open [`playground/race-lab.html`](./playground/race-lab.html) directly in a browser to explore an animated version. It contains four concrete scenarios: fulfilment, first rejection, continuing losers, and external abort. The page is a visual prototype, not a shipped package artifact; Vitest and the packed-consumer test verify the runtime contract.
+`raceUntil()` keeps the same concurrent start, but the line marks the first **accepted** value rather than the first settlement:
+
+```text
+RaceUntil Timeline — wait for an accepted result
+
+Task       │ Outcome          │ Decision                    │ Timeline
+───────────┼──────────────────┼─────────────────────────────┼────────────────────────────────────
+memory     │ null @ 24ms      │ accept → false · decline    │ ███ ▧ declined
+redis      │ Error @ 68ms     │ record rejection · continue │ ████████ ▓ recorded
+database   │ User @ 176ms     │ accept → true · winner      │ ██████████████████████ ● accepted
+backup     │ pending @ 176ms  │ abortLosers → abort          │ ██████████████████████ ▒ cancelled
+
+Legend: █ active task work · ▧ fulfilled candidate declined by accept · ▓ recorded rejection · ● accepted winner · ▒ cancelled loser
+```
+
+Open [`playground/race-lab.html`](./playground/race-lab.html) directly in a browser to explore an animated version. It contains concrete `race()` and `raceUntil()` scenarios; the page is a visual prototype, not a shipped package artifact. Vitest and the packed-consumer test verify the runtime contract.
+
+## Quality checks
+
+The [CI workflow](https://github.com/lumberjacque/better-race/actions/workflows/ci.yml) runs the V8 coverage report on Node 22, 24, and 26. The configured threshold is exactly 100% for statements, branches, functions, and lines, so a green CI run is a verifiable guarantee rather than a decorative badge. Open the latest `Node 22` job to inspect its full report.
 
 ## Development
 

package/dist/index.d.mts

@@ -1,3 +1,21 @@
+//#region src/errors.d.ts
+/** A task rejection recorded while a `raceUntil()` call kept looking for an accepted value. */
+interface RaceUntilRejection {
+  /** The task whose promise rejected. */
+  readonly key: string;
+  /** The original rejection reason from that task. */
+  readonly reason: unknown;
+}
+/**
+ * Thrown when every `raceUntil()` task has settled but no fulfilled value was
+ * accepted. Rejections are preserved in both `errors` and `rejections`.
+ */
+export declare class NoAcceptedResultError extends AggregateError {
+  /** The rejected tasks, including their keys and original reasons. */
+  readonly rejections: readonly RaceUntilRejection[];
+  constructor(rejections: readonly RaceUntilRejection[]);
+}
+//#endregion
 //#region src/types.d.ts
 /** Context supplied to every task in a race. */
 interface RaceContext {
@@ -25,6 +43,11 @@ interface RaceOptions {
    */
   readonly abortLosers?: boolean;
 }
+/** Options that control which fulfilled values may win a {@link raceUntil}. */
+interface RaceUntilOptions<TValue = unknown> extends RaceOptions {
+  /** Returns `true` when this fulfilled value should win the race. */
+  readonly accept: (value: TValue) => boolean;
+}
 type StringKeyOf<T> = Extract<keyof T, string>;
 /**
  * The discriminated union returned by {@link race}. Narrowing `key` narrows
@@ -36,6 +59,16 @@ type RaceResult<T extends RaceTasks> = { [K in StringKeyOf<T>]: {
 }; }[StringKeyOf<T>];
 /** @internal Rejects an empty object at compile time. */
 type NonEmptyTasks<T extends RaceTasks> = keyof T extends never ? never : T;
+/** The union of all values that tasks in a race can fulfil with. */
+type RaceValue<T extends RaceTasks> = Awaited<ReturnType<T[StringKeyOf<T>]>>;
+/**
+ * The keyed result returned by {@link raceUntil} when `accept` is a type
+ * predicate. Each task value is narrowed independently while keeping its key.
+ */
+type RaceUntilResult<T extends RaceTasks, Accepted> = { [K in StringKeyOf<T>]: {
+  readonly key: K;
+  readonly value: Extract<Awaited<ReturnType<T[K]>>, Accepted>;
+}; }[StringKeyOf<T>];
 //#endregion
 //#region src/race.d.ts
 /**
@@ -66,5 +99,28 @@ type NonEmptyTasks<T extends RaceTasks> = keyof T extends never ? never : T;
  */
 export declare function race<const T extends RaceTasks>(tasks: NonEmptyTasks<T>, options?: RaceOptions): Promise<RaceResult<T>>;
 //#endregion
-export type { RaceContext, RaceOptions, RaceResult, RaceTask, RaceTasks };
+//#region src/race-until.d.ts
+type TypeGuardOptions<TValue, Accepted extends TValue> = RaceUntilOptions<TValue> & {
+  readonly accept: (value: TValue) => value is Accepted;
+};
+/**
+ * Races named tasks until a fulfilled value is accepted.
+ *
+ * Every task starts in object property order before any settlement is
+ * processed. Fulfilled values that `accept` rejects and task rejections are
+ * ignored while pending tasks remain. The first accepted value resolves with
+ * its keyed result. When every task settles without an accepted value, the
+ * promise rejects with {@link NoAcceptedResultError}.
+ *
+ * A type-predicate `accept` function narrows each keyed value in the result.
+ * Set `abortLosers` to abort cooperative pending tasks after acceptance; pass
+ * `signal` to cancel the whole pending race externally.
+ *
+ * @throws {TypeError} When `tasks` is empty or contains a non-function value.
+ * @throws {NoAcceptedResultError} When no fulfilled value is accepted.
+ */
+export declare function raceUntil<const T extends RaceTasks, Accepted extends RaceValue<T>>(tasks: NonEmptyTasks<T>, options: TypeGuardOptions<RaceValue<T>, Accepted>): Promise<RaceUntilResult<T, Accepted>>;
+export declare function raceUntil<const T extends RaceTasks>(tasks: NonEmptyTasks<T>, options: RaceUntilOptions<RaceValue<T>>): Promise<RaceResult<T>>;
+//#endregion
+export type { RaceContext, RaceOptions, RaceResult, RaceTask, RaceTasks, RaceUntilOptions, RaceUntilRejection, RaceUntilResult, RaceValue };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/race.ts"],"mappings":";;UACiB;;;;;WAKN,QAAQ;;;KAIP,SAAS,MAAM,SAAS,gBAAgB,IAAI,YAAY;;KAGxD,YAAY,SAAS,eAAe;;UAG/B;;;;;;WAMN,SAAS;;;;;WAMT;;KAGN,YAAY,KAAK,cAAc;;;;;KAMxB,WAAW,UAAU,gBAC9B,KAAK,YAAY;WACP,KAAK;WACL,OAAO,QAAQ,WAAW,EAAE;KAEvC,YAAY;;KAGF,cAAc,UAAU,mBAAmB,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBCRjE,WAAW,UAAU,WACnC,OAAO,cAAc,IACrB,UAAS,cACR,QAAQ,WAAW"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/errors.ts","../src/types.ts","../src/race.ts","../src/race-until.ts"],"mappings":";;UACiB;;WAEN;;WAGA;;;;;;qBAOE,8BAA8B;;WAEhC,qBAAqB;EAElB,YAAA,qBAAqB;;;;;UChBlB;;;;;WAKN,QAAQ;;;KAIP,SAAS,MAAM,SAAS,gBAAgB,IAAI,YAAY;;KAGxD,YAAY,SAAS,eAAe;;UAG/B;;;;;;WAMN,SAAS;;;;;WAMT;;;UAGM,iBAAiB,0BAA0B;;WAEjD,SAAS,OAAO;;KAGtB,YAAY,KAAK,cAAc;;;;;KAMxB,WAAW,UAAU,gBAC9B,KAAK,YAAY;WACP,KAAK;WACL,OAAO,QAAQ,WAAW,EAAE;KAEvC,YAAY;;KAGF,cAAc,UAAU,mBAAmB,0BAA0B;;KAErE,UAAU,UAAU,aAAa,QAAQ,WAAW,EAAE,YAAY;;;;;KAMlE,gBAAgB,UAAU,WAAW,eAC9C,KAAK,YAAY;WACP,KAAK;WACL,OAAO,QAAQ,QAAQ,WAAW,EAAE,MAAM;KAErD,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBC1BE,WAAW,UAAU,WACnC,OAAO,cAAc,IACrB,UAAS,cACR,QAAQ,WAAW;;;KC1BjB,iBAAiB,QAAQ,iBAAiB,UAAU,iBAAiB;WAC/D,SAAS,OAAO,WAAW,SAAS;;;;;;;;;;;;;;;;;;wBAmB/B,gBAAgB,UAAU,WAAW,iBAAiB,UAAU,IAC9E,OAAO,cAAc,IACrB,SAAS,iBAAiB,UAAU,IAAI,YACvC,QAAQ,gBAAgB,GAAG;wBACd,gBAAgB,UAAU,WACxC,OAAO,cAAc,IACrB,SAAS,iBAAiB,UAAU,MACnC,QAAQ,WAAW"}

package/dist/index.mjs

@@ -1,3 +1,18 @@
+//#region src/errors.ts
+/**
+* Thrown when every `raceUntil()` task has settled but no fulfilled value was
+* accepted. Rejections are preserved in both `errors` and `rejections`.
+*/
+var NoAcceptedResultError = class extends AggregateError {
+	/** The rejected tasks, including their keys and original reasons. */
+	rejections;
+	constructor(rejections) {
+		super(rejections.map(({ reason }) => reason), "raceUntil() completed without an accepted result.");
+		this.name = "NoAcceptedResultError";
+		this.rejections = rejections;
+	}
+};
+//#endregion
 //#region src/race.ts
 /**
 * Races named tasks and returns both the first settled task's key and value.
@@ -70,6 +85,77 @@ function race(tasks, options = {}) {
 	});
 }
 //#endregion
-export { race };
+//#region src/race-until.ts
+function raceUntil(tasks, options) {
+	const entries = Object.entries(tasks);
+	if (entries.length === 0) throw new TypeError("raceUntil() requires at least one task.");
+	for (const [key, task] of entries) if (typeof task !== "function") throw new TypeError(`raceUntil() task "${key}" must be a function.`);
+	if (options.signal?.aborted) return Promise.reject(options.signal.reason);
+	const controllers = new Map(entries.map(([key]) => [key, new AbortController()]));
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		let remaining = entries.length;
+		const rejections = [];
+		const cleanup = () => {
+			options.signal?.removeEventListener("abort", onExternalAbort);
+		};
+		const abortTasks = (winnerKey) => {
+			for (const [key, controller] of controllers) if (key !== winnerKey) controller.abort();
+		};
+		const settleAccepted = (key, value) => {
+			settled = true;
+			cleanup();
+			if (options.abortLosers) abortTasks(key);
+			resolve({
+				key,
+				value
+			});
+		};
+		const settleFailure = (reason) => {
+			settled = true;
+			cleanup();
+			reject(reason);
+		};
+		const settleWithoutAcceptedValue = () => {
+			settled = true;
+			cleanup();
+			reject(new NoAcceptedResultError(rejections));
+		};
+		const onExternalAbort = () => {
+			settled = true;
+			cleanup();
+			abortTasks();
+			reject(options.signal?.reason);
+		};
+		options.signal?.addEventListener("abort", onExternalAbort, { once: true });
+		for (const [key, task] of entries) {
+			const context = { signal: controllers.get(key).signal };
+			Promise.resolve().then(() => task(context)).then((value) => {
+				if (settled) return;
+				try {
+					if (options.accept(value)) {
+						settleAccepted(key, value);
+						return;
+					}
+				} catch (reason) {
+					settleFailure(reason);
+					return;
+				}
+				remaining -= 1;
+				if (remaining === 0) settleWithoutAcceptedValue();
+			}, (reason) => {
+				if (settled) return;
+				rejections.push({
+					key,
+					reason
+				});
+				remaining -= 1;
+				if (remaining === 0) settleWithoutAcceptedValue();
+			});
+		}
+	});
+}
+//#endregion
+export { NoAcceptedResultError, race, raceUntil };
 
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/race.ts"],"sourcesContent":["import type {\n  NonEmptyTasks,\n  RaceContext,\n  RaceOptions,\n  RaceResult,\n  RaceTask,\n  RaceTasks,\n} from \"./types.js\";\n\ntype TaskEntry<T extends RaceTasks> = readonly [Extract<keyof T, string>, RaceTask<unknown>];\n\n/**\n * Races named tasks and returns both the first settled task's key and value.\n *\n * All tasks are started in object property order before any settlement is\n * processed. The first task to fulfil resolves with its keyed result; the\n * first task to reject rejects with its original reason, just like\n * `Promise.race()`.\n *\n * Set `abortLosers` to abort cooperative losers after the race settles. Pass\n * `signal` to cancel a still-pending race externally. A task must use the\n * supplied `AbortSignal` for cancellation to stop its underlying work.\n *\n * @example\n * ```ts\n * const winner = await race({\n *   cache: () => readCache(),\n *   api: ({ signal }) => fetchUser({ signal }),\n * });\n *\n * if (winner.key === \"api\") {\n *   winner.value; // inferred from fetchUser\n * }\n * ```\n *\n * @throws {TypeError} When `tasks` is empty or contains a non-function value.\n */\nexport function race<const T extends RaceTasks>(\n  tasks: NonEmptyTasks<T>,\n  options: RaceOptions = {},\n): Promise<RaceResult<T>> {\n  const entries = Object.entries(tasks) as unknown as TaskEntry<T>[];\n\n  if (entries.length === 0) {\n    throw new TypeError(\"race() requires at least one task.\");\n  }\n\n  for (const [key, task] of entries) {\n    if (typeof task !== \"function\") {\n      throw new TypeError(`race() task \"${key}\" must be a function.`);\n    }\n  }\n\n  if (options.signal?.aborted) {\n    return Promise.reject(options.signal.reason);\n  }\n\n  const controllers = new Map<string, AbortController>(\n    entries.map(([key]) => [key, new AbortController()]),\n  );\n\n  return new Promise<RaceResult<T>>((resolve, reject) => {\n    let settled = false;\n\n    const cleanup = (): void => {\n      options.signal?.removeEventListener(\"abort\", onExternalAbort);\n    };\n\n    const abortTasks = (winnerKey?: string): void => {\n      for (const [key, controller] of controllers) {\n        if (key !== winnerKey) {\n          controller.abort();\n        }\n      }\n    };\n\n    const settleFulfilled = (key: string, value: unknown): void => {\n      if (settled) return;\n\n      settled = true;\n      cleanup();\n      if (options.abortLosers) abortTasks(key);\n      resolve({ key, value } as RaceResult<T>);\n    };\n\n    const settleRejected = (key: string, reason: unknown): void => {\n      if (settled) return;\n\n      settled = true;\n      cleanup();\n      if (options.abortLosers) abortTasks(key);\n      reject(reason);\n    };\n\n    const onExternalAbort = (): void => {\n      settled = true;\n      cleanup();\n      abortTasks();\n      reject(options.signal?.reason);\n    };\n\n    options.signal?.addEventListener(\"abort\", onExternalAbort, { once: true });\n\n    for (const [key, task] of entries) {\n      const controller = controllers.get(key)!;\n\n      const context: RaceContext = { signal: controller.signal };\n      Promise.resolve()\n        .then(() => task(context))\n        .then(\n          (value) => settleFulfilled(key, value),\n          (reason: unknown) => settleRejected(key, reason),\n        );\n    }\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,SAAgB,KACd,OACA,UAAuB,CAAC,GACA;CACxB,MAAM,UAAU,OAAO,QAAQ,KAAK;CAEpC,IAAI,QAAQ,WAAW,GACrB,MAAM,IAAI,UAAU,oCAAoC;CAG1D,KAAK,MAAM,CAAC,KAAK,SAAS,SACxB,IAAI,OAAO,SAAS,YAClB,MAAM,IAAI,UAAU,gBAAgB,IAAI,sBAAsB;CAIlE,IAAI,QAAQ,QAAQ,SAClB,OAAO,QAAQ,OAAO,QAAQ,OAAO,MAAM;CAG7C,MAAM,cAAc,IAAI,IACtB,QAAQ,KAAK,CAAC,SAAS,CAAC,KAAK,IAAI,gBAAgB,CAAC,CAAC,CACrD;CAEA,OAAO,IAAI,SAAwB,SAAS,WAAW;EACrD,IAAI,UAAU;EAEd,MAAM,gBAAsB;GAC1B,QAAQ,QAAQ,oBAAoB,SAAS,eAAe;EAC9D;EAEA,MAAM,cAAc,cAA6B;GAC/C,KAAK,MAAM,CAAC,KAAK,eAAe,aAC9B,IAAI,QAAQ,WACV,WAAW,MAAM;EAGvB;EAEA,MAAM,mBAAmB,KAAa,UAAyB;GAC7D,IAAI,SAAS;GAEb,UAAU;GACV,QAAQ;GACR,IAAI,QAAQ,aAAa,WAAW,GAAG;GACvC,QAAQ;IAAE;IAAK;GAAM,CAAkB;EACzC;EAEA,MAAM,kBAAkB,KAAa,WAA0B;GAC7D,IAAI,SAAS;GAEb,UAAU;GACV,QAAQ;GACR,IAAI,QAAQ,aAAa,WAAW,GAAG;GACvC,OAAO,MAAM;EACf;EAEA,MAAM,wBAA8B;GAClC,UAAU;GACV,QAAQ;GACR,WAAW;GACX,OAAO,QAAQ,QAAQ,MAAM;EAC/B;EAEA,QAAQ,QAAQ,iBAAiB,SAAS,iBAAiB,EAAE,MAAM,KAAK,CAAC;EAEzE,KAAK,MAAM,CAAC,KAAK,SAAS,SAAS;GAGjC,MAAM,UAAuB,EAAE,QAFZ,YAAY,IAAI,GAEa,CAAC,CAAC,OAAO;GACzD,QAAQ,QAAQ,CAAC,CACd,WAAW,KAAK,OAAO,CAAC,CAAC,CACzB,MACE,UAAU,gBAAgB,KAAK,KAAK,IACpC,WAAoB,eAAe,KAAK,MAAM,CACjD;EACJ;CACF,CAAC;AACH"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/errors.ts","../src/race.ts","../src/race-until.ts"],"sourcesContent":["/** A task rejection recorded while a `raceUntil()` call kept looking for an accepted value. */\nexport interface RaceUntilRejection {\n  /** The task whose promise rejected. */\n  readonly key: string;\n\n  /** The original rejection reason from that task. */\n  readonly reason: unknown;\n}\n\n/**\n * Thrown when every `raceUntil()` task has settled but no fulfilled value was\n * accepted. Rejections are preserved in both `errors` and `rejections`.\n */\nexport class NoAcceptedResultError extends AggregateError {\n  /** The rejected tasks, including their keys and original reasons. */\n  readonly rejections: readonly RaceUntilRejection[];\n\n  constructor(rejections: readonly RaceUntilRejection[]) {\n    super(\n      rejections.map(({ reason }) => reason),\n      \"raceUntil() completed without an accepted result.\",\n    );\n    this.name = \"NoAcceptedResultError\";\n    this.rejections = rejections;\n  }\n}\n","import type {\n  NonEmptyTasks,\n  RaceContext,\n  RaceOptions,\n  RaceResult,\n  RaceTask,\n  RaceTasks,\n} from \"./types.js\";\n\ntype TaskEntry<T extends RaceTasks> = readonly [Extract<keyof T, string>, RaceTask<unknown>];\n\n/**\n * Races named tasks and returns both the first settled task's key and value.\n *\n * All tasks are started in object property order before any settlement is\n * processed. The first task to fulfil resolves with its keyed result; the\n * first task to reject rejects with its original reason, just like\n * `Promise.race()`.\n *\n * Set `abortLosers` to abort cooperative losers after the race settles. Pass\n * `signal` to cancel a still-pending race externally. A task must use the\n * supplied `AbortSignal` for cancellation to stop its underlying work.\n *\n * @example\n * ```ts\n * const winner = await race({\n *   cache: () => readCache(),\n *   api: ({ signal }) => fetchUser({ signal }),\n * });\n *\n * if (winner.key === \"api\") {\n *   winner.value; // inferred from fetchUser\n * }\n * ```\n *\n * @throws {TypeError} When `tasks` is empty or contains a non-function value.\n */\nexport function race<const T extends RaceTasks>(\n  tasks: NonEmptyTasks<T>,\n  options: RaceOptions = {},\n): Promise<RaceResult<T>> {\n  const entries = Object.entries(tasks) as unknown as TaskEntry<T>[];\n\n  if (entries.length === 0) {\n    throw new TypeError(\"race() requires at least one task.\");\n  }\n\n  for (const [key, task] of entries) {\n    if (typeof task !== \"function\") {\n      throw new TypeError(`race() task \"${key}\" must be a function.`);\n    }\n  }\n\n  if (options.signal?.aborted) {\n    return Promise.reject(options.signal.reason);\n  }\n\n  const controllers = new Map<string, AbortController>(\n    entries.map(([key]) => [key, new AbortController()]),\n  );\n\n  return new Promise<RaceResult<T>>((resolve, reject) => {\n    let settled = false;\n\n    const cleanup = (): void => {\n      options.signal?.removeEventListener(\"abort\", onExternalAbort);\n    };\n\n    const abortTasks = (winnerKey?: string): void => {\n      for (const [key, controller] of controllers) {\n        if (key !== winnerKey) {\n          controller.abort();\n        }\n      }\n    };\n\n    const settleFulfilled = (key: string, value: unknown): void => {\n      if (settled) return;\n\n      settled = true;\n      cleanup();\n      if (options.abortLosers) abortTasks(key);\n      resolve({ key, value } as RaceResult<T>);\n    };\n\n    const settleRejected = (key: string, reason: unknown): void => {\n      if (settled) return;\n\n      settled = true;\n      cleanup();\n      if (options.abortLosers) abortTasks(key);\n      reject(reason);\n    };\n\n    const onExternalAbort = (): void => {\n      settled = true;\n      cleanup();\n      abortTasks();\n      reject(options.signal?.reason);\n    };\n\n    options.signal?.addEventListener(\"abort\", onExternalAbort, { once: true });\n\n    for (const [key, task] of entries) {\n      const controller = controllers.get(key)!;\n\n      const context: RaceContext = { signal: controller.signal };\n      Promise.resolve()\n        .then(() => task(context))\n        .then(\n          (value) => settleFulfilled(key, value),\n          (reason: unknown) => settleRejected(key, reason),\n        );\n    }\n  });\n}\n","import { NoAcceptedResultError, type RaceUntilRejection } from \"./errors.js\";\nimport type {\n  NonEmptyTasks,\n  RaceContext,\n  RaceResult,\n  RaceTask,\n  RaceTasks,\n  RaceUntilOptions,\n  RaceUntilResult,\n  RaceValue,\n} from \"./types.js\";\n\ntype TaskEntry<T extends RaceTasks> = readonly [Extract<keyof T, string>, RaceTask<unknown>];\n\ntype TypeGuardOptions<TValue, Accepted extends TValue> = RaceUntilOptions<TValue> & {\n  readonly accept: (value: TValue) => value is Accepted;\n};\n\n/**\n * Races named tasks until a fulfilled value is accepted.\n *\n * Every task starts in object property order before any settlement is\n * processed. Fulfilled values that `accept` rejects and task rejections are\n * ignored while pending tasks remain. The first accepted value resolves with\n * its keyed result. When every task settles without an accepted value, the\n * promise rejects with {@link NoAcceptedResultError}.\n *\n * A type-predicate `accept` function narrows each keyed value in the result.\n * Set `abortLosers` to abort cooperative pending tasks after acceptance; pass\n * `signal` to cancel the whole pending race externally.\n *\n * @throws {TypeError} When `tasks` is empty or contains a non-function value.\n * @throws {NoAcceptedResultError} When no fulfilled value is accepted.\n */\nexport function raceUntil<const T extends RaceTasks, Accepted extends RaceValue<T>>(\n  tasks: NonEmptyTasks<T>,\n  options: TypeGuardOptions<RaceValue<T>, Accepted>,\n): Promise<RaceUntilResult<T, Accepted>>;\nexport function raceUntil<const T extends RaceTasks>(\n  tasks: NonEmptyTasks<T>,\n  options: RaceUntilOptions<RaceValue<T>>,\n): Promise<RaceResult<T>>;\nexport function raceUntil<const T extends RaceTasks>(\n  tasks: NonEmptyTasks<T>,\n  options: RaceUntilOptions<RaceValue<T>>,\n): Promise<RaceResult<T>> {\n  const entries = Object.entries(tasks) as unknown as TaskEntry<T>[];\n\n  if (entries.length === 0) {\n    throw new TypeError(\"raceUntil() requires at least one task.\");\n  }\n\n  for (const [key, task] of entries) {\n    if (typeof task !== \"function\") {\n      throw new TypeError(`raceUntil() task \"${key}\" must be a function.`);\n    }\n  }\n\n  if (options.signal?.aborted) {\n    return Promise.reject(options.signal.reason);\n  }\n\n  const controllers = new Map<string, AbortController>(\n    entries.map(([key]) => [key, new AbortController()]),\n  );\n\n  return new Promise<RaceResult<T>>((resolve, reject) => {\n    let settled = false;\n    let remaining = entries.length;\n    const rejections: RaceUntilRejection[] = [];\n\n    const cleanup = (): void => {\n      options.signal?.removeEventListener(\"abort\", onExternalAbort);\n    };\n\n    const abortTasks = (winnerKey?: string): void => {\n      for (const [key, controller] of controllers) {\n        if (key !== winnerKey) controller.abort();\n      }\n    };\n\n    const settleAccepted = (key: string, value: unknown): void => {\n      settled = true;\n      cleanup();\n      if (options.abortLosers) abortTasks(key);\n      resolve({ key, value } as RaceResult<T>);\n    };\n\n    const settleFailure = (reason: unknown): void => {\n      settled = true;\n      cleanup();\n      reject(reason);\n    };\n\n    const settleWithoutAcceptedValue = (): void => {\n      settled = true;\n      cleanup();\n      reject(new NoAcceptedResultError(rejections));\n    };\n\n    const onExternalAbort = (): void => {\n      settled = true;\n      cleanup();\n      abortTasks();\n      reject(options.signal?.reason);\n    };\n\n    options.signal?.addEventListener(\"abort\", onExternalAbort, { once: true });\n\n    for (const [key, task] of entries) {\n      const controller = controllers.get(key)!;\n      const context: RaceContext = { signal: controller.signal };\n\n      Promise.resolve()\n        .then(() => task(context))\n        .then(\n          (value) => {\n            if (settled) return;\n\n            try {\n              if (options.accept(value as RaceValue<T>)) {\n                settleAccepted(key, value);\n                return;\n              }\n            } catch (reason) {\n              settleFailure(reason);\n              return;\n            }\n\n            remaining -= 1;\n            if (remaining === 0) settleWithoutAcceptedValue();\n          },\n          (reason: unknown) => {\n            if (settled) return;\n\n            rejections.push({ key, reason });\n            remaining -= 1;\n            if (remaining === 0) settleWithoutAcceptedValue();\n          },\n        );\n    }\n  });\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-race",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A better Promise.race() for TypeScript: keyed results and optional cancellation.",
   "keywords": [
     "abortsignal",