Commit f62d1ee915bf4e77c8e2d55d1286211289fbdd51 | react-mutation

author	clover caruso <git@paperclover.net> 2026-01-29 16:43:24-08:00
committer	clover caruso <git@paperclover.net> 2026-01-29 16:57:23-08:00
log	f62d1ee915bf4e77c8e2d55d1286211289fbdd51
tree	1b1406624e4c0e0c1f2cbe62bbee79ff46ea8197
parent	2d5acae7f8014bc80c4ddf58592529eeaae282af
signature	Commit is signed but in an unrecognized format.

feat: some more crashouts

11 files changed, 406 insertions(+), 304 deletions(-)

jsr.json+1-1

...	...	@@ -1,6 +1,6 @@
1	1	{
2	2	"name": "@clo/react-mutation",
3		"version": "1.0.0-beta.5",
	3	"version": "1.0.0-beta.6",
4	4	"exports": {
5	5	".": "./src/mod.ts",
6	6	"./tanstack-query.ts": "./src/tanstack-query.ts",

package-lock.json+15

...	...	@@ -19,6 +19,7 @@
19	19	"@vitejs/plugin-react": "^5.1.1",
20	20	"react": "^19.2.4",
21	21	"react-dom": "^19.2.4",
	22	"typescript": "^5.9.3",
22	23	"vite": "^7.2.4",
23	24	"vitest": "^4.0.18"
24	25	},
...	...	@@ -1998,6 +1999,20 @@
1998	1999	"node": ">=14.0.0"
1999	2000	}
2000	2001	},
	2002	"node_modules/typescript": {
	2003	"version": "5.9.3",
	2004	"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
	2005	"integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
	2006	"dev": true,
	2007	"license": "Apache-2.0",
	2008	"bin": {
	2009	"tsc": "bin/tsc",
	2010	"tsserver": "bin/tsserver"
	2011	},
	2012	"engines": {
	2013	"node": ">=14.17"
	2014	}
	2015	},
2001	2016	"node_modules/undici-types": {
2002	2017	"version": "7.16.0",
2003	2018	"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz",

package.json+1

...	...	@@ -23,6 +23,7 @@
23	23	"@vitejs/plugin-react": "^5.1.1",
24	24	"react": "^19.2.4",
25	25	"react-dom": "^19.2.4",
	26	"typescript": "^5.9.3",
26	27	"vite": "^7.2.4",
27	28	"vitest": "^4.0.18"
28	29	},

readme.md+4-3

...	...	@@ -15,9 +15,10 @@ The primary gains React Mutation provides are
15	15	- Automatic result handling. If a `useMutate` hook does not observe
16	16	`isError`, unhandled errors will be propagated to a global handler, which can
17	17	display a UI toast. Otherwise, the component can display the error locally.
18		- Optimistic helpers allow defining rollbacks and refetching logic independant
19		of the actual mutation. The [built in helpers for React Query](#react-query-optimistic-helpers)
20		shows this power in more detail.
	18	- Optimistic helpers with built-in rollbacks make it super easy to alter the
	19	UI without worrying about bugged error states. The
	20	[built in helpers for React Query](#react-query-optimistic-helpers) shows
	21	this power in more detail.
21	22	- Easy debouncing and batching utilities.
22	23
23	24	## Usage

src/blocking.ts+54-40

...	...	@@ -1,6 +1,6 @@
1	1	import type { MutationClient, MutationClientFromConfig } from "./client.ts";
2	2	import type { MutationClientConfig } from "./client.ts";
3		import type { Mutation, MutationEvent } from "./types.ts";
	3	import type { Mutation, MutationEvent, RunOptions } from "./types.ts";
4	4	import { message as errMessage } from "@clo/lib/error.ts";
5	5
6	6	/**
...	...	@@ -45,12 +45,6 @@ export interface MutationOptions<
45	45	optimistic: (
46	46	context: OptimisticContext<Args, Result, Config>,
47	47	) => void;
48		/**
49		* Refetch all of the data this mutation could have affected.
50		* Normally, optimistic helpers will perform
51		* This is called automatically on errors.
52		*/
53		refetch?: (context: Config["context"] & { args: Args }) => Promise<void>;
54	48	/**
55	49	* If the optimistic updator function is perfect, then this may be set to false.
56	50	* @default true
...	...	@@ -231,26 +225,56 @@ export class BlockingMutation<
231	225
232	226	/** Calling the mutation in a global scope. Errors are turned into UI toasts. */
233	227	run(...args: Args) {
	228	this.runWithOptions(...args, {});
	229	}
	230
	231	/** Calls the mutation with custom handlers that can suppress global handlers. */
	232	runWithOptions(...array: [...Args, RunOptions<Result>]): Promise<Result> {
234	233	if (!this.#client.enabled) {
235	234	throw new Error(
236	235	"MutationClient was passed enabled: false. Are you trying to perform a mutation from SSR?",
237	236	);
238	237	}
239		this.runAndReturn(...args).then((result) => {
240		const message = this.describeResult(args, result);
241		if (message && this.#client.reportSuccess) {
242		this.#client.reportSuccess(message);
	238
	239	const args = array.slice() as Args;
	240	const { onSuccess, onSuccessDataOnly, onError, onSettled } = args
	241	.pop() as RunOptions<Result>;
	242	const suppressGlobalSuccess = onSuccess !== undefined;
	243	const suppressGlobalError = onError !== undefined;
	244
	245	const promise = this.runAsPromise(...args);
	246	promise.then((result) => {
	247	// Call user handlers
	248	onSuccess?.(result);
	249	onSuccessDataOnly?.(result);
	250	onSettled?.({ status: "success", result });
	251
	252	// Call global handler unless suppressed
	253	if (!suppressGlobalSuccess) {
	254	const message = this.describeResult(args, result);
	255	if (message && this.#client.reportSuccess) {
	256	this.#client.reportSuccess(message);
	257	}
243	258	}
244	259	}).catch((error) => {
245		const message = `Failed to ${this.describe(...args)}: ${
246		errMessage(error)
247		}`;
248		this.#client.reportError(message, error);
	260	// Call user handlers
	261	onError?.(error);
	262	onSettled?.({ status: "error", error });
	263
	264	// Call global handler unless suppressed
	265	if (!suppressGlobalError) {
	266	const message = `Failed to ${this.describe(...args)}: ${
	267	errMessage(error)
	268	}`;
	269	this.#client.reportError(message, error);
	270	}
249	271	});
	272
	273	return promise;
250	274	}
251	275
252	276	/** Calls the mutation, treating the errors as promise rejection. */
253		runAndReturn(...args: Args): Promise<Result> {
	277	runAsPromise(...args: Args): Promise<Result> {
254	278	if (!this.#client.enabled) {
255	279	throw new Error(
256	280	"MutationClient was passed enabled: false. Are you trying to perform a mutation from SSR?",
...	...	@@ -366,23 +390,19 @@ export class BlockingMutation<
366	390	this.#notify(channel, "refetching", result);
367	391	// Call refetch and all refetch callbacks in parallel
368	392	const refetchCallbacks = channel.refetches.splice(0);
369		Promise.allSettled([
370		this.#options.refetch?.({
371		...this.#client.context,
372		args,
373		}),
374		...refetchCallbacks.map((cb) => cb()),
375		]).then((results) => {
376		// Report any errors from refetch or callbacks
377		results.forEach((result) => {
378		if (result.status === "rejected") {
379		const message = `Failed to refetch after ${
380		this.describe(...args)
381		}: ${errMessage(result.reason)}`;
382		this.#client.reportError(message, result.reason);
383		}
384		});
385		}).finally(() => {
	393	Promise.allSettled(refetchCallbacks.map((cb) => cb())).then(
	394	(results) => {
	395	// Report any errors from refetch or callbacks
	396	results.forEach((result) => {
	397	if (result.status === "rejected") {
	398	const message = `Failed to refetch after ${
	399	this.describe(...args)
	400	}: ${errMessage(result.reason)}`;
	401	this.#client.reportError(message, result.reason);
	402	}
	403	});
	404	},
	405	).finally(() => {
386	406	this.#executeNext(key, channel);
387	407	});
388	408	} else {
...	...	@@ -410,13 +430,7 @@ export class BlockingMutation<
410	430	this.#notify(channel, "refetching", null, error);
411	431	// Call refetch and all refetch callbacks in parallel
412	432	const refetchCallbacks = channel.refetches.splice(0);
413		Promise.allSettled([
414		this.#options.refetch?.({
415		...this.#client.context,
416		args,
417		}),
418		...refetchCallbacks.map((cb) => cb()),
419		]).then((results) => {
	433	Promise.allSettled(refetchCallbacks.map((cb) => cb())).then((results) => {
420	434	// Report any errors from refetch or callbacks
421	435	results.forEach((result) => {
422	436	if (result.status === "rejected") {

src/debounced.ts+49-16

...	...	@@ -1,6 +1,6 @@
1	1	import type { MutationClient, MutationClientFromConfig } from "./client.ts";
2	2	import type { MutationClientConfig } from "./client.ts";
3		import type { Mutation, MutationEvent } from "./types.ts";
	3	import type { Mutation, MutationEvent, RunOptions } from "./types.ts";
4	4	import { message as errMessage } from "@clo/lib/error.ts";
5	5
6	6	export interface DebouncedMutationOptions<
...	...	@@ -293,8 +293,42 @@ export class DebouncedMutation<
293	293	});
294	294	}
295	295
	296	runWithOptions(...array: [...args: Args, options: RunOptions<Result>]): void {
	297	if (!this.#client.enabled) {
	298	throw new Error(
	299	"MutationClient was passed enabled: false. Are you trying to perform a mutation from SSR?",
	300	);
	301	}
	302	const args = array.slice() as Args;
	303	const { onSuccess, onSuccessDataOnly, onError, onSettled } = args
	304	.pop() as RunOptions<Result>;
	305	const suppressGlobalSuccess = onSuccess !== undefined;
	306	const suppressGlobalError = onError !== undefined;
	307
	308	const promise = this.#runAndReturn(args, !suppressGlobalSuccess);
	309
	310	promise.then((result) => {
	311	// Call user handlers
	312	onSuccess?.(result);
	313	onSuccessDataOnly?.(result);
	314	onSettled?.({ status: "success", result });
	315	}).catch((error) => {
	316	// Call user handlers
	317	onError?.(error);
	318	onSettled?.({ status: "error", error });
	319
	320	// Call global error handler unless suppressed
	321	if (!suppressGlobalError) {
	322	const message = `Failed to ${this.describe(...args)}: ${
	323	errMessage(error)
	324	}`;
	325	this.#client.reportError(message, error);
	326	}
	327	});
	328	}
	329
296	330	/** Calls the mutation, treating the errors as promise rejection. */
297		runAndReturn(...args: Args): Promise<Result> {
	331	runAsPromise(...args: Args): Promise<Result> {
298	332	if (!this.#client.enabled) {
299	333	throw new Error(
300	334	"MutationClient was passed enabled: false. Are you trying to perform a mutation from SSR?",
...	...	@@ -546,20 +580,19 @@ export class DebouncedMutation<
546	580	channel.status = "refetching";
547	581	this.#notify(channel, "refetching", null, error);
548	582	// Call refetch and all refetch callbacks in parallel
549		Promise.allSettled([
550		this.#options.refetch?.(),
551		...refetchCallbacks.map((cb) => cb()),
552		]).then((results) => {
553		// Report any errors from refetch or callbacks
554		results.forEach((result) => {
555		if (result.status === "rejected") {
556		const message = `Failed to refetch after ${
557		this.describe(...firstArgs)
558		}: ${errMessage(result.reason)}`;
559		this.#client.reportError(message, result.reason);
560		}
561		});
562		}).finally(() => {
	583	Promise.allSettled(refetchCallbacks.map((cb) => cb())).then(
	584	(results) => {
	585	// Report any errors from refetch or callbacks
	586	results.forEach((result) => {
	587	if (result.status === "rejected") {
	588	const message = `Failed to refetch after ${
	589	this.describe(...firstArgs)
	590	}: ${errMessage(result.reason)}`;
	591	this.#client.reportError(message, result.reason);
	592	}
	593	});
	594	},
	595	).finally(() => {
563	596	// Check if new calls came in during the commit
564	597	if (channel.pending.length > 0) {
565	598	// There are pending calls that need to be committed

src/react.ts+63-17

...	...	@@ -8,7 +8,7 @@ import {
8	8	useState,
9	9	} from "react";
10	10	import { message as errMessage } from "@clo/lib/error.ts";
11		import type { Mutation } from "./types.ts";
	11	import type { Mutation, RunOptions } from "./types.ts";
12	12	import { jsx } from "react/jsx-runtime";
13	13
14	14	/**
...	...	@@ -41,7 +41,10 @@ export type UseMutateResult<Args extends unknown[], Result> =
41	41
42	42	export interface UseMutateResultBase<Args extends unknown[], Result> {
43	43	run: (...args: Args) => void;
44		runWithResult: (...args: Args) => Promise<Result>;
	44	runWithOptions: (
	45	options: RunOptions<Result>,
	46	...args: Args
	47	) => Promise<Result>;
45	48	clear: () => void;
46	49	}
47	50
...	...	@@ -220,7 +223,7 @@ class Observer<Args extends unknown[], Result> {
220	223	this.watched.has("error") \|\| this.watched.has("errorMessage");
221	224	const watchesSuccess = this.watched.has("isSuccess") \|\|
222	225	this.watched.has("result");
223		const promise = mutation.runAndReturn(...args)
	226	const promise = mutation.runAsPromise(...args)
224	227	.then((result) => {
225	228	if (!watchesSuccess && mutation.describeResult) {
226	229	const message = mutation.describeResult(args, result);
...	...	@@ -240,12 +243,63 @@ class Observer<Args extends unknown[], Result> {
240	243	return promise;
241	244	}
242	245
	246	runWithOptions(options: RunOptions<Result>, ...args: Args): void {
	247	const mutation = this.mutation;
	248	if (!mutation) return;
	249
	250	this.currentArgs = args;
	251	const key = mutation.key(args);
	252
	253	// Set up subscription if key changed
	254	if (key !== this.currentKey) {
	255	this.currentKey = key;
	256	this.unsubscribe?.();
	257	this.unsubscribe = mutation.subscribe(
	258	mutation.key(args),
	259	({ status, error, result }) => {
	260	if (status === "idle") {
	261	this.setState({
	262	isMutating: false,
	263	isPending: false,
	264	isOptimisticData: false,
	265	});
	266	return;
	267	}
	268	const hasError = error != null;
	269	const hasResult = result != null;
	270
	271	this.setState({
	272	status: hasError
	273	? "error"
	274	: hasResult
	275	? "success"
	276	: status === "mutating"
	277	? "mutating"
	278	: "idle",
	279	error: error ?? undefined,
	280	errorMessage: this.computeErrorMessage(error ?? undefined),
	281	result: result ?? undefined,
	282	isMutating: status === "mutating",
	283	isPending: status === "mutating" \|\| status === "refetching",
	284	isSuccess: hasResult && !hasError,
	285	isError: hasError,
	286	isOptimisticData: status === "waiting" \|\| status === "mutating" \|\|
	287	status === "refetching",
	288	});
	289	},
	290	);
	291	}
	292
	293	// Delegate to the mutation's runWithOptions
	294	mutation.runWithOptions(...args, options);
	295	}
	296
243	297	binding: UseMutateResult<Args, Result> = ((self: this) => ({
244	298	run(...args) {
245	299	return self.run(...args);
246	300	},
247		runWithResult(...args) {
248		return self.run(...args);
	301	runWithOptions(options, ...args) {
	302	return self.runWithOptions(options, ...args);
249	303	},
250	304	clear() {
251	305	self.setState({
...	...	@@ -394,9 +448,6 @@ function GenericMutationButton<
394	448	const localHook = useMutate("subscribe" in mutation ? mutation : null);
395	449	const state = "subscribe" in mutation ? localHook : mutation;
396	450
397		if (onError) void state.isError; // subscribe to the events
398		if (onSuccess) void state.isSuccess; // subscribe to the events
399
400	451	// NOTE: the JSR has trouble with JSX syntax for some reason.
401	452	return jsx(
402	453	Component,
...	...	@@ -407,15 +458,10 @@ function GenericMutationButton<
407	458	if (e.defaultPrevented) return;
408	459	const computedArgs = typeof args === "function" ? args(e) : args;
409	460	if (!computedArgs \|\| e.defaultPrevented) return;
410		state.runWithResult(...computedArgs)
411		.then((result) => {
412		onSuccess?.(result);
413		onSettled?.({ status: "success", result });
414		})
415		.catch((error) => {
416		onError?.(error);
417		onSettled?.({ status: "error", error });
418		});
	461	state.runWithOptions(
	462	{ onSuccess, onError, onSettled },
	463	...computedArgs,
	464	);
419	465	}, [state]),
420	466	isPending: state.isPending,
421	467	} satisfies Parameters<typeof Component>[0],

src/tanstack-query.ts+34-1

...	...	@@ -322,6 +322,39 @@ class TanstackQueryOptimisticHelpers {
322	322	objArrayRemove<
323	323	Data extends object,
324	324	const Path extends AllObjectPaths<Data>,
	325	>(
	326	queryKey: QueryKeyAndFn<Data>,
	327	path: Path,
	328	removeFilter: (
	329	item: GetObjectPath<Data, Path> extends Array<infer T> ? T : never,
	330	index: number,
	331	) => boolean,
	332	) {
	333	const prev = this.#get(queryKey);
	334	if (!prev) return;
	335	const { value: original, exists } = getPath(prev, path);
	336	if (!exists \|\| !Array.isArray(original)) return;
	337
	338	const newArray = original.filter((item, index) =>
	339	!removeFilter(item, index)
	340	);
	341	this.#set(
	342	queryKey,
	343	(obj) => obj ? setPath(obj, path, newArray as any) : obj,
	344	);
	345	this.#onRestore(() => {
	346	// TODO: splice items back in case original changed
	347	this.#set(queryKey, (obj) => obj ? setPath(obj, path, original) : obj);
	348	});
	349	}
	350
	351	/**
	352	* Filter items to just include items that match `filter`. This is the inverse of `objArrayRemove`
	353	* If the query or path doesn't exist, the updater is skipped.
	354	*/
	355	objArrayFilter<
	356	Data extends object,
	357	const Path extends AllObjectPaths<Data>,
325	358	>(
326	359	queryKey: QueryKeyAndFn<Data>,
327	360	path: Path,
...	...	@@ -335,7 +368,7 @@ class TanstackQueryOptimisticHelpers {
335	368	const { value: original, exists } = getPath(prev, path);
336	369	if (!exists \|\| !Array.isArray(original)) return;
337	370
338		const newArray = original.filter((item, index) => !filter(item, index));
	371	const newArray = original.filter(filter);
339	372	this.#set(
340	373	queryKey,
341	374	(obj) => obj ? setPath(obj, path, newArray as any) : obj,

src/types.ts+19-2

...	...	@@ -3,8 +3,10 @@ import type { MutationClient } from "./client.ts";
3	3	export interface Mutation<Args extends unknown[], Result> {
4	4	/** Calling the mutation. Errors are turned into UI toasts. */
5	5	run(...args: Args): void;
6		/** Calls the mutation, treating the errors as promise rejection. */
7		runAndReturn(...args: Args): Promise<Result>;
	6	/** Calls the mutation with custom handlers that can suppress global handlers. */
	7	runWithOptions(...args: [...args: Args, options: RunOptions<Result>]): void;
	8	/** Calling the mutation. Errors are thrown in the promise. */
	9	runAsPromise(...args: Args): Promise<Result>;
8	10
9	11	/** Returns the concurrency key used for a given set of arguments */
10	12	key(args: Args): string;
...	...	@@ -18,6 +20,21 @@ export interface Mutation<Args extends unknown[], Result> {
18	20	client: MutationClient<object, object>;
19	21	}
20	22
	23	export interface RunOptions<Result> {
	24	/** Called on success, suppresses the global success handler */
	25	onSuccess?: (result: Result) => void;
	26	/** Called on success, does NOT suppress the global success handler */
	27	onSuccessDataOnly?: (result: Result) => void;
	28	/** Called on error, suppresses the global error handler */
	29	onError?: (error: unknown) => void;
	30	/** Called on settled (doesn't suppress global handlers) */
	31	onSettled?: (
	32	status:
	33	\| { status: "success"; result: Result }
	34	\| { status: "error"; error: unknown },
	35	) => void;
	36	}
	37
21	38	export interface MutationEvent<Result> {
22	39	status: "idle" \| "waiting" \| "mutating" \| "refetching";
23	40	result: Result \| null;

test/blocking.test.ts+127-160

...	...	@@ -57,16 +57,15 @@ test("BlockingMutation - basic mutation success", async () => {
57	57	},
58	58	describe: "test mutation",
59	59	describeResult: "Success",
60		optimistic() {
61		// Empty optimistic update
62		},
63		async refetch() {
64		refetchCallCount++;
65		await delay(5);
	60	optimistic({ onRefetch }) {
	61	onRefetch(async () => {
	62	refetchCallCount++;
	63	await delay(5);
	64	});
66	65	},
67	66	});
68	67
69		const result = await mutation.runAndReturn("test");
	68	const result = await mutation.runAsPromise("test");
70	69	// Wait for refetch to complete
71	70	await delay(20);
72	71
...	...	@@ -85,7 +84,6 @@ test("BlockingMutation - run() catches errors", async () => {
85	84	describe: "failing mutation",
86	85	describeResult: "Success",
87	86	optimistic() {},
88		async refetch() {},
89	87	});
90	88
91	89	mutation.run("test");
...	...	@@ -105,11 +103,10 @@ test("BlockingMutation - runAndReturn() rejects on error", async () => {
105	103	describe: "failing mutation",
106	104	describeResult: "Success",
107	105	optimistic() {},
108		async refetch() {},
109	106	});
110	107
111	108	await assertRejects(
112		() => mutation.runAndReturn("test"),
	109	() => mutation.runAsPromise("test"),
113	110	Error,
114	111	"mutation failed",
115	112	);
...	...	@@ -130,10 +127,9 @@ test("BlockingMutation - optimistic updates are applied immediately", async () =
130	127	const [key, value] = args;
131	128	helpers.setValue(key, value);
132	129	},
133		async refetch() {},
134	130	});
135	131
136		const promise = mutation.runAndReturn("key1", "value1");
	132	const promise = mutation.runAsPromise("key1", "value1");
137	133
138	134	// Optimistic update should be applied synchronously
139	135	assertEquals(testStore.get("key1"), "value1");
...	...	@@ -158,10 +154,9 @@ test("BlockingMutation - rollback on error", async () => {
158	154	const [key, value] = args;
159	155	helpers.setValue(key, value);
160	156	},
161		async refetch() {},
162	157	});
163	158
164		await assertRejects(() => mutation.runAndReturn("key1", "value1"));
	159	await assertRejects(() => mutation.runAsPromise("key1", "value1"));
165	160
166	161	// Optimistic update should be rolled back
167	162	assertEquals(testStore.has("key1"), false);
...	...	@@ -182,10 +177,9 @@ test("BlockingMutation - onSuccess callback is called", async () => {
182	177	successResults.push(result);
183	178	});
184	179	},
185		async refetch() {},
186	180	});
187	181
188		await mutation.runAndReturn("test");
	182	await mutation.runAsPromise("test");
189	183
190	184	assertEquals(successResults, ["result-test"]);
191	185	});
...	...	@@ -204,7 +198,7 @@ test("BlockingMutation - mutations with same key execute serially", async () =>
204	198	describe: "test mutation",
205	199	describeResult: "Success",
206	200	optimistic() {},
207		async refetch() {},
	201
208	202	refetchOnSuccess: false,
209	203	key() {
210	204	return "same-key";
...	...	@@ -212,8 +206,8 @@ test("BlockingMutation - mutations with same key execute serially", async () =>
212	206	});
213	207
214	208	// Start two mutations with the same key
215		const promise1 = mutation.runAndReturn("1");
216		const promise2 = mutation.runAndReturn("2");
	209	const promise1 = mutation.runAsPromise("1");
	210	const promise2 = mutation.runAsPromise("2");
217	211
218	212	await Promise.all([promise1, promise2]);
219	213	await delay(10);
...	...	@@ -236,7 +230,7 @@ test("BlockingMutation - mutations with different keys execute in parallel", asy
236	230	describe: "test mutation",
237	231	describeResult: "Success",
238	232	optimistic() {},
239		async refetch() {},
	233
240	234	key({ args }) {
241	235	const [id] = args;
242	236	return id;
...	...	@@ -244,8 +238,8 @@ test("BlockingMutation - mutations with different keys execute in parallel", asy
244	238	});
245	239
246	240	// Start two mutations with different keys
247		const promise1 = mutation.runAndReturn("key1");
248		const promise2 = mutation.runAndReturn("key2");
	241	const promise1 = mutation.runAsPromise("key1");
	242	const promise2 = mutation.runAsPromise("key2");
249	243
250	244	await Promise.all([promise1, promise2]);
251	245
...	...	@@ -263,7 +257,7 @@ test("BlockingMutation - key() returns JSON stringified key", () => {
263	257	describe: "test mutation",
264	258	describeResult: "Success",
265	259	optimistic() {},
266		async refetch() {},
	260
267	261	key({ args }) {
268	262	const [id] = args;
269	263	return id;
...	...	@@ -283,7 +277,6 @@ test("BlockingMutation - key() defaults to 'shared' when no key function", () =>
283	277	describe: "test mutation",
284	278	describeResult: "Success",
285	279	optimistic() {},
286		async refetch() {},
287	280	});
288	281
289	282	assertEquals(mutation.key(["test-id"]), JSON.stringify("shared"));
...	...	@@ -299,7 +292,7 @@ test("BlockingMutation - key() can return array", () => {
299	292	describe: "test mutation",
300	293	describeResult: "Success",
301	294	optimistic() {},
302		async refetch() {},
	295
303	296	key({ args }) {
304	297	const [userId, itemId] = args;
305	298	return [userId, itemId];
...	...	@@ -322,7 +315,6 @@ test("BlockingMutation - describe() with string", () => {
322	315	describe: "create item",
323	316	describeResult: "Success",
324	317	optimistic() {},
325		async refetch() {},
326	318	});
327	319
328	320	assertEquals(mutation.describe("test"), "create item");
...	...	@@ -339,8 +331,8 @@ test("BlockingMutation - describe() with function", () => {
339	331	const [id] = args;
340	332	return `delete item ${id}`;
341	333	},
	334	describeResult: null,
342	335	optimistic() {},
343		async refetch() {},
344	336	});
345	337
346	338	assertEquals(mutation.describe("123"), "delete item 123");
...	...	@@ -358,7 +350,7 @@ test("BlockingMutation - describe() receives context", () => {
358	350	return `user ${userId} editing item ${id}`;
359	351	},
360	352	optimistic() {},
361		async refetch() {},
	353	describeResult: null,
362	354	});
363	355
364	356	assertEquals(
...	...	@@ -378,16 +370,17 @@ test("BlockingMutation - subscribe() tracks mutation events", async () => {
378	370	},
379	371	describe: "test mutation",
380	372	describeResult: "Success",
381		optimistic() {},
382		async refetch() {
383		await delay(5);
	373	optimistic({ onRefetch }) {
	374	onRefetch(async () => {
	375	await delay(5);
	376	});
384	377	},
385	378	});
386	379
387	380	const key = mutation.key(["test"]);
388	381	mutation.subscribe(key, tracker.callback);
389	382
390		await mutation.runAndReturn("test");
	383	await mutation.runAsPromise("test");
391	384	// Wait for refetch to complete
392	385	await delay(20);
393	386
...	...	@@ -409,7 +402,7 @@ test("BlockingMutation - unsubscribe stops receiving events", async () => {
409	402	describe: "test mutation",
410	403	describeResult: "Success",
411	404	optimistic() {},
412		async refetch() {},
	405
413	406	refetchOnSuccess: false,
414	407	});
415	408
...	...	@@ -418,7 +411,7 @@ test("BlockingMutation - unsubscribe stops receiving events", async () => {
418	411
419	412	unsubscribe();
420	413
421		await mutation.runAndReturn("test");
	414	await mutation.runAsPromise("test");
422	415	await delay(10);
423	416
424	417	// Should not have received any events
...	...	@@ -435,14 +428,15 @@ test("BlockingMutation - refetchOnSuccess can be disabled", async () => {
435	428	},
436	429	describe: "test mutation",
437	430	describeResult: "Success",
438		optimistic() {},
439		async refetch() {
440		refetchCallCount++;
	431	optimistic({ onRefetch }) {
	432	onRefetch(async () => {
	433	refetchCallCount++;
	434	});
441	435	},
442	436	refetchOnSuccess: false,
443	437	});
444	438
445		await mutation.runAndReturn("test");
	439	await mutation.runAsPromise("test");
446	440
447	441	assertEquals(refetchCallCount, 0);
448	442	});
...	...	@@ -457,13 +451,14 @@ test("BlockingMutation - refetch is called on error", async () => {
457	451	},
458	452	describe: "failing mutation",
459	453	describeResult: "Success",
460		optimistic() {},
461		async refetch() {
462		refetchCallCount++;
	454	optimistic({ onRefetch }) {
	455	onRefetch(async () => {
	456	refetchCallCount++;
	457	});
463	458	},
464	459	});
465	460
466		await assertRejects(() => mutation.runAndReturn("test"));
	461	await assertRejects(() => mutation.runAsPromise("test"));
467	462
468	463	assertEquals(refetchCallCount, 1);
469	464	});
...	...	@@ -485,15 +480,15 @@ test("BlockingMutation - queued mutations are cancelled on error", async () => {
485	480	describe: "test mutation",
486	481	describeResult: "Success",
487	482	optimistic() {},
488		async refetch() {},
	483
489	484	key() {
490	485	return "same-key";
491	486	},
492	487	});
493	488
494		const promise1 = mutation.runAndReturn("1");
495		const promise2 = mutation.runAndReturn("2");
496		const promise3 = mutation.runAndReturn("3");
	489	const promise1 = mutation.runAsPromise("1");
	490	const promise2 = mutation.runAsPromise("2");
	491	const promise3 = mutation.runAsPromise("3");
497	492
498	493	await assertRejects(() => promise1, Error, "first mutation failed");
499	494	await assertRejects(() => promise2, Error, "first mutation failed");
...	...	@@ -518,10 +513,9 @@ test("BlockingMutation - rollbacks are called in reverse order on error", async
518	513	onRestore(() => rollbackOrder.push(2));
519	514	onRestore(() => rollbackOrder.push(3));
520	515	},
521		async refetch() {},
522	516	});
523	517
524		await assertRejects(() => mutation.runAndReturn("test"));
	518	await assertRejects(() => mutation.runAsPromise("test"));
525	519
526	520	// Rollbacks should be called in reverse order
527	521	assertEquals(rollbackOrder, [3, 2, 1]);
...	...	@@ -544,17 +538,17 @@ test("BlockingMutation - multiple mutations: rollbacks only affect failed mutati
544	538	optimistic({ args: [id], onRestore }) {
545	539	onRestore(() => rollbackOrder.push(`rollback-${id}`));
546	540	},
547		async refetch() {},
	541
548	542	key() {
549	543	return "same-key";
550	544	},
551	545	});
552	546
553	547	// First mutation succeeds
554		await mutation.runAndReturn("success");
	548	await mutation.runAsPromise("success");
555	549
556	550	// Second mutation fails
557		await assertRejects(() => mutation.runAndReturn("fail"));
	551	await assertRejects(() => mutation.runAsPromise("fail"));
558	552
559	553	// Only the failed mutation's rollback should be called
560	554	// And all rollbacks from queued items
...	...	@@ -574,10 +568,9 @@ test("BlockingMutation - onRestore throws error if called after optimistic phase
574	568	optimistic({ onRestore }) {
575	569	capturedOnRestore = onRestore;
576	570	},
577		async refetch() {},
578	571	});
579	572
580		await mutation.runAndReturn("test");
	573	await mutation.runAsPromise("test");
581	574
582	575	// Calling onRestore after the optimistic phase should throw
583	576	let error: Error \| null = null;
...	...	@@ -606,10 +599,9 @@ test("BlockingMutation - onSuccess throws error if called after optimistic phase
606	599	optimistic({ onSuccess }) {
607	600	capturedOnSuccess = onSuccess;
608	601	},
609		async refetch() {},
610	602	});
611	603
612		await mutation.runAndReturn("test");
	604	await mutation.runAsPromise("test");
613	605
614	606	// Calling onSuccess after the optimistic phase should throw
615	607	let error: Error \| null = null;
...	...	@@ -637,11 +629,10 @@ test("BlockingMutation - error during optimistic update is rejected immediately"
637	629	optimistic() {
638	630	throw new Error("optimistic update failed");
639	631	},
640		async refetch() {},
641	632	});
642	633
643	634	await assertRejects(
644		() => mutation.runAndReturn("test"),
	635	() => mutation.runAsPromise("test"),
645	636	Error,
646	637	"optimistic update failed",
647	638	);
...	...	@@ -662,10 +653,9 @@ test("BlockingMutation - error during optimistic update rolls back registered ca
662	653	onRestore(() => rollbackOrder.push(2));
663	654	throw new Error("optimistic update failed");
664	655	},
665		async refetch() {},
666	656	});
667	657
668		await assertRejects(() => mutation.runAndReturn("test"));
	658	await assertRejects(() => mutation.runAsPromise("test"));
669	659
670	660	// Rollbacks should be called even though optimistic update failed
671	661	// Note: during optimistic error, rollbacks are executed in the order they were added
...	...	@@ -681,14 +671,15 @@ test("BlockingMutation - refetch errors are reported but don't fail mutation", a
681	671	},
682	672	describe: "test mutation",
683	673	describeResult: "Success",
684		optimistic() {},
685		async refetch() {
686		throw new Error("refetch failed");
	674	optimistic({ onRefetch }) {
	675	onRefetch(async () => {
	676	throw new Error("refetch failed");
	677	});
687	678	},
688	679	});
689	680
690	681	// Mutation should still succeed
691		const result = await mutation.runAndReturn("test");
	682	const result = await mutation.runAsPromise("test");
692	683	assertEquals(result, "test");
693	684
694	685	// But refetch error should be reported
...	...	@@ -712,39 +703,14 @@ test("BlockingMutation - optimistic function receives args and helpers", async (
712	703	receivedArgs = args;
713	704	receivedHelpers = helpers;
714	705	},
715		async refetch() {},
716	706	});
717	707
718		await mutation.runAndReturn("test");
	708	await mutation.runAsPromise("test");
719	709
720	710	assertEquals(receivedArgs, ["test"]);
721	711	assertEquals(typeof receivedHelpers, "object");
722	712	});
723	713
724		test("BlockingMutation - refetch receives context and args", async () => {
725		const { client } = createTestClient();
726		let receivedUserId: string \| undefined;
727		let receivedArgs: unknown[] \| undefined;
728
729		const mutation = client.define({
730		async mutate(_id: string, value: string) {
731		return value;
732		},
733		describe: "test mutation",
734		describeResult: "Success",
735		optimistic() {},
736		async refetch({ userId, args }) {
737		receivedUserId = userId;
738		receivedArgs = args;
739		},
740		});
741
742		await mutation.runAndReturn("test-id", "test-value");
743
744		assertEquals(receivedUserId, "test-user");
745		assertEquals(receivedArgs, ["test-id", "test-value"]);
746		});
747
748	714	test("BlockingMutation - notifies error on mutation failure", async () => {
749	715	const { client } = createTestClient();
750	716	const tracker = createEventTracker<string>();
...	...	@@ -757,13 +723,12 @@ test("BlockingMutation - notifies error on mutation failure", async () => {
757	723	describe: "failing mutation",
758	724	describeResult: "Success",
759	725	optimistic() {},
760		async refetch() {},
761	726	});
762	727
763	728	const key = mutation.key(["test"]);
764	729	mutation.subscribe(key, tracker.callback);
765	730
766		await assertRejects(() => mutation.runAndReturn("test"));
	731	await assertRejects(() => mutation.runAsPromise("test"));
767	732
768	733	// Should have error event
769	734	const errorEvents = tracker.events.filter((e) =>
...	...	@@ -786,7 +751,7 @@ test("BlockingMutation - multiple subscribers receive events", async () => {
786	751	describe: "test mutation",
787	752	describeResult: "Success",
788	753	optimistic() {},
789		async refetch() {},
	754
790	755	refetchOnSuccess: false,
791	756	});
792	757
...	...	@@ -794,7 +759,7 @@ test("BlockingMutation - multiple subscribers receive events", async () => {
794	759	mutation.subscribe(key, tracker1.callback);
795	760	mutation.subscribe(key, tracker2.callback);
796	761
797		await mutation.runAndReturn("test");
	762	await mutation.runAsPromise("test");
798	763	await delay(10);
799	764
800	765	// Both subscribers should receive events
...	...	@@ -817,11 +782,11 @@ test("BlockingMutation - onSuccess is called before mutation resolves", async ()
817	782	callOrder.push("onSuccess");
818	783	});
819	784	},
820		async refetch() {},
	785
821	786	refetchOnSuccess: false,
822	787	});
823	788
824		const promise = mutation.runAndReturn("test");
	789	const promise = mutation.runAsPromise("test");
825	790	promise.then(() => {
826	791	callOrder.push("then");
827	792	});
...	...	@@ -845,15 +810,12 @@ test("BlockingMutation - result is passed to notification on success", async ()
845	810	describe: "test mutation",
846	811	describeResult: "Success",
847	812	optimistic() {},
848		async refetch() {
849		await delay(5);
850		},
851	813	});
852	814
853	815	const key = mutation.key(["test"]);
854	816	mutation.subscribe(key, tracker.callback);
855	817
856		await mutation.runAndReturn("test");
	818	await mutation.runAsPromise("test");
857	819	await delay(20);
858	820
859	821	// Should have refetching event with result
...	...	@@ -876,16 +838,16 @@ test("BlockingMutation - channel is reused for same key", async () => {
876	838	describe: "test mutation",
877	839	describeResult: "Success",
878	840	optimistic() {},
879		async refetch() {},
	841
880	842	refetchOnSuccess: false,
881	843	});
882	844
883	845	// First mutation
884		await mutation.runAndReturn("first");
	846	await mutation.runAsPromise("first");
885	847	await delay(5);
886	848
887	849	// Second mutation with same key
888		await mutation.runAndReturn("second");
	850	await mutation.runAsPromise("second");
889	851	await delay(5);
890	852
891	853	assertEquals(events, ["mutate-first", "mutate-second"]);
...	...	@@ -902,7 +864,7 @@ test("BlockingMutation - empty queue after all mutations complete", async () =>
902	864	describe: "test mutation",
903	865	describeResult: "Success",
904	866	optimistic() {},
905		async refetch() {},
	867
906	868	refetchOnSuccess: false,
907	869	key() {
908	870	return "test-key";
...	...	@@ -910,15 +872,15 @@ test("BlockingMutation - empty queue after all mutations complete", async () =>
910	872	});
911	873
912	874	// Run multiple mutations
913		await mutation.runAndReturn("1");
914		await mutation.runAndReturn("2");
915		await mutation.runAndReturn("3");
	875	await mutation.runAsPromise("1");
	876	await mutation.runAsPromise("2");
	877	await mutation.runAsPromise("3");
916	878	await delay(10);
917	879
918	880	// All mutations should have completed
919	881	// (We can't directly check the queue, but we can verify by running another mutation)
920	882	const start = Date.now();
921		await mutation.runAndReturn("4");
	883	await mutation.runAsPromise("4");
922	884	const duration = Date.now() - start;
923	885
924	886	// Should execute immediately, not be queued (< 10ms if not queued)
...	...	@@ -940,11 +902,11 @@ test("BlockingMutation - multiple onSuccess callbacks are all called", async ()
940	902	onSuccess((result) => results.push(`second-${result}`));
941	903	onSuccess((result) => results.push(`third-${result}`));
942	904	},
943		async refetch() {},
	905
944	906	refetchOnSuccess: false,
945	907	});
946	908
947		await mutation.runAndReturn("test");
	909	await mutation.runAsPromise("test");
948	910
949	911	assertEquals(results, ["first-test", "second-test", "third-test"]);
950	912	});
...	...	@@ -959,14 +921,15 @@ test("BlockingMutation - refetchOnSuccess false skips refetch", async () => {
959	921	},
960	922	describe: "test mutation",
961	923	describeResult: "Success",
962		optimistic() {},
963		async refetch() {
964		refetchCalled = true;
	924	optimistic({ onRefetch }) {
	925	onRefetch(async () => {
	926	refetchCalled = true;
	927	});
965	928	},
966	929	refetchOnSuccess: false,
967	930	});
968	931
969		await mutation.runAndReturn("test");
	932	await mutation.runAsPromise("test");
970	933	await delay(10);
971	934
972	935	// Refetch should not have been called
...	...	@@ -982,14 +945,15 @@ test("BlockingMutation - refetch error after mutation failure is reported", asyn
982	945	},
983	946	describe: "failing mutation",
984	947	describeResult: "Success",
985		optimistic() {},
986		async refetch() {
987		throw new Error("refetch also failed");
	948	optimistic({ onRefetch }) {
	949	onRefetch(async () => {
	950	throw new Error("refetch also failed");
	951	});
988	952	},
989	953	});
990	954
991	955	await assertRejects(
992		() => mutation.runAndReturn("test"),
	956	() => mutation.runAsPromise("test"),
993	957	Error,
994	958	"mutation failed",
995	959	);
...	...	@@ -1026,11 +990,11 @@ test("BlockingMutation - debounce: basic debounced execution", async () => {
1026	990	const [key, value] = args;
1027	991	helpers.setValue(key, value);
1028	992	},
1029		async refetch() {},
	993
1030	994	debounceMs: 50,
1031	995	});
1032	996
1033		const promise = mutation.runAndReturn("key1", "value1");
	997	const promise = mutation.runAsPromise("key1", "value1");
1034	998
1035	999	// Optimistic update should be applied immediately
1036	1000	assertEquals(testStore.get("key1"), "value1");
...	...	@@ -1063,14 +1027,14 @@ test("BlockingMutation - debounce: last call wins with multiple rapid calls", as
1063	1027	const [key, value] = args;
1064	1028	helpers.setValue(key, value);
1065	1029	},
1066		async refetch() {},
	1030
1067	1031	debounceMs: 50,
1068	1032	});
1069	1033
1070	1034	// Make three rapid calls
1071		const promise1 = mutation.runAndReturn("key1", "a");
1072		const promise2 = mutation.runAndReturn("key1", "b");
1073		const promise3 = mutation.runAndReturn("key1", "c");
	1035	const promise1 = mutation.runAsPromise("key1", "a");
	1036	const promise2 = mutation.runAsPromise("key1", "b");
	1037	const promise3 = mutation.runAsPromise("key1", "c");
1074	1038
1075	1039	// Last optimistic update should be applied
1076	1040	assertEquals(testStore.get("key1"), "c");
...	...	@@ -1109,17 +1073,17 @@ test("BlockingMutation - debounce: optimistic rollback and reapply", async () =>
1109	1073	// Add a second value to test multiple rollbacks
1110	1074	helpers.setValue(`${key}-2`, `${value}-2`);
1111	1075	},
1112		async refetch() {},
	1076
1113	1077	debounceMs: 50,
1114	1078	});
1115	1079
1116	1080	// First call sets two values
1117		mutation.runAndReturn("key1", "a");
	1081	mutation.runAsPromise("key1", "a");
1118	1082	assertEquals(testStore.get("key1"), "a");
1119	1083	assertEquals(testStore.get("key1-2"), "a-2");
1120	1084
1121	1085	// Second call should rollback first call's optimistic and apply its own
1122		const promise = mutation.runAndReturn("key1", "b");
	1086	const promise = mutation.runAsPromise("key1", "b");
1123	1087	assertEquals(testStore.get("key1"), "b");
1124	1088	assertEquals(testStore.get("key1-2"), "b-2");
1125	1089
...	...	@@ -1144,16 +1108,16 @@ test("BlockingMutation - debounce: timer reset behavior", async () => {
1144	1108	describe: "debounced mutation",
1145	1109	describeResult: "Success",
1146	1110	optimistic() {},
1147		async refetch() {},
	1111
1148	1112	debounceMs: 100,
1149	1113	});
1150	1114
1151	1115	// Call at t=0
1152		const promise1 = mutation.runAndReturn("first");
	1116	const promise1 = mutation.runAsPromise("first");
1153	1117
1154	1118	// Call at t=50 (should reset timer)
1155	1119	await delay(50);
1156		const promise2 = mutation.runAndReturn("second");
	1120	const promise2 = mutation.runAsPromise("second");
1157	1121
1158	1122	// At t=100, mutation should NOT have executed yet
1159	1123	await delay(50);
...	...	@@ -1180,18 +1144,18 @@ test("BlockingMutation - debounce: integration with blocking queue", async () =>
1180	1144	describe: "debounced mutation",
1181	1145	describeResult: "Success",
1182	1146	optimistic() {},
1183		async refetch() {},
	1147
1184	1148	debounceMs: 30,
1185	1149	key: () => "shared",
1186	1150	});
1187	1151
1188	1152	// Start a debounced call that will enter queue first
1189		const promise1 = mutation.runAndReturn("first");
	1153	const promise1 = mutation.runAsPromise("first");
1190	1154
1191	1155	// While it's waiting in debounce, fire more debounced calls
1192	1156	await delay(10);
1193		const promise2 = mutation.runAndReturn("second");
1194		const promise3 = mutation.runAndReturn("third");
	1157	const promise2 = mutation.runAsPromise("second");
	1158	const promise3 = mutation.runAsPromise("third");
1195	1159
1196	1160	// Wait for all to complete
1197	1161	await Promise.all([promise1, promise2, promise3]);
...	...	@@ -1220,13 +1184,13 @@ test("BlockingMutation - debounce: error during optimistic update", async () =>
1220	1184	}
1221	1185	helpers.setValue("key", value);
1222	1186	},
1223		async refetch() {},
	1187
1224	1188	debounceMs: 50,
1225	1189	});
1226	1190
1227	1191	// Call that throws during optimistic
1228	1192	await assertRejects(
1229		() => mutation.runAndReturn("error"),
	1193	() => mutation.runAsPromise("error"),
1230	1194	Error,
1231	1195	"optimistic error",
1232	1196	);
...	...	@@ -1235,7 +1199,7 @@ test("BlockingMutation - debounce: error during optimistic update", async () =>
1235	1199	assertEquals(testStore.has("key"), false);
1236	1200
1237	1201	// Subsequent successful call should work
1238		const promise = mutation.runAndReturn("good");
	1202	const promise = mutation.runAsPromise("good");
1239	1203	assertEquals(testStore.get("key"), "good");
1240	1204	await promise;
1241	1205	});
...	...	@@ -1251,10 +1215,12 @@ test("BlockingMutation - debounce: status transitions", async () => {
1251	1215	},
1252	1216	describe: "debounced mutation",
1253	1217	describeResult: "Success",
1254		optimistic() {},
1255		async refetch() {
1256		await delay(10);
	1218	optimistic({ onRefetch }) {
	1219	onRefetch(async () => {
	1220	await delay(10);
	1221	});
1257	1222	},
	1223
1258	1224	debounceMs: 50,
1259	1225	});
1260	1226
...	...	@@ -1262,7 +1228,7 @@ test("BlockingMutation - debounce: status transitions", async () => {
1262	1228	const unsubscribe = mutation.subscribe(key, callback);
1263	1229
1264	1230	// First call should transition to waiting
1265		mutation.runAndReturn("test");
	1231	mutation.runAsPromise("test");
1266	1232	await delay(10);
1267	1233	assertEquals(events[events.length - 1].status, "waiting");
1268	1234
...	...	@@ -1291,19 +1257,20 @@ test("BlockingMutation - debounce: debounced call executes after queue error", a
1291	1257	},
1292	1258	describe: "debounced mutation",
1293	1259	describeResult: "Success",
1294		optimistic() {},
1295		async refetch() {
1296		await delay(10);
	1260	optimistic({ onRefetch }) {
	1261	onRefetch(async () => {
	1262	await delay(10);
	1263	});
1297	1264	},
1298	1265	debounceMs: 50,
1299	1266	key: () => "shared",
1300	1267	});
1301	1268
1302	1269	// Start a call that will fail (enters debounce)
1303		const promise1 = mutation.runAndReturn("fail");
	1270	const promise1 = mutation.runAsPromise("fail");
1304	1271
1305	1272	// Immediately override with a successful call (last call wins)
1306		const promise2 = mutation.runAndReturn("success");
	1273	const promise2 = mutation.runAsPromise("success");
1307	1274
1308	1275	// Both promises should resolve with the same successful result
1309	1276	// (because debouncing causes "last call wins")
...	...	@@ -1327,20 +1294,20 @@ test("BlockingMutation - debounce: all promises resolve together", async () => {
1327	1294	describe: "debounced mutation",
1328	1295	describeResult: "Success",
1329	1296	optimistic() {},
1330		async refetch() {},
	1297
1331	1298	debounceMs: 50,
1332	1299	});
1333	1300
1334	1301	// Create three rapid calls
1335		const promise1 = mutation.runAndReturn("id", "a").then((result) => {
	1302	const promise1 = mutation.runAsPromise("id", "a").then((result) => {
1336	1303	resolvedAt.push(Date.now());
1337	1304	return result;
1338	1305	});
1339		const promise2 = mutation.runAndReturn("id", "b").then((result) => {
	1306	const promise2 = mutation.runAsPromise("id", "b").then((result) => {
1340	1307	resolvedAt.push(Date.now());
1341	1308	return result;
1342	1309	});
1343		const promise3 = mutation.runAndReturn("id", "c").then((result) => {
	1310	const promise3 = mutation.runAsPromise("id", "c").then((result) => {
1344	1311	resolvedAt.push(Date.now());
1345	1312	return result;
1346	1313	});
...	...	@@ -1367,7 +1334,7 @@ test("BlockingMutation - debounce: cleanup on channel deletion", async () => {
1367	1334	describe: "debounced mutation",
1368	1335	describeResult: "Success",
1369	1336	optimistic() {},
1370		async refetch() {},
	1337
1371	1338	debounceMs: 100,
1372	1339	});
1373	1340
...	...	@@ -1377,7 +1344,7 @@ test("BlockingMutation - debounce: cleanup on channel deletion", async () => {
1377	1344	const unsubscribe = mutation.subscribe(key, () => {});
1378	1345
1379	1346	// Start a debounced call
1380		mutation.runAndReturn("test");
	1347	mutation.runAsPromise("test");
1381	1348	await delay(10);
1382	1349
1383	1350	// Unsubscribe while debounce is pending
...	...	@@ -1403,16 +1370,16 @@ test("BlockingMutation - debounce: multiple keys debounce independently", async
1403	1370	describe: "debounced mutation",
1404	1371	describeResult: "Success",
1405	1372	optimistic() {},
1406		async refetch() {},
	1373
1407	1374	debounceMs: 50,
1408	1375	key: ({ args }) => args[0],
1409	1376	});
1410	1377
1411	1378	// Rapid calls to different keys
1412		const promise1a = mutation.runAndReturn("key1");
1413		const promise1b = mutation.runAndReturn("key1");
1414		const promise2a = mutation.runAndReturn("key2");
1415		const promise2b = mutation.runAndReturn("key2");
	1379	const promise1a = mutation.runAsPromise("key1");
	1380	const promise1b = mutation.runAsPromise("key1");
	1381	const promise2a = mutation.runAsPromise("key2");
	1382	const promise2b = mutation.runAsPromise("key2");
1416	1383
1417	1384	await Promise.all([promise1a, promise1b, promise2a, promise2b]);
1418	1385
...	...	@@ -1437,15 +1404,15 @@ test("BlockingMutation - debounce: onSuccess callbacks from last call only", asy
1437	1404	successResults.push(`${value}->${result}`);
1438	1405	});
1439	1406	},
1440		async refetch() {},
	1407
1441	1408	debounceMs: 50,
1442	1409	});
1443	1410
1444	1411	// Make three rapid calls with different onSuccess callbacks
1445	1412	await Promise.all([
1446		mutation.runAndReturn("a"),
1447		mutation.runAndReturn("b"),
1448		mutation.runAndReturn("c"),
	1413	mutation.runAsPromise("a"),
	1414	mutation.runAsPromise("b"),
	1415	mutation.runAsPromise("c"),
1449	1416	]);
1450	1417
1451	1418	await delay(20);

test/debounced.test.ts+39-64

...	...	@@ -89,7 +89,7 @@ test("DebouncedMutation - basic mutation success with debounce", async () => {
89	89	},
90	90	});
91	91
92		const result = await mutation.runAndReturn(5);
	92	const result = await mutation.runAsPromise(5);
93	93	await delay(20); // Wait for refetch
94	94
95	95	assertEquals(result, 5);
...	...	@@ -116,7 +116,6 @@ test("DebouncedMutation - run() catches errors", async () => {
116	116	},
117	117	describe: "failing mutation",
118	118	describeResult: "Success",
119		async refetch() {},
120	119	});
121	120
122	121	mutation.run(5);
...	...	@@ -144,11 +143,10 @@ test("DebouncedMutation - runAndReturn() rejects on error", async () => {
144	143	},
145	144	describe: "failing mutation",
146	145	describeResult: "Success",
147		async refetch() {},
148	146	});
149	147
150	148	await assertRejects(
151		() => mutation.runAndReturn(5),
	149	() => mutation.runAsPromise(5),
152	150	Error,
153	151	"commit failed",
154	152	);
...	...	@@ -181,13 +179,12 @@ test("DebouncedMutation - debounce batches rapid calls", async () => {
181	179	},
182	180	describe: "increment counter",
183	181	describeResult: "Success",
184		async refetch() {},
185	182	});
186	183
187	184	// Rapid calls within debounce window
188		const promise1 = mutation.runAndReturn(1);
189		const promise2 = mutation.runAndReturn(2);
190		const promise3 = mutation.runAndReturn(3);
	185	const promise1 = mutation.runAsPromise(1);
	186	const promise2 = mutation.runAsPromise(2);
	187	const promise3 = mutation.runAsPromise(3);
191	188
192	189	// Optimistic updates should be applied immediately
193	190	assertEquals(testStore.get("counter"), 6);
...	...	@@ -223,17 +220,16 @@ test("DebouncedMutation - debounce resets timer on each call", async () => {
223	220	},
224	221	describe: "increment counter",
225	222	describeResult: "Success",
226		async refetch() {},
227	223	});
228	224
229	225	// First call
230		const promise1 = mutation.runAndReturn(1);
	226	const promise1 = mutation.runAsPromise(1);
231	227
232	228	// Wait less than debounce time
233	229	await delay(15);
234	230
235	231	// Second call should reset the timer
236		const promise2 = mutation.runAndReturn(2);
	232	const promise2 = mutation.runAsPromise(2);
237	233
238	234	// Wait less than debounce time again
239	235	await delay(15);
...	...	@@ -242,7 +238,7 @@ test("DebouncedMutation - debounce resets timer on each call", async () => {
242	238	assertEquals(commitCallCount, 0);
243	239
244	240	// Third call
245		const promise3 = mutation.runAndReturn(3);
	241	const promise3 = mutation.runAsPromise(3);
246	242
247	243	// Wait for all to complete
248	244	await Promise.all([promise1, promise2, promise3]);
...	...	@@ -274,15 +270,14 @@ test("DebouncedMutation - debounce separates batches after timeout", async () =>
274	270	},
275	271	describe: "increment counter",
276	272	describeResult: "Success",
277		async refetch() {},
278	273	});
279	274
280	275	// First batch
281		await mutation.runAndReturn(1);
	276	await mutation.runAsPromise(1);
282	277	await delay(50); // Wait for first batch to complete
283	278
284	279	// Second batch (after timeout)
285		await mutation.runAndReturn(2);
	280	await mutation.runAsPromise(2);
286	281	await delay(50);
287	282
288	283	// Two separate commits
...	...	@@ -319,10 +314,9 @@ test("DebouncedMutation - throttle commits immediately on first call", async ()
319	314	},
320	315	describe: "increment counter",
321	316	describeResult: "Success",
322		async refetch() {},
323	317	});
324	318
325		await mutation.runAndReturn(5);
	319	await mutation.runAsPromise(5);
326	320
327	321	// First call should commit immediately (within a small tolerance)
328	322	assertEquals(commitTime < 20, true);
...	...	@@ -352,19 +346,18 @@ test("DebouncedMutation - throttle batches calls within time window", async () =
352	346	},
353	347	describe: "increment counter",
354	348	describeResult: "Success",
355		async refetch() {},
356	349	});
357	350
358	351	// First call commits immediately
359		const promise1 = mutation.runAndReturn(1);
	352	const promise1 = mutation.runAsPromise(1);
360	353	await delay(5);
361	354
362	355	// Second call within throttle window - should batch
363		const promise2 = mutation.runAndReturn(2);
	356	const promise2 = mutation.runAsPromise(2);
364	357	await delay(5);
365	358
366	359	// Third call within throttle window - should batch with second
367		const promise3 = mutation.runAndReturn(3);
	360	const promise3 = mutation.runAsPromise(3);
368	361
369	362	// Wait for first to complete
370	363	await promise1;
...	...	@@ -403,11 +396,10 @@ test("DebouncedMutation - throttle allows new batch after time window", async ()
403	396	},
404	397	describe: "increment counter",
405	398	describeResult: "Success",
406		async refetch() {},
407	399	});
408	400
409	401	// First call
410		await mutation.runAndReturn(1);
	402	await mutation.runAsPromise(1);
411	403	await delay(10);
412	404
413	405	assertEquals(commitCallCount, 1);
...	...	@@ -416,7 +408,7 @@ test("DebouncedMutation - throttle allows new batch after time window", async ()
416	408	await delay(60);
417	409
418	410	// Second call should commit immediately
419		await mutation.runAndReturn(2);
	411	await mutation.runAsPromise(2);
420	412	await delay(10);
421	413
422	414	assertEquals(commitCallCount, 2);
...	...	@@ -447,12 +439,11 @@ test("DebouncedMutation - skips commit when value unchanged", async () => {
447	439	},
448	440	describe: "increment counter",
449	441	describeResult: "Success",
450		async refetch() {},
451	442	});
452	443
453	444	// +5 and -5 cancel out
454		const promise1 = mutation.runAndReturn(5);
455		const promise2 = mutation.runAndReturn(-5);
	445	const promise1 = mutation.runAsPromise(5);
	446	const promise2 = mutation.runAsPromise(-5);
456	447
457	448	const [result1, result2] = await Promise.all([promise1, promise2]);
458	449
...	...	@@ -507,11 +498,10 @@ test("DebouncedMutation - uses deepEquals for comparison", async () => {
507	498	},
508	499	describe: "set count",
509	500	describeResult: "Success",
510		async refetch() {},
511	501	});
512	502
513	503	// Set to same value (different object reference but same content)
514		await mutation.runAndReturn(0);
	504	await mutation.runAsPromise(0);
515	505	await delay(30);
516	506
517	507	// Should skip commit because value is deeply equal
...	...	@@ -559,10 +549,9 @@ test("DebouncedMutation - custom deepEquals function", async () => {
559	549	},
560	550	describe: "failing mutation",
561	551	describeResult: "Success",
562		async refetch() {},
563	552	});
564	553
565		await mutation.runAndReturn(5).catch(() => {
	554	await mutation.runAsPromise(5).catch(() => {
566	555	// Expected to fail due to commit error
567	556	});
568	557	await delay(30);
...	...	@@ -593,11 +582,10 @@ test("DebouncedMutation - rollback on commit error", async () => {
593	582	},
594	583	describe: "failing mutation",
595	584	describeResult: "Success",
596		async refetch() {},
597	585	});
598	586
599	587	// Optimistic update applied
600		const promise = mutation.runAndReturn(5);
	588	const promise = mutation.runAsPromise(5);
601	589	assertEquals(testStore.get("counter"), 15);
602	590
603	591	await assertRejects(() => promise, Error, "commit failed");
...	...	@@ -626,13 +614,12 @@ test("DebouncedMutation - error event includes error details", async () => {
626	614	},
627	615	describe: "failing mutation",
628	616	describeResult: "Success",
629		async refetch() {},
630	617	});
631	618
632	619	const key = mutation.key([5]);
633	620	mutation.subscribe(key, tracker.callback);
634	621
635		await assertRejects(() => mutation.runAndReturn(5));
	622	await assertRejects(() => mutation.runAsPromise(5));
636	623	await delay(30);
637	624
638	625	// Should have error in events
...	...	@@ -660,7 +647,6 @@ test("DebouncedMutation - key() returns JSON stringified key", () => {
660	647	},
661	648	describe: "test mutation",
662	649	describeResult: "Success",
663		async refetch() {},
664	650	});
665	651
666	652	assertEquals(mutation.key(["test-id"]), JSON.stringify("test-id"));
...	...	@@ -681,7 +667,6 @@ test("DebouncedMutation - key() can return array", () => {
681	667	},
682	668	describe: "test mutation",
683	669	describeResult: "Success",
684		async refetch() {},
685	670	});
686	671
687	672	assertEquals(
...	...	@@ -712,12 +697,11 @@ test("DebouncedMutation - different keys create separate batches", async () => {
712	697	},
713	698	describe: "test mutation",
714	699	describeResult: "Success",
715		async refetch() {},
716	700	});
717	701
718	702	// Two different keys
719		const promise1 = mutation.runAndReturn("a", 5);
720		const promise2 = mutation.runAndReturn("b", 10);
	703	const promise1 = mutation.runAsPromise("a", 5);
	704	const promise2 = mutation.runAsPromise("b", 10);
721	705
722	706	await Promise.all([promise1, promise2]);
723	707	await delay(30);
...	...	@@ -747,7 +731,6 @@ test("DebouncedMutation - describe() with string", () => {
747	731	},
748	732	describe: "update counter",
749	733	describeResult: "Success",
750		async refetch() {},
751	734	});
752	735
753	736	assertEquals(mutation.describe(5), "update counter");
...	...	@@ -768,7 +751,6 @@ test("DebouncedMutation - describe() with function", () => {
768	751	},
769	752	describe: ({ args }) => `increment by ${args[0]}`,
770	753	describeResult: "Success",
771		async refetch() {},
772	754	});
773	755
774	756	assertEquals(mutation.describe(5), "increment by 5");
...	...	@@ -796,12 +778,11 @@ test("DebouncedMutation - all pending promises resolve with same result", async
796	778	},
797	779	describe: "increment counter",
798	780	describeResult: "Success",
799		async refetch() {},
800	781	});
801	782
802		const promise1 = mutation.runAndReturn(1);
803		const promise2 = mutation.runAndReturn(2);
804		const promise3 = mutation.runAndReturn(3);
	783	const promise1 = mutation.runAsPromise(1);
	784	const promise2 = mutation.runAsPromise(2);
	785	const promise3 = mutation.runAsPromise(3);
805	786
806	787	const [result1, result2, result3] = await Promise.all([
807	788	promise1,
...	...	@@ -833,12 +814,11 @@ test("DebouncedMutation - all pending promises reject with same error", async ()
833	814	},
834	815	describe: "increment counter",
835	816	describeResult: "Success",
836		async refetch() {},
837	817	});
838	818
839		const promise1 = mutation.runAndReturn(1);
840		const promise2 = mutation.runAndReturn(2);
841		const promise3 = mutation.runAndReturn(3);
	819	const promise1 = mutation.runAsPromise(1);
	820	const promise2 = mutation.runAsPromise(2);
	821	const promise3 = mutation.runAsPromise(3);
842	822
843	823	const errors: Error[] = [];
844	824	await Promise.all([
...	...	@@ -880,7 +860,7 @@ test("DebouncedMutation - handles empty getValue result", async () => {
880	860	describeResult: "Success",
881	861	});
882	862
883		const result = await mutation.runAndReturn(5);
	863	const result = await mutation.runAsPromise(5);
884	864	await delay(30);
885	865
886	866	assertEquals(commitCallCount, 1);
...	...	@@ -906,15 +886,14 @@ test("DebouncedMutation - channel cleanup after idle with no listeners", async (
906	886	},
907	887	describe: "test mutation",
908	888	describeResult: "Success",
909		async refetch() {},
910	889	});
911	890
912	891	// Run mutation without subscribing
913		await mutation.runAndReturn(5);
	892	await mutation.runAsPromise(5);
914	893	await delay(30);
915	894
916	895	// Run another mutation - should work fine (channel recreated if needed)
917		const result = await mutation.runAndReturn(3);
	896	const result = await mutation.runAsPromise(3);
918	897	await delay(30);
919	898
920	899	assertEquals(result, 3);
...	...	@@ -943,10 +922,9 @@ test("DebouncedMutation - default time is 200ms", async () => {
943	922	},
944	923	describe: "test mutation",
945	924	describeResult: "Success",
946		async refetch() {},
947	925	});
948	926
949		await mutation.runAndReturn(5);
	927	await mutation.runAsPromise(5);
950	928
951	929	// Should commit after ~200ms (with some tolerance)
952	930	assertEquals(commitTime !== null, true);
...	...	@@ -977,10 +955,9 @@ test("DebouncedMutation - context is passed to getValue", async () => {
977	955	},
978	956	describe: "test mutation",
979	957	describeResult: "Success",
980		async refetch() {},
981	958	});
982	959
983		await mutation.runAndReturn(5);
	960	await mutation.runAsPromise(5);
984	961	await delay(30);
985	962
986	963	assertEquals(receivedUserId, "test-user");
...	...	@@ -1007,10 +984,9 @@ test("DebouncedMutation - context is passed to commit", async () => {
1007	984	},
1008	985	describe: "test mutation",
1009	986	describeResult: "Success",
1010		async refetch() {},
1011	987	});
1012	988
1013		await mutation.runAndReturn(5);
	989	await mutation.runAsPromise(5);
1014	990	await delay(30);
1015	991
1016	992	assertEquals(receivedUserId, "test-user");
...	...	@@ -1037,12 +1013,11 @@ test("DebouncedMutation - first args are used for commit", async () => {
1037	1013	},
1038	1014	describe: "test mutation",
1039	1015	describeResult: "Success",
1040		async refetch() {},
1041	1016	});
1042	1017
1043		mutation.runAndReturn("first", 1);
1044		mutation.runAndReturn("second", 2);
1045		await mutation.runAndReturn("third", 3);
	1018	mutation.runAsPromise("first", 1);
	1019	mutation.runAsPromise("second", 2);
	1020	await mutation.runAsPromise("third", 3);
1046	1021	await delay(10);
1047	1022
1048	1023	// Should use first args