better-race 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShimG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# better-race
+
+> A better `Promise.race()` for TypeScript: keyed results, precise narrowing, and optional cooperative cancellation.
+
+[![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)
+[![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)
+[![license: MIT](https://img.shields.io/github/license/lumberjacque/better-race)](LICENSE)
+
+`ESM-only` · `zero runtime dependencies` · `tree-shakeable` · `AbortSignal`-native
+
+`Promise.race()` tells you the first value that settled. `better-race` also tells you **which task produced it**, while keeping that key and value connected in TypeScript.
+
+```ts
+import { race } from "better-race";
+
+const winner = await race({
+  cache: () => readCache(),
+  api: ({ signal }) => fetchUser({ signal }),
+});
+
+if (winner.key === "api") {
+  winner.value; // exactly the return type of fetchUser
+}
+```
+
+## Why?
+
+Native `Promise.race()` returns a value union but drops its source:
+
+```ts
+const value = await Promise.race([readCache(), fetchUser()]);
+// CachedUser | ApiUser
+```
+
+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.
+
+## Installation
+
+```sh
+npm install better-race
+```
+
+`better-race` is ESM-only, targets ES2022, and supports Node.js 22 or newer. It is framework-agnostic: it uses only promises and the standard `AbortSignal` API.
+
+## `race(tasks, options?)`
+
+Pass an object whose string keys name tasks. A task can return a value, a promise, or any `PromiseLike` value. It receives a context containing an `AbortSignal`, which it may ignore.
+
+```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 }),
+});
+```
+
+The result is inferred as:
+
+```ts
+{ key: "memory"; value: MemoryUser }
+| { key: "replica"; value: ReplicaUser }
+| { key: "primary"; value: PrimaryUser }
+```
+
+Narrow the key and TypeScript narrows the value:
+
+```ts
+if (winner.key === "memory") {
+  winner.value; // MemoryUser
+} else if (winner.key === "replica") {
+  winner.value; // ReplicaUser
+} else {
+  winner.value; // PrimaryUser
+}
+```
+
+### Semantics
+
+`race()` intentionally follows the mental model of `Promise.race()`.
+
+- Every task starts in object property order before any settlement is processed.
+- The first task to settle wins, whether it fulfils or rejects.
+- A first rejection rejects with the **original reason**; it is never wrapped.
+- A synchronous task result works. A synchronous throw becomes a rejected race.
+- `race({})` is rejected at the call site with a clear `TypeError`; TypeScript also rejects it.
+- Only own, enumerable string keys are considered.
+
+There is no priority system. Property order defines predictable startup order only—not a tie-breaker.
+
+### Optional loser cancellation
+
+By default, losers keep running, exactly like `Promise.race()`:
+
+```ts
+const winner = await race({
+  cache: readCache,
+  network: ({ signal }) => fetch("/user", { signal }),
+});
+```
+
+Set `abortLosers: true` to abort every still-running loser after the first settlement, including when the winning task rejects:
+
+```ts
+const winner = await race(
+  {
+    primary: ({ signal }) => fetch("/primary", { signal }),
+    backup: ({ signal }) => fetch("/backup", { signal }),
+  },
+  { abortLosers: true },
+);
+```
+
+Cancellation is cooperative. Passing a signal does not magically stop synchronous CPU work or code that ignores it. `fetch`, many database clients, and your own signal-aware functions can react to it.
+
+The winning task's signal is never aborted by `abortLosers`.
+
+### External cancellation
+
+Pass a caller-owned signal to stop a pending race:
+
+```ts
+const controller = new AbortController();
+
+const winner = await race(
+  {
+    primary: ({ signal }) => fetch("/primary", { signal }),
+    backup: ({ signal }) => fetch("/backup", { signal }),
+  },
+  { signal: controller.signal, abortLosers: true },
+);
+
+controller.abort(new Error("User navigated away"));
+```
+
+If the external signal is already aborted, no task starts. If it aborts while the race is pending, every task signal is aborted and the returned promise rejects with the exact `signal.reason`.
+
+Once a task wins, the external listener is removed. With the default `abortLosers: false`, an external abort later does **not** retroactively cancel a loser that was deliberately allowed to continue.
+
+### Options
+
+```ts
+interface RaceOptions {
+  signal?: AbortSignal;
+  abortLosers?: boolean; // false by default
+}
+```
+
+### Public types
+
+```ts
+import type { RaceContext, RaceOptions, RaceResult, RaceTask, RaceTasks } from "better-race";
+```
+
+`RaceContext` deliberately contains only `signal`. There are no framework adapters, schedulers, retries, timeouts, hooks, or hidden global state.
+
+## Use cases
+
+- Read from a memory cache, distributed cache, and primary store simultaneously.
+- 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.
+
+## Examples
+
+The executable examples are in [`examples/`](./examples):
+
+- [`basic-keyed-result.ts`](./examples/basic-keyed-result.ts)
+- [`abort-losers.ts`](./examples/abort-losers.ts)
+- [`external-abort.ts`](./examples/external-abort.ts)
+- [`rejection-semantics.ts`](./examples/rejection-semantics.ts)
+
+CI compiles and executes these examples against the packed package, not the source tree.
+
+## Visual semantics
+
+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
+
+Task       │ 0ms                 72ms                                  400ms
+───────────┼─────────────────────┼──────────────────────────────────────────
+cache      │ ███████████████████ ● fulfilled winner
+api        │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ × abort signal received
+replica    │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ × 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.
+
+## Development
+
+```sh
+npm install
+npm run verify
+```
+
+`verify` runs formatting, linting, typechecking, 100% runtime coverage, type tests, a production build, and a packed-consumer test.
+
+Useful commands:
+
+```sh
+npm run format        # Format source with oxfmt
+npm run lint          # Lint with oxlint
+npm run test:coverage # Runtime tests with strict 100% coverage
+npm run test:types    # Compile-time inference tests
+npm run build         # ESM package and declaration output
+npm run test:pack     # Test the tarball from a clean consumer
+```
+
+Husky runs formatting for staged files plus typechecking and tests before commits. Commit messages use the Conventional Commits specification.
+
+## Contributing and security
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and [SECURITY.md](./SECURITY.md). This project is released under the [MIT License](./LICENSE).

package/dist/index.d.mts

@@ -0,0 +1,70 @@
+//#region src/types.d.ts
+/** Context supplied to every task in a race. */
+interface RaceContext {
+  /**
+   * A signal that is aborted when the caller cancels a pending race or, when
+   * enabled, when another task settles first.
+   */
+  readonly signal: AbortSignal;
+}
+/** A synchronous or asynchronous operation that participates in a race. */
+type RaceTask<T> = (context: RaceContext) => T | PromiseLike<T>;
+/** A named collection of tasks accepted by {@link race}. */
+type RaceTasks = Readonly<Record<string, RaceTask<unknown>>>;
+/** Options that control cancellation for {@link race}. */
+interface RaceOptions {
+  /**
+   * Cancels every still-running task while the race is pending. The race
+   * rejects with this signal's reason. Once a task wins, this signal is
+   * detached and can no longer affect continuing losers.
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * Abort still-running losers when the first task settles. Defaults to
+   * `false`, matching the non-cancelling behaviour of `Promise.race()`.
+   */
+  readonly abortLosers?: boolean;
+}
+type StringKeyOf<T> = Extract<keyof T, string>;
+/**
+ * The discriminated union returned by {@link race}. Narrowing `key` narrows
+ * `value` to the exact value type returned by that task.
+ */
+type RaceResult<T extends RaceTasks> = { [K in StringKeyOf<T>]: {
+  readonly key: K;
+  readonly value: Awaited<ReturnType<T[K]>>;
+}; }[StringKeyOf<T>];
+/** @internal Rejects an empty object at compile time. */
+type NonEmptyTasks<T extends RaceTasks> = keyof T extends never ? never : T;
+//#endregion
+//#region src/race.d.ts
+/**
+ * Races named tasks and returns both the first settled task's key and value.
+ *
+ * All tasks are started in object property order before any settlement is
+ * processed. The first task to fulfil resolves with its keyed result; the
+ * first task to reject rejects with its original reason, just like
+ * `Promise.race()`.
+ *
+ * Set `abortLosers` to abort cooperative losers after the race settles. Pass
+ * `signal` to cancel a still-pending race externally. A task must use the
+ * supplied `AbortSignal` for cancellation to stop its underlying work.
+ *
+ * @example
+ * ```ts
+ * const winner = await race({
+ *   cache: () => readCache(),
+ *   api: ({ signal }) => fetchUser({ signal }),
+ * });
+ *
+ * if (winner.key === "api") {
+ *   winner.value; // inferred from fetchUser
+ * }
+ * ```
+ *
+ * @throws {TypeError} When `tasks` is empty or contains a non-function value.
+ */
+export declare function race<const T extends RaceTasks>(tasks: NonEmptyTasks<T>, options?: RaceOptions): Promise<RaceResult<T>>;
+//#endregion
+export type { RaceContext, RaceOptions, RaceResult, RaceTask, RaceTasks };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +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"}

package/dist/index.mjs

@@ -0,0 +1,75 @@
+//#region src/race.ts
+/**
+* Races named tasks and returns both the first settled task's key and value.
+*
+* All tasks are started in object property order before any settlement is
+* processed. The first task to fulfil resolves with its keyed result; the
+* first task to reject rejects with its original reason, just like
+* `Promise.race()`.
+*
+* Set `abortLosers` to abort cooperative losers after the race settles. Pass
+* `signal` to cancel a still-pending race externally. A task must use the
+* supplied `AbortSignal` for cancellation to stop its underlying work.
+*
+* @example
+* ```ts
+* const winner = await race({
+*   cache: () => readCache(),
+*   api: ({ signal }) => fetchUser({ signal }),
+* });
+*
+* if (winner.key === "api") {
+*   winner.value; // inferred from fetchUser
+* }
+* ```
+*
+* @throws {TypeError} When `tasks` is empty or contains a non-function value.
+*/
+function race(tasks, options = {}) {
+	const entries = Object.entries(tasks);
+	if (entries.length === 0) throw new TypeError("race() requires at least one task.");
+	for (const [key, task] of entries) if (typeof task !== "function") throw new TypeError(`race() 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;
+		const cleanup = () => {
+			options.signal?.removeEventListener("abort", onExternalAbort);
+		};
+		const abortTasks = (winnerKey) => {
+			for (const [key, controller] of controllers) if (key !== winnerKey) controller.abort();
+		};
+		const settleFulfilled = (key, value) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			if (options.abortLosers) abortTasks(key);
+			resolve({
+				key,
+				value
+			});
+		};
+		const settleRejected = (key, reason) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			if (options.abortLosers) abortTasks(key);
+			reject(reason);
+		};
+		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) => settleFulfilled(key, value), (reason) => settleRejected(key, reason));
+		}
+	});
+}
+//#endregion
+export { race };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "better-race",
+  "version": "0.1.0",
+  "description": "A better Promise.race() for TypeScript: keyed results and optional cancellation.",
+  "keywords": [
+    "abortsignal",
+    "async",
+    "cancellation",
+    "promise",
+    "race",
+    "typescript"
+  ],
+  "homepage": "https://github.com/lumberjacque/better-race#readme",
+  "bugs": {
+    "url": "https://github.com/lumberjacque/better-race/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lumberjacque/better-race.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint .",
+    "lint:ci": "oxlint --deny-warnings .",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:types": "vitest --typecheck",
+    "test:pack": "node scripts/test-pack.mjs",
+    "verify": "node scripts/verify.mjs",
+    "version": "changeset version",
+    "publish": "node scripts/publish.mjs",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.2",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@types/node": "^26.4.1",
+    "@vitest/coverage-v8": "^5.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.4.1",
+    "oxfmt": "^0.66.0",
+    "oxlint": "^1.81.0",
+    "tsdown": "^0.23.0",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.0"
+  },
+  "lint-staged": {
+    "*.{js,cjs,mjs,ts,tsx,json,jsonc,md,yml,yaml,html,css}": "oxfmt --write"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}