Commit 7ad627cb1d7df5aad122280d12e72244e86cb447 | react-mutation

jsr.json+6-3

 @@ -1,10 +1,10 @@
 {
   "name": "@clo/react-mutation",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "exports": {
     ".": "./src/mod.ts",
-    "./tanstack-query.ts": "./src/tanstack-query.ts",
+    "./tanstack-query": "./src/tanstack-query.ts",
-    "./object-path.ts": "./src/object-path.ts"
+    "./object-path": "./src/object-path.ts"
   },
   "imports": {
     "@tanstack/react-query": "npm:@tanstack/react-query@^5",
 @@ -16,6 +16,9 @@
       "README.md",
       "src/**/*",
       "test/**/*"
+    ],
+    "exclude": [
+      "src/play.ts"
     ]
   },
   "license": "ISC"

package.json+5

 @@ -15,6 +15,11 @@
     "@clo/lib": "npm:@jsr/clo__lib@^3.0.0",
     "@std/assert": "npm:@jsr/std__assert@^1.0.17"
   },
+  "exports": {
+    ".": "./src/mod.ts",
+    "./tanstack-query": "./src/tanstack-query.ts",
+    "./object-path": "./src/object-path.ts"
+  },
   "devDependencies": {
     "@tanstack/react-query": "^5.90.20",
     "@testing-library/react": "^16.3.2",

readme.changes.md+28

...	@@ -1,5 +1,32 @@	...	@@ -1,5 +1,32 @@
1	# notable changes in React Mutation	1	# notable changes in React Mutation
2		2
		3	## v3
		4
		5	### breaking
		6
		7	- `id` is now required for all mutations. It must be unique per client;
		8	duplicate registration throws in production and replaces the previous
		9	registration in development (hot reload re-runs `define`).
		10	- mutation arguments must be JSON serializable (`Json[]`)
		11	- `handleUnauthenticated` and `onUnauthenticated` now receive a serializable
		12	`MutationAction` (`{ id, description, args }`) instead of a description string
		13
		14	### features
		15
		16	- authentication integration for mutations (`auth: true`, `userContext`,
		17	`isAllowed`, `handleUnauthenticated`)
		18	- auth scopes for permission gates: declare `authScopes` on the client and
		19	`auth: "<scope>"` on mutations
		20	- `MutationClient.run(action)` re-runs a stored `MutationAction`, enabling
		21	sign-in flows that resume the blocked mutation
		22	- `MutationButton` hides non-allowed mutations that cannot route to the
		23	sign-in flow; opt out with `showNotAllowed`
		24
		25	### bugfixes
		26
		27	- `runAsHeadlessPromise` correctly rethrows the underlying error
		28	- clarify some intent in the readme
		29
3	## v2.1.0	30	## v2.1.0
4		31
5	### features	32	### features
...	@@ -14,6 +41,7 @@	...	@@ -14,6 +41,7 @@
14	### bugfixes	41	### bugfixes
15		42
16	- typescript violation not passing client context to optimistic handlers	43	- typescript violation not passing client context to optimistic handlers
		44	- `onSuccess` prop split into `onSuccessUi` and `onSuccessData`. but it didn't even work before so this isn't breaking.
17		45
18	## v2	46	## v2
19		47

readme.md+79-5

...	@@ -28,10 +28,7 @@ React Mutation starts with a `MutationClient`, which shares global state for an	...	@@ -28,10 +28,7 @@ React Mutation starts with a `MutationClient`, which shares global state for an
28	```ts	28	```ts
29	import { showToastUI } from "...";	29	import { showToastUI } from "...";
30	import { MutationClient } from "@clo/react-mutation";	30	import { MutationClient } from "@clo/react-mutation";
31	import {	31	import { boundQueryClientGet, queryClientOptimisticHelpers, reactiveFromQueryCache } from "@clo/react-mutation/tanstack-query";
32	boundQueryClientGet,
33	queryClientOptimisticHelpers,
34	} from "@clo/react-mutation";
35	import { QueryClient } from "@tanstack/react-query";	32	import { QueryClient } from "@tanstack/react-query";
36		33
37	const queryClient = new QueryClient();	34	const queryClient = new QueryClient();
...	@@ -39,7 +36,7 @@ export const mutations = new MutationClient({	...	@@ -39,7 +36,7 @@ export const mutations = new MutationClient({
39	// All properties in `context` are available within every function.	36	// All properties in `context` are available within every function.
40	context: {	37	context: {
41	client: queryClient,	38	client: queryClient,
42	get: boundQueryClientGet(client),	39	get: boundQueryClientGet(queryClient),
43		40
44	// Can add any easy helpers for your codebase.	41	// Can add any easy helpers for your codebase.
45	navigateAway: (urlThatIsBeingDeleted: string, redirect: string) => ...,	42	navigateAway: (urlThatIsBeingDeleted: string, redirect: string) => ...,
...	@@ -62,6 +59,33 @@ export const mutations = new MutationClient({	...	@@ -62,6 +59,33 @@ export const mutations = new MutationClient({
62	reportSuccess(userFriendlySuccessMessage: string) {	59	reportSuccess(userFriendlySuccessMessage: string) {
63	showToastUI("success", userFriendlyErrorMessage);	60	showToastUI("success", userFriendlyErrorMessage);
64	},	61	},
		62
		63	// Optionally, your session system can be integrated to provide `auth: true`
		64	// mutations that require a sign in before enabling. When a mutation cannot
		65	// be performed due to missing auth, its `isAllowed` field reads false.
		66	userContext: reactiveFromQueryCache(
		67	queryClient,
		68	queryCurrentUser,
		69	(user) => user ? { user } : null,
		70	),
		71	// Optionally, on top of `userContext`, custom subsets of authentication can be
		72	// defined for different permission levels, for example admin-only. This is used
		73	// at the call site with `auth: "admin"`.
		74	authScopes: {
		75	admin: reactiveFromQueryCache(queryClient, queryCurrentUser, (user) => !!user?.isAdmin),
		76	},
		77	// On top of `userContext`, the session system can integrate its login flow to
		78	// the mutation system. When configured, all authenticated mutations will be
		79	// marked enabled but `!isAllowed`, except ones in scopes (so an admin
		80	// mutation is still disabled and not allowed). When triggering a mutation, it
		81	// is routed to this function instead.
		82	handleUnauthenticated(action, mutation) {
		83	// `action` is serializable. Could commit it to `sessionStorage` to survive
		84	// a full-page sign-in flow, for example.
		85	openLoginModal(`Sign in to ${action.description}`, () => {
		86	mutations.run(action);
		87	});
		88	},
65	});	89	});
66	```	90	```
67		91
...	@@ -76,6 +100,8 @@ const queryItem = (id: string) => queryOptions({ ... });	...	@@ -76,6 +100,8 @@ const queryItem = (id: string) => queryOptions({ ... });
76		100
77	// The convention is to name handlers starting with `mut`	101	// The convention is to name handlers starting with `mut`
78	const mutDeleteItem = mutations.define({	102	const mutDeleteItem = mutations.define({
		103	// A stable identifier, unique per application.
		104	id: "item/delete",
79	// `mutate` comes first (for type inference), and	105	// `mutate` comes first (for type inference), and
80	// is only worried about syncing with the backend.	106	// is only worried about syncing with the backend.
81	async mutate(id: string) {	107	async mutate(id: string) {
...	@@ -217,6 +243,7 @@ will override the earlier calls by rolling back the optimistic state.	...	@@ -217,6 +243,7 @@ will override the earlier calls by rolling back the optimistic state.
217		243
218	```tsx	244	```tsx
219	const mutUpdateField = mutations.define({	245	const mutUpdateField = mutations.define({
		246	id: "item/update-field",
220	async mutate(id: string, value: string) { /* mutation */ },	247	async mutate(id: string, value: string) { /* mutation */ },
221	optimistic({ args: [id, value], helpers }) {	248	optimistic({ args: [id, value], helpers }) {
222	helpers.objSet(queryItem(id), ["value"], value);	249	helpers.objSet(queryItem(id), ["value"], value);
...	@@ -252,6 +279,7 @@ anything, `snapshot` can be used to detect no-op mutations.	...	@@ -252,6 +279,7 @@ anything, `snapshot` can be used to detect no-op mutations.
252		279
253	```tsx	280	```tsx
254	const mutUpdateField = mutations.define({	281	const mutUpdateField = mutations.define({
		282	id: "item/update-field",
255	async mutate(id: string, value: string) {/* mutation */},	283	async mutate(id: string, value: string) {/* mutation */},
256		284
257	optimistic({ args: [id, value], helpers }) {	285	optimistic({ args: [id, value], helpers }) {
...	@@ -284,6 +312,8 @@ The `useMutate(null \| Mutation)` react hook returns an object with the following	...	@@ -284,6 +312,8 @@ The `useMutate(null \| Mutation)` react hook returns an object with the following
284	- `run` (Function) this starts the mutation.	312	- `run` (Function) this starts the mutation.
285	- `clear` (Function) clear the status of sucess or error states.	313	- `clear` (Function) clear the status of sucess or error states.
286	- `isPending` (boolean) if a loading indicator should be visible.	314	- `isPending` (boolean) if a loading indicator should be visible.
		315	- `isDisabled` (boolean) if the underlying form/button should be disabled
		316	- `isAllowed` (boolean) if the mutation is allowed considering authentication and pre-checks
287	- `isSuccess` (boolean) if the mutation has succeeded.	317	- `isSuccess` (boolean) if the mutation has succeeded.
288	- `result` (Result or undefined) the successful result of the mutation.	318	- `result` (Result or undefined) the successful result of the mutation.
289	- `isError` (boolean) if the mutation failed.	319	- `isError` (boolean) if the mutation failed.
...	@@ -361,3 +391,47 @@ It can now be used for easy mutations:	...	@@ -361,3 +391,47 @@ It can now be used for easy mutations:
361	</MutationButton>	391	</MutationButton>
362	</>;	392	</>;
363	```	393	```
		394
		395	## Authenticated Mutations
		396
		397	Once the `MutationClient` is connected to the application's authentication
		398	system, mutations themselves can declare `auth: true`. This does two things:
		399
		400	- `useMutate` and mutation buttons read `isAllowed: false` while signed out.
		401	Without a `handleUnauthenticated` handler they also disable; with one they
		402	stay enabled so a click can route to the sign-in flow.
		403	- The mutation implementation is given the `UserContext` to utilize.
		404
		405	`describe` is the one function whose user context is nullable: it also runs
		406	while signed out to build the `action.description` given to the sign-in flow.
		407
		408	```tsx
		409	const mutUpdateBio = mutations.define({
		410	id: "user/update-bio",
		411	auth: true,
		412	async mutate(bio: string) {
		413	this.user; // if the user context, if needed
		414	},
		415	optimistic({ args: [bio], helpers }) {
		416	helpers.objSet(queryCurrentUser(), ["bio"], bio);
		417	},
		418	// (...the rest...)
		419	});
		420	```
		421
		422	Scopes can allow easily adding permission gates. Unlike `auth: true`, a scoped
		423	mutation whose scope is unsatisfied always disables; it is never routed to
		424	`handleUnauthenticated`.
		425
		426	```tsx
		427	const mutBanUser = mutations.define({
		428	id: "user/ban",
		429	auth: "admin",
		430	async mutate(targetId: string) {/* mutation */},
		431	// (...the rest...)
		432	});
		433	```
		434
		435	By default, `MutationButton` will hide non-allowed mutations that cannot route
		436	to the sign-in flow, which can be opted out by passing the `showNotAllowed`
		437	prop.

src/client.ts+82-8

...	@@ -1,21 +1,30 @@	...	@@ -1,21 +1,30 @@
1	import { BlockingMutation, type MutationOptions } from "./mutation.ts";	1	import { BlockingMutation, type MutationOptions } from "./mutation.ts";
2	import type { Mutation } from "./types.ts";	2	import type { Json, Mutation, MutationAction } from "./types.ts";
3		3
4	export interface MutationClientConfig {	4	export interface MutationClientConfig {
5	context: {};	5	context: {};
6	optimisticHelpers: {};	6	optimisticHelpers: {};
		7	userContext: {};
		8	authScopes: string;
7	}	9	}
8		10
9	export type MutationClientFromConfig<Config extends MutationClientConfig> = MutationClient<	11	export type MutationClientFromConfig<Config extends MutationClientConfig> = MutationClient<
10	Config["context"],	12	Config["context"],
11	Config["optimisticHelpers"]	13	Config["optimisticHelpers"],
		14	Config["userContext"],
		15	Config["authScopes"]
12	>;	16	>;
13		17
14	const defaultDeepEquals = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);	18	const defaultDeepEquals = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
15		19
		20	// Declared locally to avoid depending on node types.
		21	declare const process: { env: { NODE_ENV?: string } };
		22
16	export interface MutationClientOptions<	23	export interface MutationClientOptions<
17	Context extends object,	24	Context extends object,
18	OptimisticHelpers extends object,	25	OptimisticHelpers extends object,
		26	UserContext extends object = {},
		27	AuthScopes extends string = never,
19	> {	28	> {
20	context: Context;	29	context: Context;
21	getOptimisticHelpers: (	30	getOptimisticHelpers: (
...	@@ -35,6 +44,30 @@ export interface MutationClientOptions<	...	@@ -35,6 +44,30 @@ export interface MutationClientOptions<
35	* @default true	44	* @default true
36	*/	45	*/
37	enabled?: boolean;	46	enabled?: boolean;
		47	/** To support authenticated mutations, define a function that returns additional context. */
		48	userContext?: Reactive<UserContext \| null>;
		49	/**
		50	* Subsets of authentication for different permission levels, used at the
		51	* define site with `auth: "<scope>"`. A scoped mutation is allowed only when
		52	* a user is available and its scope reads `true`; unlike `auth: true`, it is
		53	* never routed to `handleUnauthenticated`.
		54	*/
		55	authScopes?: Record<AuthScopes, Reactive<boolean>>;
		56	/**
		57	* Called instead of running an authenticated mutation when no user is
		58	* available. The action is JSON serializable and can be stored, then passed
		59	* to {@linkcode MutationClient.run} once the user signs in.
		60	*/
		61	handleUnauthenticated?: (
		62	this: { context: Context },
		63	action: MutationAction,
		64	mutation: Mutation<Json[], unknown>,
		65	) => void;
		66	}
		67
		68	export interface Reactive<T> {
		69	get: () => T;
		70	sub: (onChange: () => void) => () => void;
38	}	71	}
39		72
40	export interface OptimisticEvents {	73	export interface OptimisticEvents {
...	@@ -45,16 +78,25 @@ export interface OptimisticEvents {	...	@@ -45,16 +78,25 @@ export interface OptimisticEvents {
45	export class MutationClient<	78	export class MutationClient<
46	Context extends object,	79	Context extends object,
47	OptimisticHelpers extends object,	80	OptimisticHelpers extends object,
		81	UserContext extends object = {},
		82	AuthScopes extends string = never,
48	> {	83	> {
49	context: Context;	84	context: Context;
		85	userContext?: Reactive<UserContext \| null>;
		86	authScopes?: { [scope: string]: Reactive<boolean> };
		87	handleUnauthenticated?: (action: MutationAction, mutation: Mutation<Json[], unknown>) => void;
50	getOptimisticHelpers: (event: OptimisticEvents) => OptimisticHelpers;	88	getOptimisticHelpers: (event: OptimisticEvents) => OptimisticHelpers;
51	reportError: (message: string, error: unknown) => void;	89	reportError: (message: string, error: unknown) => void;
52	reportSuccess?: (message: string) => void;	90	reportSuccess?: (message: string) => void;
53	deepEquals: (a: unknown, b: unknown) => boolean;	91	deepEquals: (a: unknown, b: unknown) => boolean;
54	enabled: boolean;	92	enabled: boolean;
		93	#mutations: Map<string, Mutation<Json[], unknown>> = new Map();
55		94
56	constructor(options: MutationClientOptions<Context, OptimisticHelpers>) {	95	constructor(options: MutationClientOptions<Context, OptimisticHelpers, UserContext, AuthScopes>) {
57	this.context = options.context;	96	this.context = options.context;
		97	this.userContext = options.userContext;
		98	this.authScopes = options.authScopes;
		99	this.handleUnauthenticated = options.handleUnauthenticated;
58	this.getOptimisticHelpers = options.getOptimisticHelpers;	100	this.getOptimisticHelpers = options.getOptimisticHelpers;
59	this.reportError = options.reportError;	101	this.reportError = options.reportError;
60	this.reportSuccess = options.reportSuccess;	102	this.reportSuccess = options.reportSuccess;
...	@@ -65,17 +107,49 @@ export class MutationClient<	...	@@ -65,17 +107,49 @@ export class MutationClient<
65	/**	107	/**
66	* Define a standard mutation.	108	* Define a standard mutation.
67	*/	109	*/
68	define<const Args extends unknown[], Result>(	110	define<const Args extends Json[], Result, const Auth extends boolean \| AuthScopes = false>(
69	options: MutationOptions<	111	options: MutationOptions<
70	Args,	112	Args,
71	Result,	113	Result,
72	{ context: Context; optimisticHelpers: OptimisticHelpers }	114	Auth,
		115	{ context: Context; optimisticHelpers: OptimisticHelpers; userContext: UserContext; authScopes: AuthScopes }
73	>,	116	>,
74	): Mutation<Args, Result> {	117	): Mutation<Args, Result> {
75	return new BlockingMutation<	118	if (typeof options.auth === "string" && !this.authScopes?.[options.auth]) {
		119	throw new Error(`Unknown auth scope "${options.auth}".`);
		120	}
		121	if (this.#mutations.has(options.id)) {
		122	// Hot reload re-evaluates defining modules against the same client, so
		123	// a duplicate is assumed to be a replacement unless this is positively
		124	// a production build. The `typeof` guard supports unbundled browsers;
		125	// bundled browser builds inline NODE_ENV but leave `typeof process`
		126	// alone, which downgrades them to the replace-and-warn path.
		127	if (typeof process !== "undefined" && process.env.NODE_ENV === "production") {
		128	throw new Error(`Mutation id "${options.id}" is already registered.`);
		129	}
		130	console.error(`Mutation id "${options.id}" registered twice; assuming hot reload and replacing it.`);
		131	}
		132	const mutation = new BlockingMutation<
76	Args,	133	Args,
77	Result,	134	Result,
78	{ context: Context; optimisticHelpers: OptimisticHelpers }	135	Auth,
79	>(this, options);	136	{ context: Context; optimisticHelpers: OptimisticHelpers; userContext: UserContext; authScopes: AuthScopes }
		137	>(
		138	this,
		139	options,
		140	);
		141	this.#mutations.set(options.id, mutation as unknown as Mutation<Json[], unknown>);
		142	return mutation;
		143	}
		144
		145	/**
		146	* Re-run a mutation from a stored {@linkcode MutationAction}, such as one
		147	* captured by `handleUnauthenticated` before the user signed in. Results are
		148	* reported through the global handlers.
		149	*/
		150	run(action: Pick<MutationAction, "id" \| "args">): void {
		151	const mutation = this.#mutations.get(action.id);
		152	if (!mutation) throw new Error(`Mutation id "${action.id}" is not registered.`);
		153	mutation.run(...action.args);
80	}	154	}
81	}	155	}

src/mod.ts+2-1

...	@@ -3,6 +3,7 @@ export {	...	@@ -3,6 +3,7 @@ export {
3	type MutationClientConfig,	3	type MutationClientConfig,
4	type MutationClientFromConfig,	4	type MutationClientFromConfig,
5	type MutationClientOptions,	5	type MutationClientOptions,
		6	type Reactive,
6	} from "./client.ts";	7	} from "./client.ts";
7	export type { MutationOptions, OptimisticContext } from "./mutation.ts";	8	export type { MutationOptions, OptimisticContext } from "./mutation.ts";
8	export {	9	export {
...	@@ -16,4 +17,4 @@ export {	...	@@ -16,4 +17,4 @@ export {
16	type UseMutateResultBase,	17	type UseMutateResultBase,
17	type UseMutateSuccess,	18	type UseMutateSuccess,
18	} from "./react.ts";	19	} from "./react.ts";
19	export type { Mutation, MutationEvent } from "./types.ts";	20	export type { Json, Mutation, MutationAction, MutationEvent } from "./types.ts";

src/mutation.ts+152-50

 @@ -1,7 +1,7 @@
 import { message as errMessage } from "@clo/lib/error.ts";
-import type { MutationClient, MutationClientFromConfig } from "./client.ts";
+import type { MutationClientFromConfig, Reactive } from "./client.ts";
 import type { MutationClientConfig } from "./client.ts";
-import type { Mutation, MutationEvent, RunOptions } from "./types.ts";
+import type { Json, Mutation, MutationEvent, RunOptions } from "./types.ts";
 /**
  * Argument to `defineBlocking`.
 @@ -10,10 +10,26 @@ import type { Mutation, MutationEvent, RunOptions } from "./types.ts";
  * @template Config - global values and helpers from `MutationContext`
  */
 export interface MutationOptions<
-  Args extends unknown[],
+  Args extends Json[],
   Result,
+  Auth extends boolean | string,
   Config extends MutationClientConfig,
 > {
+  /**
+   * Stable identifier, unique per client; duplicate registration throws in
+   * production and replaces the previous registration in development, where
+   * hot reload re-runs `define`. Identifies the mutation in a stored
+   * `MutationAction` so a call attempted while signed out can be restored
+   * with `MutationClient.run`.
+   */
+  id: string;
+  /**
+   * Require a current user before the mutation can run. Passing one of the
+   * client's `authScopes` additionally requires that scope to read `true`.
+   */
+  auth?: Auth;
+  /** Additional guard for fine-grained auth or domain-specific availability. */
+  isAllowed?: Reactive<boolean>;
   /**
    * This function is only responsible for performing the underlying API call,
    * syncronizing the optimistic state with reality. Throw on failure. A rest
 @@ -24,27 +40,31 @@ export interface MutationOptions<
    * In practice, optimistic context is never needed in this function, but it
    * is provided as the `this` value if you truly desire it.
    */
-  mutate: (this: Config["context"], ...args: Args) => Promise<Result>;
+  mutate: (this: Context<Config, Auth>, ...args: Args) => Promise<Result>;
+  /**
+   * Specifying the optimistic strategy is required. To disable, pass an empty
+   * function with a comment to document why it isn't needed.
+   */
+  optimistic: (
+    context: OptimisticContext<Args, Result, Config, Auth>,
+  ) => void;
   /**
    * Used in error messages and debug tools.
    * Phrase it considering the template `Could not ${describe(...)}`
+   *
+   * Unlike every other function, user context is nullable: this also runs
+   * while signed out to build the `MutationAction` description given to the
+   * sign-in flow.
    */
-  describe: string | ((context: Config["context"] & { args: Args }) => string);
+  describe: string | ((context: Context<Config, false> & { args: Args }) => string);
   /**
    * Used in success messages.
    * Phrase it as a complete success message: "Deleted Item"
    */
   describeResult:
     | string
-    | ((context: Config["context"] & { args: Args; result: Result }) => string)
+    | ((context: Context<Config, Auth> & { args: Args; result: Result }) => string)
     | null;
-  /**
-   * Specifying the optimistic strategy is required. To disable, pass an empty
-   * function with a comment to document why it isn't needed.
-   */
-  optimistic: (
-    context: OptimisticContext<Args, Result, Config>,
-  ) => void;
   /**
    * If the optimistic updator function is perfect, then this may be set to false.
    * @default true
 @@ -55,7 +75,7 @@ export interface MutationOptions<
    * specifying, then all mutations of the same key will evaluate in serial,
    * but optimistic updates will apply instantly.
    */
-  key?: (context: Config["context"] & { args: Args }) => string | string[];
+  key?: (context: Context<Config, Auth> & { args: Args }) => string | string[];
   /**
    * Enable debouncing with "last call wins" behavior. When rapid calls arrive,
    * the previous optimistic update is rolled back and the new one applied.
 @@ -76,14 +96,19 @@ export interface MutationOptions<
    * If the snapshots are equal (using deepEquals), the mutation is cancelled.
    * Only `onSettled` callbacks fire, not `onSuccess` or global handlers.
    */
-  snapshot?: (context: Config["context"] & { args: Args }) => unknown;
+  snapshot?: (context: Context<Config, Auth> & { args: Args }) => unknown;
 }
+type Context<Config extends MutationClientConfig, Auth extends boolean | string> =
+  & Config["context"]
+  & (Auth extends false ? Partial<Config["userContext"]> : Config["userContext"]);
 export type OptimisticContext<
   Args extends unknown[],
   Result,
   Config extends MutationClientConfig,
-> = Config["context"] & {
+  Auth extends boolean | string,
+> = Context<Config, Auth> & {
   args: Args;
   helpers: Config["optimisticHelpers"];
   /** Add an event listener to roll back the update */
 @@ -94,9 +119,11 @@ export type OptimisticContext<
   onRefetch: (cb: () => Promise<void>) => void;
 };
-interface PendingDebouncedState<Args extends unknown[], Result> {
+interface PendingDebouncedState<Args extends unknown[], Result, Context> {
   /** Arguments from the most recent call */
   args: Args;
+  /** Context captured when the most recent call was allowed */
+  context: Context;
   /** Number of rollbacks the most recent call added */
   rollbackCount: number;
   /** All pending promises from all superseded calls */
 @@ -130,23 +157,24 @@ function unwrapMutationError(caught: unknown) {
   return { error: caught, description: null };
 }
-interface Channel<Args extends unknown[], Result, OptimisticHelpers> {
+interface Channel<Args extends unknown[], Result, OptimisticHelpers, Context> {
   listeners: Set<(update: MutationEvent<Result>) => void>;
   status: "idle" | "waiting" | "mutating" | "refetching" | "skipped";
   rollbacks: Array<() => void>;
   refetches: Array<() => Promise<void>>;
-  queue: Array<Item<Args, Result>>;
+  queue: Array<Item<Args, Result, Context>>;
   // Shared optimistic helpers instance for the channel
   helpers: OptimisticHelpers | null;
   // Debounce state (only used if debounce option is set)
   debounceTimer: ReturnType<typeof setTimeout> | null;
-  pendingDebounced: PendingDebouncedState<Args, Result> | null;
+  pendingDebounced: PendingDebouncedState<Args, Result, Context> | null;
   // Track when last debounced mutation executed (for debounceImmediate)
   lastDebouncedExecutionTime: number | null;
 }
-interface Item<Args extends unknown[], Result> {
+interface Item<Args extends unknown[], Result, Context> {
   args: Args;
+  context: Context;
   rollbacks: number;
   onSuccess: Array<(result: Result) => void>;
   resolve: (result: Result) => void;
 @@ -154,29 +182,70 @@ interface Item<Args extends unknown[], Result> {
 }
 export class BlockingMutation<
-  Args extends unknown[],
+  Args extends Json[],
   Result,
+  Auth extends boolean | string,
   Config extends MutationClientConfig,
 > implements Mutation<Args, Result> {
-  #options: MutationOptions<Args, Result, Config>;
+  #options: MutationOptions<Args, Result, Auth, Config>;
   #client: MutationClientFromConfig<Config>;
   #channels: Map<
     string,
-    Channel<Args, Result, Config["optimisticHelpers"]>
+    Channel<Args, Result, Config["optimisticHelpers"], Context<Config, Auth>>
   > = new Map();
   client: MutationClientFromConfig<Config>;
   constructor(
-    client: MutationClient<Config["context"], Config["optimisticHelpers"]>,
+    client: MutationClientFromConfig<Config>,
-    options: MutationOptions<Args, Result, Config>,
+    options: MutationOptions<Args, Result, Auth, Config>,
   ) {
     this.#options = options;
     this.#client = client;
     this.client = client;
   }
+  get id(): string {
+    return this.#options.id;
+  }
+  #context(): Context<Config, Auth> {
+    return {
+      ...this.#client.context,
+      ...(this.#client.userContext?.get() ?? {}),
+    } as Context<Config, Auth>;
+  }
+  #reportUnauthenticated(options: RunOptions<Result>, args: Args) {
+    const handler = options.onUnauthenticated ?? this.#client.handleUnauthenticated;
+    handler?.call(
+      this.#client,
+      { id: this.#options.id, description: this.describe(...args), args },
+      this as unknown as Mutation<Json[], unknown>,
+    );
+  }
+  isUnauthenticated(): boolean {
+    return this.#options.auth === true && this.#client.userContext?.get() == null;
+  }
+  isAllowed(): boolean {
+    const { auth } = this.#options;
+    if (auth !== undefined && auth !== false && this.#client.userContext?.get() == null) return false;
+    if (typeof auth === "string" && !(this.#client.authScopes?.[auth]?.get() ?? false)) return false;
+    return this.#options.isAllowed?.get() ?? true;
+  }
+  subscribeAllowed(cb: () => void): () => void {
+    const { auth } = this.#options;
+    const unsubscribes = [
+      this.#options.isAllowed?.sub(cb),
+      typeof auth === "string" ? this.#client.authScopes?.[auth]?.sub(cb) : undefined,
+    ];
+    return () => unsubscribes.forEach((unsubscribe) => unsubscribe?.());
+  }
   key(args: Args) {
-    const k = this.#options.key?.({ ...this.#client.context, args })
+    const k = this.#options.key?.({ ...this.#context(), args })
       ?? "shared";
     return JSON.stringify(k);
   }
 @@ -211,7 +280,7 @@ export class BlockingMutation<
   }
   #notify(
-    channel: Channel<Args, Result, Config["optimisticHelpers"]>,
+    channel: Channel<Args, Result, Config["optimisticHelpers"], Context<Config, Auth>>,
     status: MutationEvent<Result>["status"],
     result: Result | null = null,
     error: unknown = null,
 @@ -222,7 +291,7 @@ export class BlockingMutation<
   #setIdle(
     key: string,
-    channel: Channel<Args, Result, Config["optimisticHelpers"]>,
+    channel: Channel<Args, Result, Config["optimisticHelpers"], Context<Config, Auth>>,
   ) {
     // Check if there are pending debounced calls waiting
     if (channel.pendingDebounced !== null) {
 @@ -250,7 +319,7 @@ export class BlockingMutation<
   describe(...args: Args): string {
     const { describe } = this.#options;
     return typeof describe === "function"
-      ? describe({ ...this.#client.context, args })
+      ? describe({ ...this.#context(), args })
       : describe;
   }
 @@ -258,7 +327,7 @@ export class BlockingMutation<
     const { describeResult } = this.#options;
     if (describeResult === null) return undefined;
     return typeof describeResult === "function"
-      ? describeResult({ ...this.#client.context, args, result })
+      ? describeResult({ ...this.#context(), args, result })
       : describeResult;
   }
 @@ -284,8 +353,17 @@ export class BlockingMutation<
     }
     const args = array.slice() as Args;
-    const { onSuccessUi: onSuccess, onSuccessData, onError, onSettled, onRestore } = args
+    const options = args.pop() as RunOptions<Result>;
-      .pop() as RunOptions<Result>;
+    const { onSuccessUi: onSuccess, onSuccessData, onError, onSettled, onRestore } = options;
+    if (!this.isAllowed()) {
+      if (this.isUnauthenticated()) {
+        this.#reportUnauthenticated(options, args);
+        return Promise.reject(new Error("Mutation requires authentication."));
+      }
+      return Promise.reject(new Error("Mutation is not allowed."));
+    }
     const promise = this.#runWithOptions(args, onRestore, true);
     return promise.then((result) => {
       // Call user handlers
 @@ -312,8 +390,22 @@ export class BlockingMutation<
     }
     const args = array.slice() as Args;
-    const { onSuccessUi, onSuccessData, onError, onSettled, onRestore } = args
+    const options = args.pop() as RunOptions<Result>;
-      .pop() as RunOptions<Result>;
+    const { onSuccessUi, onSuccessData, onError, onSettled, onRestore } = options;
+    if (!this.isAllowed()) {
+      if (this.isUnauthenticated()) {
+        this.#reportUnauthenticated(options, args);
+        return;
+      }
+      const error = new Error("Mutation is not allowed.");
+      onError?.(error);
+      onSettled?.({ status: "error", error });
+      if (!onError) {
+        this.#client.reportError(formatFriendlyError(this.describe(...args), error), error);
+      }
+      return;
+    }
     const suppressAll = this.#options.debounceMs !== undefined && !onSuccessUi && !onError;
     const suppressGlobalSuccess = onSuccessUi !== undefined || suppressAll;
     const suppressGlobalError = onError !== undefined || suppressAll;
 @@ -357,6 +449,7 @@ export class BlockingMutation<
     }
     const key = this.key(args);
     const channel = this.#getOrPutChannel(key);
+    const context = this.#context();
     // Check if debouncing is enabled
     if (this.#options.debounceMs !== undefined) {
 @@ -370,6 +463,7 @@ export class BlockingMutation<
         args,
         key,
         channel,
+        context,
         userOnRestore,
         !!shouldExecuteImmediate,
         suppressGlobalHandlers,
 @@ -378,7 +472,7 @@ export class BlockingMutation<
     // Take snapshot before optimistic update (if snapshot function defined)
     const beforeSnapshot = this.#options.snapshot
-      ? this.#options.snapshot.call(this.#client.context, { args })
+      ? this.#options.snapshot.call(context, { ...context, args })
       : undefined;
     // Create shared optimistic helpers instance for the channel if it doesn't exist
 @@ -416,7 +510,7 @@ export class BlockingMutation<
     try {
       this.#options.optimistic({
-        ...this.#client.context,
+        ...context,
         args,
         helpers: channel.helpers,
         onRestore,
 @@ -452,8 +546,8 @@ export class BlockingMutation<
     // Take snapshot after optimistic update and check for no-op
     if (beforeSnapshot !== undefined) {
       const afterSnapshot = this.#options.snapshot!.call(
-        this.#client.context,
+        context,
-        { args },
+        { ...context, args },
       );
       const isNoOp = this.#client.deepEquals(beforeSnapshot, afterSnapshot);
 @@ -475,6 +569,7 @@ export class BlockingMutation<
     const { promise, resolve, reject } = Promise.withResolvers<Result>();
     channel.queue.push({
       args,
+      context,
       rollbacks,
       onSuccess,
       resolve,
 @@ -490,7 +585,7 @@ export class BlockingMutation<
   #executeNext(
     key: string,
-    channel: Channel<Args, Result, Config["optimisticHelpers"]>,
+    channel: Channel<Args, Result, Config["optimisticHelpers"], Context<Config, Auth>>,
   ) {
     const item = channel.queue.shift();
     if (!item) {
 @@ -498,11 +593,11 @@ export class BlockingMutation<
       return;
     }
-    const { args, onSuccess, resolve, reject } = item;
+    const { args, context, onSuccess, resolve, reject } = item;
     channel.status = "mutating";
     this.#notify(channel, "mutating");
-    this.#options.mutate.call(this.#client.context, ...args).then((result) => {
+    this.#options.mutate.call(context, ...args).then((result) => {
       // remove rollbacks and apply optimistic success handlers
       channel.rollbacks.splice(0, item.rollbacks);
       onSuccess.forEach((cb) => cb(result));
 @@ -575,7 +670,8 @@ export class BlockingMutation<
   #runDebouncedAndReturn(
     args: Args,
     key: string,
-    channel: Channel<Args, Result, Config["optimisticHelpers"]>,
+    channel: Channel<Args, Result, Config["optimisticHelpers"], Context<Config, Auth>>,
+    context: Context<Config, Auth>,
     userOnRestore: (() => void) | undefined,
     shouldExecuteImmediate: boolean,
     shouldCallGlobalHandler: boolean,
 @@ -584,7 +680,10 @@ export class BlockingMutation<
     const isFirstDebouncedCall = channel.pendingDebounced === null;
     let initialSnapshot: unknown;
     if (isFirstDebouncedCall && this.#options.snapshot) {
-      initialSnapshot = this.#options.snapshot.call(this.#client.context, { args });
+      initialSnapshot = this.#options.snapshot.call(
+        context,
+        { ...context, args },
+      );
     }
     // If there's a pending debounced call, roll it back
 @@ -627,7 +726,7 @@ export class BlockingMutation<
     try {
       this.#options.optimistic({
-        ...this.client.context,
+        ...context,
         args,
         helpers: channel.helpers,
         onRestore,
 @@ -664,8 +763,8 @@ export class BlockingMutation<
     // Check for no-op by comparing to initial snapshot
     if (this.#options.snapshot) {
       const currentSnapshot = this.#options.snapshot.call(
-        this.#client.context,
+        context,
-        { args },
+        { ...context, args },
       );
       const snapshotToCompare = isFirstDebouncedCall
         ? initialSnapshot!
 @@ -708,6 +807,7 @@ export class BlockingMutation<
       // First debounced call
       channel.pendingDebounced = {
         args,
+        context,
         rollbackCount: rollbacks,
         pending: [{ resolve, reject }],
         onSuccess,
 @@ -721,6 +821,7 @@ export class BlockingMutation<
     } else {
       // Subsequent debounced call - update state
       channel.pendingDebounced.args = args;
+      channel.pendingDebounced.context = context;
       channel.pendingDebounced.rollbackCount = rollbacks;
       channel.pendingDebounced.pending.push({ resolve, reject });
       channel.pendingDebounced.onSuccess = onSuccess;
 @@ -744,7 +845,7 @@ export class BlockingMutation<
   }
   #rollbackPendingDebounced(
-    channel: Channel<Args, Result, Config["optimisticHelpers"]>,
+    channel: Channel<Args, Result, Config["optimisticHelpers"], Context<Config, Auth>>,
   ) {
     if (!channel.pendingDebounced) return;
 @@ -763,7 +864,7 @@ export class BlockingMutation<
   #enqueueDebouncedCall(
     key: string,
-    channel: Channel<Args, Result, Config["optimisticHelpers"]>,
+    channel: Channel<Args, Result, Config["optimisticHelpers"], Context<Config, Auth>>,
   ) {
     // Clear timer
     channel.debounceTimer = null;
 @@ -774,7 +875,7 @@ export class BlockingMutation<
       return;
     }
-    const { args, rollbackCount, pending, onSuccess, shouldCallGlobalHandler } = channel.pendingDebounced;
+    const { args, context, rollbackCount, pending, onSuccess, shouldCallGlobalHandler } = channel.pendingDebounced;
     channel.pendingDebounced = null;
     // Track execution time for debounceImmediate
 @@ -822,6 +923,7 @@ export class BlockingMutation<
     // Add to queue (same structure as regular blocking mutation)
     channel.queue.push({
       args,
+      context,
       rollbacks: rollbackCount,
       onSuccess,
       resolve: wrapperResolve,

src/react.ts+45-7

 @@ -1,6 +1,5 @@
 import { message as errMessage } from "@clo/lib/error.ts";
 import type { Timer } from "@clo/lib/ts.ts";
-import { isDisabled } from "@testing-library/user-event/dist/cjs/utils/index.js";
 import {
   type FC,
   type MouseEvent,
 @@ -30,6 +29,7 @@ export function useMutate<
   if (mutation !== observer.mutation) {
     observer.mutation = mutation;
     observer.reset();
+    observer.subscribeAllowed();
   }
   return observer.binding;
 }
 @@ -56,6 +56,8 @@ export interface UseMutateResultBase<Args extends unknown[], Result> {
   args: Args | undefined;
   /** `true` when controls should be disabled */
   isDisabled: boolean;
+  /** `true` when a mutation exists and its authentication requirement is satisfied. */
+  isAllowed: boolean;
 }
 export interface UseMutateSuccess<Result> {
 @@ -121,7 +123,6 @@ type AnyMutationStateWithoutRun<Args extends unknown[], Result> =
     isSuccess: boolean;
     isError: boolean;
     args: Args | undefined;
-    isDisabled: boolean;
   };
 export type AnyMutationState<Args extends unknown[], Result> =
 @@ -140,7 +141,6 @@ function initialState() {
     isError: false,
     isOptimisticData: false,
     args: undefined,
-    isDisabled: true,
   } as const;
 }
 @@ -148,6 +148,7 @@ class Observer<Args extends unknown[], Result> {
   setRerender: (fn: number) => void;
   mutation: Mutation<Args, Result> | null = null;
   unsubscribe: (() => void) | null = null;
+  unsubscribeAllowed: (() => void) | null = null;
   currentKey: string | null = null;
   pendingTimer: Timer | null = null;
   debounced: boolean = false;
 @@ -174,12 +175,30 @@ class Observer<Args extends unknown[], Result> {
   reset() {
     this.unsubscribe?.();
+    this.unsubscribeAllowed?.();
     this.unsubscribe = null;
+    this.unsubscribeAllowed = null;
     this.currentKey = null;
     this.state = initialState();
     this.debounced = false;
   }
+  subscribeAllowed() {
+    const mutation = this.mutation;
+    if (!mutation) return;
+    const rerenderIfWatched = () => {
+      if (this.watched.has("isAllowed") || this.watched.has("isDisabled")) {
+        this.setRerender(Math.random());
+      }
+    };
+    const unsubscribeMutation = mutation.subscribeAllowed(rerenderIfWatched);
+    const unsubscribeClient = mutation.client.userContext?.sub(rerenderIfWatched) ?? (() => {});
+    this.unsubscribeAllowed = () => {
+      unsubscribeMutation();
+      unsubscribeClient();
+    };
+  }
   resetPending() {
     this.setState({ isPending: false });
     if (this.pendingTimer) clearTimeout(this.pendingTimer);
 @@ -373,10 +392,18 @@ class Observer<Args extends unknown[], Result> {
       self.watched.add("isMutating");
       return self.state.isMutating;
     },
-    // TODO: when auth drops this will be dependant on the auth status and isMutating
+    get isAllowed() {
+      self.watched.add("isAllowed");
+      return self.mutation?.isAllowed() ?? false;
+    },
     get isDisabled() {
+      self.watched.add("isDisabled");
       self.watched.add("isMutating");
-      return !self.mutation || (self.state.isMutating && !self.debounced);
+      const mutation = self.mutation;
+      if (!mutation || (self.state.isMutating && !self.debounced)) return true;
+      if (mutation.isAllowed()) return false;
+      // Unauthenticated clicks stay enabled when they can route to a sign-in flow.
+      return !(mutation.isUnauthenticated() && mutation.client.handleUnauthenticated);
     },
     get isPending() {
       self.watched.add("isPending");
 @@ -431,6 +458,8 @@ export interface MutationButtonProps<Args extends unknown[], Result> {
   onSuccessUi?: (result: Result) => void;
   /** Does not prevent the global handler */
   onSuccessData?: (result: Result) => void;
+  /** Called instead of running an authenticated mutation when no user is available. */
+  onUnauthenticated?: RunOptions<Result>["onUnauthenticated"];
   /** Global event handlers will still be called! */
   onSettled?: (
 @@ -442,6 +471,9 @@ export interface MutationButtonProps<Args extends unknown[], Result> {
       error: unknown;
     },
   ) => void;
+  /** Setting this to true will opt out of the behavior that non-allowed buttons are hidden. */
+  showNotAllowed?: boolean;
 }
 /**
 @@ -493,7 +525,9 @@ function GenericMutationButton<
     onError,
     onSuccessUi,
     onSuccessData,
+    onUnauthenticated,
     onSettled,
+    showNotAllowed,
     ...forwarded
   } = props;
   forwarded satisfies Omit<Props, keyof MutationButtonProps<Args, Result>>;
 @@ -508,9 +542,13 @@ function GenericMutationButton<
     if (!computedArgs || e.defaultPrevented) return;
     state.runWithOptions(
       ...computedArgs,
-      { onSuccessUi, onSuccessData, onError, onSettled },
+      { onSuccessUi, onSuccessData, onError, onUnauthenticated, onSettled },
     );
-  }, [args, onClick, onError, onSettled, onSuccessUi, onSuccessData, state]);
+  }, [args, onClick, onError, onSettled, onSuccessUi, onSuccessData, onUnauthenticated, state]);
+  // Buttons the user can never click are hidden; a signed-out `auth: true`
+  // button stays visible when it can route the click to the sign-in flow.
+  if (!showNotAllowed && !state.isAllowed && state.isDisabled) return null;
   // NOTE: the JSR has trouble with JSX syntax for some reason.
   return jsx(

src/tanstack-query.ts+28-1

...	@@ -1,5 +1,5 @@	...	@@ -1,5 +1,5 @@
1	import { QueryClient, type QueryFunction, type QueryKey, type Updater } from "@tanstack/react-query";	1	import { QueryClient, type QueryFunction, type QueryKey, type Updater } from "@tanstack/react-query";
2	import type { OptimisticEvents } from "./client.ts";	2	import type { OptimisticEvents, Reactive } from "./client.ts";
3	import { type AllObjectPaths, type GetObjectPath, getPath, setPath } from "./object-path.ts";	3	import { type AllObjectPaths, type GetObjectPath, getPath, setPath } from "./object-path.ts";
4		4
5	export type QueryKeyAndFn<T = unknown, Key extends QueryKey = QueryKey> = {	5	export type QueryKeyAndFn<T = unknown, Key extends QueryKey = QueryKey> = {
...	@@ -19,6 +19,33 @@ export function boundQueryClientGet(	...	@@ -19,6 +19,33 @@ export function boundQueryClientGet(
19	};	19	};
20	}	20	}
21		21
		22	export function reactiveFromQueryCache<T>(
		23	client: QueryClient,
		24	{ queryKey }: QueryKeyAndFn<T>,
		25	): Reactive<T \| undefined>;
		26	export function reactiveFromQueryCache<T, R>(
		27	client: QueryClient,
		28	{ queryKey }: QueryKeyAndFn<T>,
		29	deriver: (value: T \| undefined) => R,
		30	): Reactive<R>;
		31	export function reactiveFromQueryCache<T>(
		32	client: QueryClient,
		33	{ queryKey }: QueryKeyAndFn<T>,
		34	deriver: (value: T \| undefined) => unknown = x => x,
		35	): Reactive<unknown> {
		36	return {
		37	get: () => deriver(client.getQueryData<T>(queryKey)),
		38	sub: (onChange) => {
		39	const queryKeyJson = JSON.stringify(queryKey);
		40	return client.getQueryCache().subscribe((event) => {
		41	if (JSON.stringify(event.query.queryKey) === queryKeyJson) {
		42	onChange();
		43	}
		44	});
		45	},
		46	};
		47	}
		48
22	class TanstackQueryOptimisticHelpers {	49	class TanstackQueryOptimisticHelpers {
23	#client: QueryClient;	50	#client: QueryClient;
24	#onRefetch: OptimisticEvents["onRefetch"];	51	#onRefetch: OptimisticEvents["onRefetch"];

src/types.ts+39-3

...	@@ -1,6 +1,31 @@	...	@@ -1,6 +1,31 @@
1	import type { MutationClient } from "./client.ts";	1	import type { MutationClient } from "./client.ts";
2		2
		3	/**
		4	* Mutation arguments must be JSON serializable so a call can be stored and
		5	* replayed later, such as re-running a mutation after the user signs in.
		6	*/
		7	export type Json =
		8	\| string
		9	\| number
		10	\| boolean
		11	\| null
		12	\| Json[]
		13	\| { [key: string]: Json };
		14
		15	/**
		16	* A serializable record of a mutation call. Produced when an authenticated
		17	* mutation is attempted without a user; pass it to `MutationClient.run`
		18	* after sign-in to re-run the call.
		19	*/
		20	export interface MutationAction {
		21	id: string;
		22	description: string;
		23	args: Json[];
		24	}
		25
3	export interface Mutation<Args extends unknown[], Result> {	26	export interface Mutation<Args extends unknown[], Result> {
		27	/** Unique identifier passed to `define`. */
		28	readonly id: string;
4	/** Calling the mutation. Errors are turned into UI toasts. */	29	/** Calling the mutation. Errors are turned into UI toasts. */
5	run(...args: Args): void;	30	run(...args: Args): void;
6	/** Calls the mutation with custom handlers that can suppress global handlers. */	31	/** Calls the mutation with custom handlers that can suppress global handlers. */
...	@@ -25,7 +50,14 @@ export interface Mutation<Args extends unknown[], Result> {	...	@@ -25,7 +50,14 @@ export interface Mutation<Args extends unknown[], Result> {
25	): () => void;	50	): () => void;
26	describe(...args: Args): string;	51	describe(...args: Args): string;
27	describeResult: ((args: Args, result: Result) => string \| undefined) \| null;	52	describeResult: ((args: Args, result: Result) => string \| undefined) \| null;
28	client: MutationClient<object, object>;	53	/**
		54	* `true` when an `auth: true` mutation has no user available. Scoped
		55	* mutations are excluded; they disable instead of routing to the sign-in flow.
		56	*/
		57	isUnauthenticated(): boolean;
		58	isAllowed(): boolean;
		59	subscribeAllowed(cb: () => void): () => void;
		60	client: MutationClient<object, object, object>;
29	}	61	}
30		62
31	export interface RunOptions<Result> {	63	export interface RunOptions<Result> {
...	@@ -47,8 +79,12 @@ export interface RunOptions<Result> {	...	@@ -47,8 +79,12 @@ export interface RunOptions<Result> {
47	) => void;	79	) => void;
48	/** Called when optimistic state is being restored/rolled back */	80	/** Called when optimistic state is being restored/rolled back */
49	onRestore?: () => void;	81	onRestore?: () => void;
50	/** @internal Suppresses global handlers for debounced mutations */	82	/**
51	__suppressGlobalForDebounce?: boolean;	83	* Called instead of running an authenticated mutation when no user is
		84	* available. The action is JSON serializable and can be passed to
		85	* `MutationClient.run` after sign-in.
		86	*/
		87	onUnauthenticated?: (action: MutationAction, mutation: Mutation<Json[], unknown>) => void;
52	}	88	}
53		89
54	export interface MutationEvent<Result> {	90	export interface MutationEvent<Result> {

test/auth.test.tsx created+568

...	@@ -0,0 +1,568 @@
1	import {
2	createMutationButton,
3	type MutationAction,
4	MutationClient,
5	type Reactive,
6	useMutate,
7	} from "@clo/react-mutation";
8	import { assertEquals, assertThrows } from "@std/assert";
9	import { act, render, screen } from "@testing-library/react";
10	import { userEvent } from "@testing-library/user-event";
11	import type { FC, MouseEventHandler, ReactNode } from "react";
12	import { test, vi } from "vitest";
13	import { IterableStream } from "./share.ts";
14
15	interface User {
16	id: string;
17	}
18
19	function mutableReactive<T>(value: T): Reactive<T> & { set(value: T): void } {
20	const listeners = new Set<() => void>();
21	return {
22	get: () => value,
23	set(next) {
24	value = next;
25	listeners.forEach((listener) => listener());
26	},
27	sub(listener) {
28	listeners.add(listener);
29	return () => listeners.delete(listener);
30	},
31	};
32	}
33
34	function createAuthClient(currentUser: () => User \| null, withHandler = true, admin?: Reactive<boolean>) {
35	const unauthenticated: MutationAction[] = [];
36	const errors: string[] = [];
37	const client = new MutationClient<{ contextValue: number }, {}, { user: User; accountId: string }, "admin">({
38	context: { contextValue: 42 },
39	userContext: {
40	get: () => {
41	const user = currentUser();
42	return user ? { user, accountId: "a1" } : null;
43	},
44	sub: () => () => {},
45	},
46	authScopes: admin ? { admin } : undefined,
47	handleUnauthenticated: withHandler ? (action) => unauthenticated.push(action) : undefined,
48	getOptimisticHelpers: () => ({}),
49	reportError: (message) => errors.push(message),
50	});
51
52	return { client, unauthenticated, errors };
53	}
54
55	test("authenticated mutations receive user in every context", async () => {
56	const currentUser = { id: "u1" };
57	const { client } = createAuthClient(() => currentUser);
58	const seen: string[] = [];
59	let snapshotValue = 0;
60
61	const mutation = client.define({
62	id: "test-auth",
63	auth: true,
64	mutate: async function(value: number) {
65	seen.push(`mutate:${this.user?.id}:${this.accountId}:${this.contextValue}:${value}`);
66	return value + 1;
67	},
68	key: ({ user, accountId, contextValue, args: [value] }) => {
69	seen.push(`key:${user?.id}:${accountId}:${contextValue}:${value}`);
70	return String(value);
71	},
72	snapshot: ({ user, accountId, contextValue, args: [value] }) => {
73	seen.push(`snapshot:${user?.id}:${accountId}:${contextValue}:${value}`);
74	return snapshotValue;
75	},
76	optimistic: ({ user, accountId, contextValue, args: [value] }) => {
77	seen.push(`optimistic:${user?.id}:${accountId}:${contextValue}:${value}`);
78	snapshotValue += 1;
79	},
80	describe: ({ user, accountId, contextValue, args: [value] }) => {
81	seen.push(`describe:${user?.id}:${accountId}:${contextValue}:${value}`);
82	return "Test auth";
83	},
84	describeResult: ({ user, accountId, contextValue, args: [value], result }) => {
85	seen.push(`result:${user?.id}:${accountId}:${contextValue}:${value}:${result}`);
86	return "Tested auth";
87	},
88	refetchOnSuccess: false,
89	});
90
91	assertEquals(mutation.key([1]), "\"1\"");
92	assertEquals(mutation.describe(1), "Test auth");
93	assertEquals(mutation.describeResult?.([1], 2), "Tested auth");
94	assertEquals(await mutation.runAsHeadlessPromise(1, {}), 2);
95
96	assertEquals(seen, [
97	"key:u1:a1:42:1",
98	"describe:u1:a1:42:1",
99	"result:u1:a1:42:1:2",
100	"key:u1:a1:42:1",
101	"snapshot:u1:a1:42:1",
102	"optimistic:u1:a1:42:1",
103	"snapshot:u1:a1:42:1",
104	"mutate:u1:a1:42:1",
105	]);
106	});
107
108	test("authenticated mutations do not run while unauthenticated", async () => {
109	const { client, unauthenticated } = createAuthClient(() => null);
110	const localUnauthenticated: string[] = [];
111	const mutate = vi.fn(async () => "ok");
112	const optimistic = vi.fn();
113
114	const mutation = client.define({
115	id: "test-auth",
116	auth: true,
117	mutate,
118	optimistic,
119	describe: ({ user, contextValue }) => `Test auth as ${user?.id ?? "guest"}:${contextValue}`,
120	describeResult: "Tested auth",
121	});
122
123	mutation.runWithOptions({
124	onUnauthenticated: () => localUnauthenticated.push("local"),
125	});
126	mutation.run();
127	await Promise.resolve();
128
129	assertEquals(localUnauthenticated, ["local"]);
130	assertEquals(unauthenticated, [{ id: "test-auth", description: "Test auth as guest:42", args: [] }]);
131	assertEquals(optimistic.mock.calls, []);
132	assertEquals(mutate.mock.calls, []);
133	});
134
135	test("duplicate mutation ids throw in production and replace in development", async () => {
136	const { client } = createAuthClient(() => null);
137	const options = {
138	id: "test-duplicate",
139	mutate: async () => "ok",
140	optimistic: () => {},
141	describe: "Test duplicate",
142	describeResult: null,
143	refetchOnSuccess: false,
144	};
145	client.define(options);
146
147	vi.stubEnv("NODE_ENV", "production");
148	try {
149	assertThrows(() => client.define(options), Error, "Mutation id \"test-duplicate\" is already registered.");
150	} finally {
151	vi.unstubAllEnvs();
152	}
153
154	const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
155	try {
156	const replacement = vi.fn(async () => "ok");
157	client.define({ ...options, mutate: replacement });
158	assertEquals(errorSpy.mock.calls.length, 1);
159
160	client.run({ id: "test-duplicate", args: [] });
161	assertEquals(replacement.mock.calls, [[]]);
162	} finally {
163	errorSpy.mockRestore();
164	}
165	});
166
167	test("unauthenticated actions survive JSON storage and restore after sign-in", async () => {
168	let currentUser: User \| null = null;
169	const { client, unauthenticated } = createAuthClient(() => currentUser);
170	const mutate = vi.fn(async (value: number, note: string) => `${value}:${note}`);
171
172	client.define({
173	id: "test-restore",
174	auth: true,
175	mutate,
176	optimistic: () => {},
177	describe: "Test restore",
178	describeResult: null,
179	refetchOnSuccess: false,
180	});
181
182	client.run({ id: "test-restore", args: [1, "hello"] });
183	assertEquals(mutate.mock.calls, []);
184	assertEquals(unauthenticated, [{ id: "test-restore", description: "Test restore", args: [1, "hello"] }]);
185
186	const stored: MutationAction = JSON.parse(JSON.stringify(unauthenticated[0]));
187	currentUser = { id: "u1" };
188	client.run(stored);
189	await Promise.resolve();
190
191	assertEquals(mutate.mock.calls, [[1, "hello"]]);
192	assertThrows(() => client.run({ id: "test-unknown", args: [] }), Error, "not registered");
193	});
194
195	test("useMutate derives isAllowed and isDisabled from authentication", async () => {
196	const user = userEvent.setup({ delay: null });
197	let currentUser: User \| null = null;
198	const { client } = createAuthClient(() => currentUser, false);
199	const s = new IterableStream<string>();
200
201	const mutation = client.define({
202	id: "test-auth",
203	auth: true,
204	mutate: async () => (await s.next()).value,
205	optimistic: () => {},
206	describe: "Test auth",
207	describeResult: "Tested auth",
208	});
209
210	let renders: Array<{ isAllowed: boolean; isDisabled: boolean; isMutating: boolean }> = [];
211	function TestComponent() {
212	const { run, isAllowed, isDisabled, isMutating } = useMutate(mutation);
213	renders.push({ isAllowed, isDisabled, isMutating });
214
215	return <button data-testid="run" onClick={() => run()}>run</button>;
216	}
217
218	const view = render(<TestComponent />);
219	assertEquals(renders, [{ isAllowed: false, isDisabled: true, isMutating: false }]);
220	renders = [];
221
222	currentUser = { id: "u1" };
223	view.rerender(<TestComponent />);
224	assertEquals(renders, [{ isAllowed: true, isDisabled: false, isMutating: false }]);
225	renders = [];
226
227	await act(() => user.click(screen.getByTestId("run")));
228	assertEquals(renders, [{ isAllowed: true, isDisabled: true, isMutating: true }]);
229	renders = [];
230
231	await act(async () => {
232	s.push("ok");
233	});
234	assertEquals(renders, [{ isAllowed: true, isDisabled: false, isMutating: false }]);
235	});
236
237	test("useMutate reacts to userContext changes", () => {
238	const userContext = mutableReactive<{ user: User; accountId: string } \| null>(null);
239	const client = new MutationClient<{ contextValue: number }, {}, { user: User; accountId: string }>({
240	context: { contextValue: 42 },
241	userContext,
242	getOptimisticHelpers: () => ({}),
243	reportError: () => {},
244	});
245	const mutation = client.define({
246	id: "test-auth",
247	auth: true,
248	mutate: async () => "ok",
249	optimistic: () => {},
250	describe: "Test auth",
251	describeResult: "Tested auth",
252	});
253
254	let renders: Array<{ isAllowed: boolean; isDisabled: boolean }> = [];
255	function TestComponent() {
256	const { isAllowed, isDisabled } = useMutate(mutation);
257	renders.push({ isAllowed, isDisabled });
258	return null;
259	}
260
261	render(<TestComponent />);
262	assertEquals(renders, [{ isAllowed: false, isDisabled: true }]);
263	renders = [];
264
265	act(() => userContext.set({ user: { id: "u1" }, accountId: "a1" }));
266	assertEquals(renders, [{ isAllowed: true, isDisabled: false }]);
267	});
268
269	test("useMutate reacts to mutation isAllowed changes", () => {
270	const isAllowed = mutableReactive(false);
271	const { client } = createAuthClient(() => null);
272	const mutation = client.define({
273	id: "test-allowed",
274	isAllowed,
275	mutate: async () => "ok",
276	optimistic: () => {},
277	describe: "Test allowed",
278	describeResult: "Tested allowed",
279	});
280
281	let renders: Array<{ isAllowed: boolean; isDisabled: boolean }> = [];
282	function TestComponent() {
283	const { isAllowed, isDisabled } = useMutate(mutation);
284	renders.push({ isAllowed, isDisabled });
285	return null;
286	}
287
288	render(<TestComponent />);
289	assertEquals(renders, [{ isAllowed: false, isDisabled: true }]);
290	renders = [];
291
292	act(() => isAllowed.set(true));
293	assertEquals(renders, [{ isAllowed: true, isDisabled: false }]);
294	});
295
296	test("unauthenticated with a handler stays enabled and routes clicks to it", async () => {
297	const user = userEvent.setup({ delay: null });
298	const { client, unauthenticated } = createAuthClient(() => null);
299	const mutate = vi.fn(async () => "ok");
300
301	const mutation = client.define({
302	id: "test-auth",
303	auth: true,
304	mutate,
305	optimistic: () => {},
306	describe: "Test auth",
307	describeResult: "Tested auth",
308	});
309
310	let lastRender = { isAllowed: true, isDisabled: true };
311	function TestComponent() {
312	const { run, isAllowed, isDisabled } = useMutate(mutation);
313	lastRender = { isAllowed, isDisabled };
314	return <button data-testid="run" onClick={() => run()}>run</button>;
315	}
316
317	render(<TestComponent />);
318	assertEquals(lastRender, { isAllowed: false, isDisabled: false });
319
320	await act(() => user.click(screen.getByTestId("run")));
321	assertEquals(unauthenticated, [{ id: "test-auth", description: "Test auth", args: [] }]);
322	assertEquals(mutate.mock.calls, []);
323	});
324
325	test("running while isAllowed is false reports an error instead of the sign-in flow", () => {
326	const isAllowed = mutableReactive(false);
327	const { client, unauthenticated, errors } = createAuthClient(() => null);
328	const mutate = vi.fn(async () => "ok");
329
330	const mutation = client.define({
331	id: "test-not-allowed",
332	isAllowed,
333	mutate,
334	optimistic: () => {},
335	describe: "Test allowed",
336	describeResult: null,
337	});
338
339	mutation.run();
340
341	assertEquals(unauthenticated, []);
342	assertEquals(mutate.mock.calls, []);
343	assertEquals(errors, ["Could not test allowed: Mutation is not allowed."]);
344	});
345
346	test("MutationButton hides authenticated mutations without a sign-in flow", async () => {
347	const user = userEvent.setup({ delay: null });
348	const { client } = createAuthClient(() => null, false);
349	const mutate = vi.fn(async () => "ok");
350
351	const mutation = client.define({
352	id: "test-auth",
353	auth: true,
354	mutate,
355	optimistic: () => {},
356	describe: "Test auth",
357	describeResult: "Tested auth",
358	});
359
360	const MutationButtonBase: FC<{
361	children?: ReactNode;
362	disabled?: boolean;
363	isPending: boolean;
364	onClick: MouseEventHandler<HTMLElement> \| undefined;
365	}> = ({ children, disabled, isPending, onClick }) => (
366	<button data-testid="button" disabled={disabled \|\| isPending} onClick={onClick}>
367	{children}
368	</button>
369	);
370	const MutationButton = createMutationButton(MutationButtonBase);
371
372	const view = render(<MutationButton mutation={mutation} args={[]}>run</MutationButton>);
373	assertEquals(screen.queryByTestId("button"), null);
374
375	view.rerender(<MutationButton mutation={mutation} args={[]} showNotAllowed>run</MutationButton>);
376	assertEquals((screen.getByTestId("button") as HTMLButtonElement).disabled, true);
377	await act(() => user.click(screen.getByTestId("button")));
378	assertEquals(mutate.mock.calls, []);
379	});
380
381	test("auth scopes gate mutations without routing to sign-in", () => {
382	let currentUser: User \| null = { id: "u1" };
383	const admin = mutableReactive(false);
384	const { client, unauthenticated, errors } = createAuthClient(() => currentUser, true, admin);
385	const mutate = vi.fn(async () => "ok");
386
387	const mutation = client.define({
388	id: "test-admin",
389	auth: "admin",
390	mutate,
391	optimistic: () => {},
392	describe: "Test admin",
393	describeResult: null,
394	refetchOnSuccess: false,
395	});
396
397	assertEquals(mutation.isAllowed(), false);
398	assertEquals(mutation.isUnauthenticated(), false);
399
400	mutation.run();
401	assertEquals(unauthenticated, []);
402	assertEquals(mutate.mock.calls, []);
403	assertEquals(errors, ["Could not test admin: Mutation is not allowed."]);
404
405	admin.set(true);
406	assertEquals(mutation.isAllowed(), true);
407	mutation.run();
408	assertEquals(mutate.mock.calls, [[]]);
409
410	currentUser = null;
411	assertEquals(mutation.isAllowed(), false);
412	assertEquals(mutation.isUnauthenticated(), false);
413	});
414
415	test("defining an unknown auth scope throws", () => {
416	const { client } = createAuthClient(() => null);
417
418	assertThrows(
419	() =>
420	client.define({
421	id: "test-unknown-scope",
422	auth: "admin",
423	mutate: async () => "ok",
424	optimistic: () => {},
425	describe: "Test unknown scope",
426	describeResult: null,
427	}),
428	Error,
429	"Unknown auth scope \"admin\".",
430	);
431	});
432
433	test("useMutate reacts to auth scope changes", () => {
434	const admin = mutableReactive(false);
435	const { client } = createAuthClient(() => ({ id: "u1" }), true, admin);
436	const mutation = client.define({
437	id: "test-admin",
438	auth: "admin",
439	mutate: async () => "ok",
440	optimistic: () => {},
441	describe: "Test admin",
442	describeResult: null,
443	});
444
445	let renders: Array<{ isAllowed: boolean; isDisabled: boolean }> = [];
446	function TestComponent() {
447	const { isAllowed, isDisabled } = useMutate(mutation);
448	renders.push({ isAllowed, isDisabled });
449	return null;
450	}
451
452	render(<TestComponent />);
453	assertEquals(renders, [{ isAllowed: false, isDisabled: true }]);
454	renders = [];
455
456	act(() => admin.set(true));
457	assertEquals(renders, [{ isAllowed: true, isDisabled: false }]);
458	});
459
460	test("MutationButton hides non-allowed mutations unless showNotAllowed", () => {
461	const admin = mutableReactive(false);
462	const { client } = createAuthClient(() => ({ id: "u1" }), true, admin);
463	const mutation = client.define({
464	id: "test-admin",
465	auth: "admin",
466	mutate: async () => "ok",
467	optimistic: () => {},
468	describe: "Test admin",
469	describeResult: null,
470	});
471
472	const MutationButtonBase: FC<{
473	children?: ReactNode;
474	disabled?: boolean;
475	isPending: boolean;
476	onClick: MouseEventHandler<HTMLElement> \| undefined;
477	}> = ({ children, disabled, isPending, onClick }) => (
478	<button data-testid="button" disabled={disabled \|\| isPending} onClick={onClick}>
479	{children}
480	</button>
481	);
482	const MutationButton = createMutationButton(MutationButtonBase);
483
484	const view = render(<MutationButton mutation={mutation} args={[]}>run</MutationButton>);
485	assertEquals(screen.queryByTestId("button"), null);
486
487	view.rerender(<MutationButton mutation={mutation} args={[]} showNotAllowed>run</MutationButton>);
488	assertEquals((screen.getByTestId("button") as HTMLButtonElement).disabled, true);
489
490	act(() => admin.set(true));
491	assertEquals((screen.getByTestId("button") as HTMLButtonElement).disabled, false);
492	});
493
494	test("MutationButton stays visible for unauthenticated mutations with a sign-in flow", () => {
495	const { client } = createAuthClient(() => null);
496	const mutation = client.define({
497	id: "test-auth",
498	auth: true,
499	mutate: async () => "ok",
500	optimistic: () => {},
501	describe: "Test auth",
502	describeResult: "Tested auth",
503	});
504
505	const MutationButtonBase: FC<{
506	children?: ReactNode;
507	disabled?: boolean;
508	isPending: boolean;
509	onClick: MouseEventHandler<HTMLElement> \| undefined;
510	}> = ({ children, disabled, isPending, onClick }) => (
511	<button data-testid="button" disabled={disabled \|\| isPending} onClick={onClick}>
512	{children}
513	</button>
514	);
515	const MutationButton = createMutationButton(MutationButtonBase);
516
517	render(<MutationButton mutation={mutation} args={[]}>run</MutationButton>);
518	assertEquals((screen.getByTestId("button") as HTMLButtonElement).disabled, false);
519	});
520
521	test("mutation isAllowed can disable unrelated to auth", () => {
522	let allow = false;
523	const isAllowed: Reactive<boolean> = {
524	get: () => allow,
525	sub: () => () => {},
526	};
527	const { client } = createAuthClient(() => null);
528
529	const mutation = client.define({
530	id: "test-allowed",
531	isAllowed,
532	mutate: async () => "ok",
533	optimistic: () => {},
534	describe: "Test allowed",
535	describeResult: "Tested allowed",
536	});
537
538	assertEquals(mutation.isAllowed(), false);
539	allow = true;
540	assertEquals(mutation.isAllowed(), true);
541	});
542
543	test("authenticated mutation isAllowed receives user context", () => {
544	let currentUser: User \| null = { id: "u1" };
545	let allow = true;
546	const isAllowed: Reactive<boolean> = {
547	get: () => allow,
548	sub: () => () => {},
549	};
550	const { client } = createAuthClient(() => currentUser);
551
552	const mutation = client.define({
553	id: "test-auth-allowed",
554	auth: true,
555	isAllowed,
556	mutate: async () => "ok",
557	optimistic: () => {},
558	describe: "Test allowed",
559	describeResult: "Tested allowed",
560	});
561
562	assertEquals(mutation.isAllowed(), true);
563	allow = false;
564	assertEquals(mutation.isAllowed(), false);
565	allow = true;
566	currentUser = null;
567	assertEquals(mutation.isAllowed(), false);
568	});

test/debounce.test.tsx+3

test/optimistic.test.tsx+1

...	@@ -18,6 +18,7 @@ test.each([	...	@@ -18,6 +18,7 @@ test.each([
18	const streamRefreshes = new IterableStream<string>();	18	const streamRefreshes = new IterableStream<string>();
19		19
20	const mutTest = client.define({	20	const mutTest = client.define({
		21	id: "test-1",
21	mutate: async () => {	22	mutate: async () => {
22	return (await streamResults.next()).value;	23	return (await streamResults.next()).value;
23	},	24	},

test/optimistic.ts+1

...	@@ -10,6 +10,7 @@ test("passes context value to functions", async () => {	...	@@ -10,6 +10,7 @@ test("passes context value to functions", async () => {
10		10
11	let values: number[] = [];	11	let values: number[] = [];
12	const mutTest = client.define({	12	const mutTest = client.define({
		13	id: "test-1",
13	async mutate() {	14	async mutate() {
14	values.push(this.contextValue);	15	values.push(this.contextValue);
15	calls.push("mutate");	16	calls.push("mutate");

test/ordering.test.ts+9

...	@@ -11,6 +11,7 @@ test.each([	...	@@ -11,6 +11,7 @@ test.each([
11	const { client, errorMessages, successMessages } = createTestMutationClient();	11	const { client, errorMessages, successMessages } = createTestMutationClient();
12	const calls: string[] = [];	12	const calls: string[] = [];
13	const mutTest = client.define({	13	const mutTest = client.define({
		14	id: "test-1",
14	mutate: async () => {	15	mutate: async () => {
15	calls.push("mutate");	16	calls.push("mutate");
16	await delay(100);	17	await delay(100);
...	@@ -60,6 +61,7 @@ test("error case: describe is called before rollback", async () => {	...	@@ -60,6 +61,7 @@ test("error case: describe is called before rollback", async () => {
60	let optimisticState = false;	61	let optimisticState = false;
61		62
62	const mutTest = client.define({	63	const mutTest = client.define({
		64	id: "test-2",
63	mutate: async () => {	65	mutate: async () => {
64	calls.push("mutate");	66	calls.push("mutate");
65	await delay(100);	67	await delay(100);
...	@@ -122,6 +124,7 @@ test("error case with refetchOnSuccess=false still refetches", async () => {	...	@@ -122,6 +124,7 @@ test("error case with refetchOnSuccess=false still refetches", async () => {
122	const calls: string[] = [];	124	const calls: string[] = [];
123		125
124	const mutTest = client.define({	126	const mutTest = client.define({
		127	id: "test-3",
125	mutate: async () => {	128	mutate: async () => {
126	calls.push("mutate");	129	calls.push("mutate");
127	await delay(100);	130	await delay(100);
...	@@ -155,6 +158,7 @@ test("multiple mutations in sequence: ordering preserved", async () => {	...	@@ -155,6 +158,7 @@ test("multiple mutations in sequence: ordering preserved", async () => {
155	const calls: string[] = [];	158	const calls: string[] = [];
156		159
157	const mutTest = client.define({	160	const mutTest = client.define({
		161	id: "test-4",
158	mutate: async (id: number) => {	162	mutate: async (id: number) => {
159	calls.push(`mutate-${id}`);	163	calls.push(`mutate-${id}`);
160	await delay(100);	164	await delay(100);
...	@@ -226,6 +230,7 @@ test("error in second mutation: first stays applied, second rolls back", async (	...	@@ -226,6 +230,7 @@ test("error in second mutation: first stays applied, second rolls back", async (
226	let state = 0;	230	let state = 0;
227		231
228	const mutTest = client.define({	232	const mutTest = client.define({
		233	id: "test-5",
229	mutate: async (id: number) => {	234	mutate: async (id: number) => {
230	calls.push(`mutate-${id}`);	235	calls.push(`mutate-${id}`);
231	await delay(100);	236	await delay(100);
...	@@ -275,6 +280,7 @@ test("onSuccess callback ordering relative to refetch", async () => {	...	@@ -275,6 +280,7 @@ test("onSuccess callback ordering relative to refetch", async () => {
275	const calls: string[] = [];	280	const calls: string[] = [];
276		281
277	const mutTest = client.define({	282	const mutTest = client.define({
		283	id: "test-6",
278	mutate: async () => {	284	mutate: async () => {
279	calls.push("mutate");	285	calls.push("mutate");
280	await delay(100);	286	await delay(100);
...	@@ -321,6 +327,7 @@ test("runWithOptions callbacks: onError called before global handler", async ()	...	@@ -321,6 +327,7 @@ test("runWithOptions callbacks: onError called before global handler", async ()
321	const calls: string[] = [];	327	const calls: string[] = [];
322		328
323	const mutTest = client.define({	329	const mutTest = client.define({
		330	id: "test-7",
324	mutate: async () => {	331	mutate: async () => {
325	await delay(100);	332	await delay(100);
326	throw new Error("Failed");	333	throw new Error("Failed");
...	@@ -364,6 +371,7 @@ test("runWithOptions callbacks: onSuccess called before global handler", async (	...	@@ -364,6 +371,7 @@ test("runWithOptions callbacks: onSuccess called before global handler", async (
364	const calls: string[] = [];	371	const calls: string[] = [];
365		372
366	const mutTest = client.define({	373	const mutTest = client.define({
		374	id: "test-8",
367	mutate: async () => {	375	mutate: async () => {
368	await delay(100);	376	await delay(100);
369	return "result";	377	return "result";
...	@@ -407,6 +415,7 @@ test("optimistic update with no describeResult: no success message", async () =>	...	@@ -407,6 +415,7 @@ test("optimistic update with no describeResult: no success message", async () =>
407	const calls: string[] = [];	415	const calls: string[] = [];
408		416
409	const mutTest = client.define({	417	const mutTest = client.define({
		418	id: "test-9",
410	mutate: async () => {	419	mutate: async () => {
411	await delay(100);	420	await delay(100);
412	return "result";	421	return "result";

test/runWithOptions.test.tsx+2

...	@@ -13,6 +13,7 @@ test("runWithOptions should allow react hook to do local handling", async () =>	...	@@ -13,6 +13,7 @@ test("runWithOptions should allow react hook to do local handling", async () =>
13	const s = new IterableStream<string>();	13	const s = new IterableStream<string>();
14		14
15	const mutTest = client.define({	15	const mutTest = client.define({
		16	id: "test-1",
16	mutate: async () => {	17	mutate: async () => {
17	return (await s.next()).value;	18	return (await s.next()).value;
18	},	19	},
...	@@ -74,6 +75,7 @@ test("runAsHeadlessPromise rejects with the underlying error", async () => {	...	@@ -74,6 +75,7 @@ test("runAsHeadlessPromise rejects with the underlying error", async () => {
74	const localErrors: unknown[] = [];	75	const localErrors: unknown[] = [];
75		76
76	const mutTest = client.define({	77	const mutTest = client.define({
		78	id: "test-2",
77	mutate: async () => {	79	mutate: async () => {
78	return (await s.next()).value;	80	return (await s.next()).value;
79	},	81	},

test/setError.test.tsx+3

...	@@ -12,6 +12,7 @@ test("setError should manually set error state on the hook", async () => {	...	@@ -12,6 +12,7 @@ test("setError should manually set error state on the hook", async () => {
12	const { client, successMessages, errorMessages } = createTestMutationClient();	12	const { client, successMessages, errorMessages } = createTestMutationClient();
13		13
14	const mutTest = client.define({	14	const mutTest = client.define({
		15	id: "test-1",
15	mutate: async () => {	16	mutate: async () => {
16	return "success";	17	return "success";
17	},	18	},
...	@@ -92,6 +93,7 @@ test("setError should override success state", async () => {	...	@@ -92,6 +93,7 @@ test("setError should override success state", async () => {
92	const s = new IterableStream<string>();	93	const s = new IterableStream<string>();
93		94
94	const mutTest = client.define({	95	const mutTest = client.define({
		96	id: "test-2",
95	mutate: async () => {	97	mutate: async () => {
96	return (await s.next()).value;	98	return (await s.next()).value;
97	},	99	},
...	@@ -206,6 +208,7 @@ test("setError should work with different error types", async () => {	...	@@ -206,6 +208,7 @@ test("setError should work with different error types", async () => {
206	const { client } = createTestMutationClient();	208	const { client } = createTestMutationClient();
207		209
208	const mutTest = client.define({	210	const mutTest = client.define({
		211	id: "test-3",
209	mutate: async () => {	212	mutate: async () => {
210	return "success";	213	return "success";
211	},	214	},

test/snapshot.test.tsx+4

test/tanstack-query-helpers.test.ts+22-1

...	@@ -1,7 +1,7 @@	...	@@ -1,7 +1,7 @@
1	import { assertEquals } from "@std/assert";	1	import { assertEquals } from "@std/assert";
2	import { QueryClient, queryOptions } from "@tanstack/react-query";	2	import { QueryClient, queryOptions } from "@tanstack/react-query";
3	import { test } from "vitest";	3	import { test } from "vitest";
4	import { queryClientOptimisticHelpers } from "../src/tanstack-query.ts";	4	import { queryClientOptimisticHelpers, reactiveFromQueryCache } from "../src/tanstack-query.ts";
5		5
6	interface TestData {	6	interface TestData {
7	name: string;	7	name: string;
...	@@ -89,6 +89,27 @@ test("helpers can be spread and retain bound this", () => {	...	@@ -89,6 +89,27 @@ test("helpers can be spread and retain bound this", () => {
89	assertEquals(result?.count, 12);	89	assertEquals(result?.count, 12);
90	});	90	});
91		91
		92	test("reactiveFromQueryCache derives and subscribes to query data", () => {
		93	const { client, queryTest } = createTestQueryClient();
		94	const reactive = reactiveFromQueryCache(
		95	client,
		96	queryTest,
		97	(data) => data ? { name: data.name } : null,
		98	);
		99	let changes = 0;
		100	const unsubscribe = reactive.sub(() => changes += 1);
		101
		102	assertEquals(reactive.get(), { name: "Test" });
		103
		104	client.setQueryData(queryTest.queryKey, { ...initialData, name: "Updated" });
		105	assertEquals(reactive.get(), { name: "Updated" });
		106	assertEquals(changes, 1);
		107
		108	unsubscribe();
		109	client.setQueryData(queryTest.queryKey, { ...initialData, name: "Ignored" });
		110	assertEquals(changes, 1);
		111	});
		112
92	// ============================================================================	113	// ============================================================================
93	// set() tests	114	// set() tests
94	// ============================================================================	115	// ============================================================================

test/useMutate.test.tsx+3

author	clover caruso <git@paperclover.net> 2026-05-15 13:39:57-07:00
committer	clover caruso <git@paperclover.net> 2026-07-22 12:53:46-07:00
log	7ad627cb1d7df5aad122280d12e72244e86cb447
tree	d855cb307d31a85f066bae1f003eb9dd5ceb0708
parent	cc21b6dbb13e3b9425367a3e4a740ae8478a1633
signature	Signed by SSH key SHA256:cOKiuRFOeSRxne6EWgHtdQQSlBxjOXm2hOCFnCdLQbQ

...	@@ -13,6 +13,7 @@ test("debounceMs: waits before first call", async () => {	...	@@ -13,6 +13,7 @@ test("debounceMs: waits before first call", async () => {
13	const s = new IterableStream<string>();	13	const s = new IterableStream<string>();
14		14
15	const mutTest = client.define({	15	const mutTest = client.define({
		16	id: "test-1",
16	mutate: async () => {	17	mutate: async () => {
17	return (await s.next()).value;	18	return (await s.next()).value;
18	},	19	},
...	@@ -107,6 +108,7 @@ test("debounceMs: batch multiple calls together", async () => {	...	@@ -107,6 +108,7 @@ test("debounceMs: batch multiple calls together", async () => {
107		108
108	const mutations: number[] = [];	109	const mutations: number[] = [];
109	const mutTest = client.define({	110	const mutTest = client.define({
		111	id: "test-2",
110	mutate: async (k: number) => {	112	mutate: async (k: number) => {
111	mutations.push(k);	113	mutations.push(k);
112	return (await s.next()).value;	114	return (await s.next()).value;
...	@@ -188,6 +190,7 @@ test.todo("debounceImmediate runs the first one right away", async () => {	...	@@ -188,6 +190,7 @@ test.todo("debounceImmediate runs the first one right away", async () => {
188		190
189	const mutations: number[] = [];	191	const mutations: number[] = [];
190	const mutTest = client.define({	192	const mutTest = client.define({
		193	id: "test-3",
191	mutate: async (k: number) => {	194	mutate: async (k: number) => {
192	mutations.push(k);	195	mutations.push(k);
193	return (await s.next()).value;	196	return (await s.next()).value;

...	@@ -15,6 +15,7 @@ test("snapshot should skip no-op mutation", async () => {	...	@@ -15,6 +15,7 @@ test("snapshot should skip no-op mutation", async () => {
15	let state = { value: "initial" };	15	let state = { value: "initial" };
16	let failed = false;	16	let failed = false;
17	const mutUpdate = client.define({	17	const mutUpdate = client.define({
		18	id: "test-1",
18	mutate: async (newValue: string) => {	19	mutate: async (newValue: string) => {
19	failed = true;	20	failed = true;
20	},	21	},
...	@@ -63,6 +64,7 @@ test("snapshot should allow mutation when value changes", async () => {	...	@@ -63,6 +64,7 @@ test("snapshot should allow mutation when value changes", async () => {
63	let state = { value: "initial" };	64	let state = { value: "initial" };
64		65
65	const mutUpdate = client.define({	66	const mutUpdate = client.define({
		67	id: "test-2",
66	mutate: async (newValue: string) => {	68	mutate: async (newValue: string) => {
67	return (await s.next()).value;	69	return (await s.next()).value;
68	},	70	},
...	@@ -116,6 +118,7 @@ test("debounced snapshot should skip when final state equals initial", async ()	...	@@ -116,6 +118,7 @@ test("debounced snapshot should skip when final state equals initial", async ()
116		118
117	const mutations: string[] = [];	119	const mutations: string[] = [];
118	const mutUpdate = client.define({	120	const mutUpdate = client.define({
		121	id: "test-3",
119	mutate: async (newValue: string) => {	122	mutate: async (newValue: string) => {
120	mutations.push(newValue);	123	mutations.push(newValue);
121	},	124	},
...	@@ -176,6 +179,7 @@ test("debounced snapshot should mutate when final differs from initial", async (	...	@@ -176,6 +179,7 @@ test("debounced snapshot should mutate when final differs from initial", async (
176	let state = { value: "initial" };	179	let state = { value: "initial" };
177		180
178	const mutUpdate = client.define({	181	const mutUpdate = client.define({
		182	id: "test-4",
179	mutate: async (newValue: string) => {	183	mutate: async (newValue: string) => {
180	return (await s.next()).value;	184	return (await s.next()).value;
181	},	185	},

...	@@ -14,6 +14,7 @@ test("useMutate - global error and success handling", async () => {	...	@@ -14,6 +14,7 @@ test("useMutate - global error and success handling", async () => {
14	const s = new IterableStream<string>();	14	const s = new IterableStream<string>();
15		15
16	const mutTest = client.define({	16	const mutTest = client.define({
		17	id: "test-1",
17	mutate: async () => {	18	mutate: async () => {
18	return (await s.next()).value;	19	return (await s.next()).value;
19	},	20	},
...	@@ -99,6 +100,7 @@ test("useMutate - local error and success handling", async () => {	...	@@ -99,6 +100,7 @@ test("useMutate - local error and success handling", async () => {
99	const s = new IterableStream<string>();	100	const s = new IterableStream<string>();
100		101
101	const mutTest = client.define({	102	const mutTest = client.define({
		103	id: "test-2",
102	mutate: async () => {	104	mutate: async () => {
103	return (await s.next()).value;	105	return (await s.next()).value;
104	},	106	},
...	@@ -282,6 +284,7 @@ test("MutationButton should allow args={null} to disable mutation runs", async (	...	@@ -282,6 +284,7 @@ test("MutationButton should allow args={null} to disable mutation runs", async (
282	const mutate = vi.fn(async (value: number) => value + 1);	284	const mutate = vi.fn(async (value: number) => value + 1);
283		285
284	const mutTest = client.define({	286	const mutTest = client.define({
		287	id: "test-3",
285	mutate,	288	mutate,
286	describe: "Test the action",	289	describe: "Test the action",
287	describeResult: "Tested the action",	290	describeResult: "Tested the action",

feat: authenticated mutations