@classytic/arc-next 0.11.1 → 0.13.0

package/dist/hooks.d.ts

@@ -2,15 +2,14 @@ import { ArcClient, UseRouterHook } from "./client.js";
 import { AggResult, AggRow, BaseApi } from "./api.js";
 import { CacheUtils, QueryKeys } from "./cache.js";
 import { MutationCallbacks, MutationMessages, TransitionMutationReturn } from "./mutation.js";
-import { DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, RequestPassthrough } from "./query.js";
-import { SoftDeleteMethods } from "./presets/soft-delete.js";
 import { BulkMethods } from "./presets/bulk.js";
+import { SearchPresetMethods } from "./presets/search.js";
 import { SlugLookupMethods } from "./presets/slug.js";
+import { SoftDeleteMethods } from "./presets/soft-delete.js";
 import { TreeMethods } from "./presets/tree.js";
-import { SearchPresetMethods } from "./presets/search.js";
+import { DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, RequestPassthrough } from "./query.js";
 import { QueryKey, UseQueryResult } from "@tanstack/react-query";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
-
 //#region src/hooks.d.ts
 /**
  * CRUD API interface accepted by createCrudHooks.
@@ -22,11 +21,12 @@ import { PaginatedResult } from "@classytic/repo-core/pagination";
  * any cast — yet a vanilla `createCrudApi('todos')` instance has none of them
  * in autocomplete unless you opt in.
  */
-type CrudApi<T = unknown, TCreate = Partial<T>, TUpdate = Partial<T>> = Pick<BaseApi<T, TCreate, TUpdate>, 'getAll' | 'getById' | 'create' | 'update' | 'delete' | 'count'> & {
-  upload?: BaseApi<T, TCreate, TUpdate>['upload'];
-  dispatchAction?: BaseApi<T, TCreate, TUpdate>['dispatchAction'];
-  invokeRoute?: BaseApi<T, TCreate, TUpdate>['invokeRoute']; /** Declared aggregations (arc 2.13+). Always available on BaseApi. */
-  aggregate?: BaseApi<T, TCreate, TUpdate>['aggregate'];
+type CrudApi<T = unknown, TCreate = Partial<T>, TUpdate = Partial<T>> = Pick<BaseApi<T, TCreate, TUpdate>, "getAll" | "getById" | "create" | "update" | "delete" | "count"> & {
+  upload?: BaseApi<T, TCreate, TUpdate>["upload"];
+  dispatchAction?: BaseApi<T, TCreate, TUpdate>["dispatchAction"];
+  invokeRoute?: BaseApi<T, TCreate, TUpdate>["invokeRoute"];
+  /** Declared aggregations (arc 2.13+). Always available on BaseApi. */
+  aggregate?: BaseApi<T, TCreate, TUpdate>["aggregate"];
 } & Partial<SoftDeleteMethods<T>> & Partial<BulkMethods<T, TCreate, TUpdate>> & Partial<SlugLookupMethods<T>> & Partial<TreeMethods<T>> & Partial<SearchPresetMethods<T>>;
 /** Args + options for `useAggregation`. Mirrors `ListQueryOptions` for DX consistency. */
 interface AggregationQueryOptions<TRow extends AggRow = AggRow, TData = AggResult<TRow>> {
@@ -182,11 +182,15 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
   KEYS: QueryKeys;
   cache: CacheUtils<T>;
   useList: {
-    /** New signature — auto-injects token/orgId from configureAuth() context */(params?: Record<string, unknown>, options?: ListQueryOptions<T>): ListQueryResult<T>; /** Legacy signature — explicit token */
+    /** New signature — auto-injects token/orgId from configureAuth() context */
+    (params?: Record<string, unknown>, options?: ListQueryOptions<T>): ListQueryResult<T>;
+    /** Legacy signature — explicit token */
     (token: string | null, params?: Record<string, unknown>, options?: ListQueryOptions<T>): ListQueryResult<T>;
   };
   useDetail: {
-    /** New signature — auto-injects token from configureAuth() context */(id: string | null, options?: DetailQueryOptions<T>): DetailQueryResult<T>; /** Legacy signature — explicit token */
+    /** New signature — auto-injects token from configureAuth() context */
+    (id: string | null, options?: DetailQueryOptions<T>): DetailQueryResult<T>;
+    /** Legacy signature — explicit token */
     (id: string | null, token: string | null, options?: DetailQueryOptions<T>): DetailQueryResult<T>;
   };
   /**
@@ -202,7 +206,9 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
    */
   useSuspenseDetail: (id: string, options?: Omit<DetailQueryOptions<T>, "enabled">) => DetailQueryResult<T>;
   useInfiniteList: {
-    /** New signature — auto-injects token/orgId from configureAuth() context */(params?: Record<string, unknown>, options?: InfiniteListQueryOptions): InfiniteListQueryResult<T>; /** Legacy signature — explicit token */
+    /** New signature — auto-injects token/orgId from configureAuth() context */
+    (params?: Record<string, unknown>, options?: InfiniteListQueryOptions): InfiniteListQueryResult<T>;
+    /** Legacy signature — explicit token */
     (token: string | null, params?: Record<string, unknown>, options?: InfiniteListQueryOptions): InfiniteListQueryResult<T>;
   };
   useActions: () => CrudActions<T, TCreate, TUpdate>;
@@ -223,7 +229,8 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
    * (approve/cancel/dispatch) instead of bespoke routes.
    */
   useAction: <TResult = T, TBody extends Record<string, unknown> = Record<string, unknown>>(options?: {
-    invalidateQueries?: QueryKey[]; /** Default action name. Can be overridden per-call via `mutate({ action })`. */
+    invalidateQueries?: QueryKey[];
+    /** Default action name. Can be overridden per-call via `mutate({ action })`. */
     action?: string;
     messages?: MutationMessages<TResult, {
       id: string;
@@ -335,15 +342,20 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
    * `ssePlugin` (`/events/stream`). Pass `enabled: false` to opt out.
    */
   useResourceSync: (options?: {
-    source?: 'ws' | 'sse'; /** Override resource name. Defaults to the factory's `entityKey`. */
-    resource?: string; /** Override path (default: `/ws` or `/events/stream`). */
-    path?: string; /** Whether the connection is active. Default: true. */
-    enabled?: boolean; /** Per-event hook fired AFTER cache invalidation. */
+    source?: "ws" | "sse";
+    /** Override resource name. Defaults to the factory's `entityKey`. */
+    resource?: string;
+    /** Override path (default: `/ws` or `/events/stream`). */
+    path?: string;
+    /** Whether the connection is active. Default: true. */
+    enabled?: boolean;
+    /** Per-event hook fired AFTER cache invalidation. */
     onEvent?: (event: {
-      operation: 'created' | 'updated' | 'deleted';
+      operation: "created" | "updated" | "deleted";
       id?: string;
       data: unknown;
-    }) => void; /** Connection-state listener. */
+    }) => void;
+    /** Connection-state listener. */
     onConnectionChange?: (connected: boolean) => void;
   }) => {
     isConnected: boolean;
@@ -360,15 +372,6 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
  * configureNavigation(useRouter);
  */
 declare function configureNavigation(hook: UseRouterHook): void;
-declare function createCrudHooks<T, TCreate = Partial<T>, TUpdate = Partial<T>>({
-  api,
-  entityKey,
-  singular,
-  plural,
-  idField,
-  defaults,
-  callbacks,
-  client
-}: CrudHooksConfig<T, TCreate, TUpdate>): CrudHooksReturn<T, TCreate, TUpdate>;
+declare function createCrudHooks<T, TCreate = Partial<T>, TUpdate = Partial<T>>({ api, entityKey, singular, plural, idField, defaults, callbacks, client }: CrudHooksConfig<T, TCreate, TUpdate>): CrudHooksReturn<T, TCreate, TUpdate>;
 //#endregion
 export { AggregationQueryOptions, BulkActions, CallOptions, CrudActions, CrudApi, CrudHooksConfig, CrudHooksReturn, DeleteParams, MutationParams, NavigateFn, NavigationOptions, UpdateParams, configureNavigation, createCrudHooks };

package/dist/hooks.js

@@ -2,7 +2,7 @@
 
 import { getAuthMode, getClientAuthContext, hasGlobalStaticAuth } from "./client.js";
 import { isKeysetPagination, isOffsetPagination } from "./api.js";
-import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, syncDetailToLists, updateListCache, withOrgParams } from "./cache.js";
+import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, prependToListCache, replaceItemInListCache, syncDetailToLists, updateListCache, withOrgParams } from "./cache.js";
 import { findItemInListCache, useDetailQuery, useInfiniteListQuery, useListQuery, useSuspenseDetailQuery, useSuspenseListQuery } from "./query.js";
 import { useMutationWithTransition, useOptimisticMutation } from "./mutation.js";
 import { subscribeToEvents } from "./sse.js";
@@ -58,6 +58,32 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 	}
 	const KEYS = createQueryKeys(entityKey);
 	const cache = createCacheUtils(KEYS);
+	/**
+	* Shared identity for this resource's write mutations (create / update /
+	* delete). Powers last-standing invalidation in `useOptimisticMutation`:
+	* rapid sequential writes trigger ONE settled refetch instead of N racing
+	* ones, so an early write's refetch can never clobber a later write's
+	* optimistic state.
+	*/
+	const WRITE_MUTATION_KEY = [entityKey, "write"];
+	/**
+	* Per-record write ordering. `update`/`remove`/`restore` calls against the
+	* SAME record are chained (call order = server application order = cache
+	* application order); writes to different records stay fully parallel. A
+	* failed write does not block the next one — each link runs regardless of
+	* the previous outcome. Factory-scoped so every component using this
+	* resource's hooks shares one chain per record.
+	*/
+	const writeChains = /* @__PURE__ */ new Map();
+	function enqueueWrite(recordId, run) {
+		const result = (writeChains.get(recordId) ?? Promise.resolve()).then(run, run);
+		const tail = result.then(() => void 0, () => void 0);
+		writeChains.set(recordId, tail);
+		tail.then(() => {
+			if (writeChains.get(recordId) === tail) writeChains.delete(recordId);
+		});
+		return result;
+	}
 	const instanceToast = client?.toast;
 	const instanceNavigation = client?.navigation ?? null;
 	const resolveAuthMode = () => client?.config?.authMode ?? getAuthMode();
@@ -149,7 +175,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const detailResult = useDetailQuery({
 			queryKey: fullDetailKey,
 			queryFn: ({ signal }) => api.getById({
-				id,
+				id: id ?? "",
 				token,
 				organizationId,
 				params: queryParams,
@@ -260,6 +286,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const queryClient = useQueryClient();
 		const silentRef = useRef(false);
 		const shouldToast = useCallback(() => !silentRef.current, []);
+		const tempIdsRef = useRef(/* @__PURE__ */ new WeakMap());
 		const createMutation = useOptimisticMutation({
 			mutationFn: ({ token, organizationId, data }) => api.create({
 				token,
@@ -268,14 +295,32 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			}),
 			queryClient,
 			queryKeys: [KEYS.lists(), KEYS.aggregations()],
+			mutationKey: WRITE_MUTATION_KEY,
 			shouldToast,
-			optimisticUpdate: (oldData, { data }) => {
-				const optimisticItem = {
+			optimisticUpdate: (oldData, variables, qKey) => {
+				if (qKey[1] !== "list") return oldData;
+				const { data } = variables;
+				let tempId = tempIdsRef.current.get(variables);
+				if (!tempId) {
+					tempId = resolveItemId(data) ?? `temp-${globalThis.crypto?.randomUUID?.() ?? Date.now()}`;
+					tempIdsRef.current.set(variables, tempId);
+				}
+				return prependToListCache(oldData, {
 					...data,
 					_optimistic: true,
-					[idField ?? (resolveItemId(data) ? "id" : "_id")]: resolveItemId(data) ?? `temp-${Date.now()}`
-				};
-				return updateListCache(oldData, (arr) => [optimisticItem, ...arr || []]);
+					[idField ?? (resolveItemId(data) ? "id" : "_id")]: tempId
+				});
+			},
+			reconcile: (raw, variables) => {
+				const serverDoc = extractItem(raw);
+				if (!serverDoc || typeof serverDoc !== "object") return;
+				const tempId = tempIdsRef.current.get(variables);
+				if (tempId) for (const [qKey, qData] of queryClient.getQueriesData({ queryKey: KEYS.lists() })) {
+					const next = replaceItemInListCache(qData, tempId, serverDoc, idField ? { idField } : {});
+					if (next !== qData) queryClient.setQueryData(qKey, next);
+				}
+				const realId = resolveItemId(serverDoc);
+				if (realId) queryClient.setQueryData(KEYS.detail(realId), serverDoc);
 			},
 			onSuccess: (raw, variables) => {
 				callbacks.onCreate?.onSuccess?.(extractItem(raw), { data: variables.data }, void 0);
@@ -305,26 +350,32 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				KEYS.details(),
 				KEYS.aggregations()
 			],
+			mutationKey: WRITE_MUTATION_KEY,
 			shouldToast,
-			optimisticUpdate: (oldData, { id, data }) => {
-				const updated = updateListCache(oldData, (arr) => (arr || []).map((item) => resolveItemId(item) === id ? {
+			optimisticUpdate: (oldData, { id, data }, qKey) => {
+				if (qKey[1] === "detail") {
+					if (qKey[2] !== id || !oldData || typeof oldData !== "object") return oldData;
+					return {
+						...oldData,
+						...data
+					};
+				}
+				if (qKey[1] !== "list") return oldData;
+				return updateListCache(oldData, (arr) => (arr || []).map((item) => resolveItemId(item) === id ? {
 					...item,
 					...data
 				} : item));
-				const detailUpdater = (current) => current ? {
-					...current,
-					data: {
-						...current.data || {},
-						...data
-					}
-				} : current;
-				queryClient.getQueriesData({ queryKey: KEYS.detail(id) }).forEach(([qKey, qData]) => {
-					if (qData) queryClient.setQueryData(qKey, detailUpdater);
-				});
-				return updated;
+			},
+			reconcile: (raw, { id }) => {
+				const serverDoc = extractItem(raw);
+				if (!serverDoc || typeof serverDoc !== "object") return;
+				for (const [qKey, qData] of queryClient.getQueriesData({ queryKey: KEYS.detail(id) })) if (qData) queryClient.setQueryData(qKey, serverDoc);
+				for (const [qKey, qData] of queryClient.getQueriesData({ queryKey: KEYS.lists() })) {
+					const next = replaceItemInListCache(qData, id, serverDoc, idField ? { idField } : {});
+					if (next !== qData) queryClient.setQueryData(qKey, next);
+				}
 			},
 			onSuccess: (raw, { id, data: updateData }) => {
-				queryClient.invalidateQueries({ queryKey: KEYS.detail(id) });
 				callbacks.onUpdate?.onSuccess?.(extractItem(raw), {
 					id,
 					data: updateData
@@ -356,8 +407,10 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			}),
 			queryClient,
 			queryKeys: [KEYS.lists(), KEYS.aggregations()],
+			mutationKey: WRITE_MUTATION_KEY,
 			shouldToast,
-			optimisticUpdate: (oldData, { id }) => {
+			optimisticUpdate: (oldData, { id }, qKey) => {
+				if (qKey[1] !== "list") return oldData;
 				return updateListCache(oldData, (arr) => (arr || []).filter((item) => resolveItemId(item) !== id));
 			},
 			onSuccess: (data, { id }) => {
@@ -424,7 +477,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			update: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const entity = extractItem(await updateMutation.mutateAsync(resolveActionAuth(params)));
+					const entity = extractItem(await enqueueWrite(params.id, () => updateMutation.mutateAsync(resolveActionAuth(params))));
 					options?.onSuccess?.(entity);
 					options?.onSettled?.(entity, null);
 					return entity;
@@ -439,7 +492,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			remove: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const result = await deleteMutation.mutateAsync(resolveActionAuth(params));
+					const result = await enqueueWrite(params.id, () => deleteMutation.mutateAsync(resolveActionAuth(params)));
 					options?.onSuccess?.(result);
 					options?.onSettled?.(result, null);
 					return result;
@@ -454,7 +507,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			restore: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const entity = extractItem(await restoreMutation.mutateAsync(resolveActionAuth(params)));
+					const entity = extractItem(await enqueueWrite(params.id, () => restoreMutation.mutateAsync(resolveActionAuth(params))));
 					options?.onSuccess?.(entity);
 					options?.onSettled?.(entity, null);
 					return entity;
@@ -631,7 +684,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			queryFn: ({ signal }) => {
 				if (!api.getBySlug) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a getBySlug method`));
 				return api.getBySlug({
-					slug,
+					slug: slug ?? "",
 					token,
 					organizationId,
 					params: queryParams,
@@ -704,7 +757,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				return api.getChildren({
 					token,
 					organizationId,
-					parentId,
+					parentId: parentId ?? "",
 					params: restParams,
 					options: {
 						signal,
@@ -721,6 +774,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		});
 	}
 	function useBulkActions() {
+		const queryClient = useQueryClient();
 		const bulkCreateMutation = useMutationWithTransition({
 			mutationFn: (vars) => {
 				if (!api.bulkCreate) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a bulkCreate method`));
@@ -732,6 +786,14 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				});
 			},
 			invalidateQueries: [KEYS.lists(), KEYS.aggregations()],
+			onSuccess: (raw) => {
+				const created = raw?.data;
+				if (!Array.isArray(created)) return;
+				for (const doc of created) {
+					const id = resolveItemId(doc);
+					if (id) queryClient.setQueryData(KEYS.detail(id), doc);
+				}
+			},
 			messages: {
 				success: `${pluralName} created successfully`,
 				error: `Failed to create ${pluralName.toLowerCase()}`
@@ -754,6 +816,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				KEYS.details(),
 				KEYS.aggregations()
 			],
+			shouldInvalidate: (raw) => {
+				const r = raw;
+				if (!r || typeof r.modifiedCount !== "number") return true;
+				return r.modifiedCount > 0 || (r.upsertedCount ?? 0) > 0;
+			},
 			messages: {
 				success: `${pluralName} updated successfully`,
 				error: `Failed to update ${pluralName.toLowerCase()}`
@@ -771,6 +838,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				});
 			},
 			invalidateQueries: [KEYS.lists(), KEYS.aggregations()],
+			shouldInvalidate: (raw) => {
+				const r = raw;
+				if (!r || typeof r.deletedCount !== "number") return true;
+				return r.deletedCount > 0;
+			},
 			messages: {
 				success: `${pluralName} deleted successfully`,
 				error: `Failed to delete ${pluralName.toLowerCase()}`

package/dist/mutation.d.ts

@@ -1,7 +1,5 @@
 import { ToastHandler } from "./client.js";
-import * as _$_tanstack_react_query0 from "@tanstack/react-query";
 import { QueryClient, QueryKey, UseMutateAsyncFunction, UseMutateFunction } from "@tanstack/react-query";
-
 //#region src/mutation.d.ts
 /**
  * Toast copy for a mutation. Generic over the mutation's result/variables so
@@ -60,6 +58,13 @@ declare function getToastHandler(): ToastHandler;
 interface TransitionMutationConfig<TData, TVariables> {
   mutationFn: (variables: TVariables) => Promise<TData>;
   invalidateQueries?: QueryKey[];
+  /**
+   * Result-aware invalidation gate. When provided, `invalidateQueries` only
+   * fire if this returns true for the mutation result — lets bulk operations
+   * skip refetching everything when the server reports nothing changed
+   * (`modifiedCount: 0`, `deletedCount: 0`).
+   */
+  shouldInvalidate?: (data: TData) => boolean;
   onSuccess?: (data: TData, variables: TVariables) => void;
   onError?: (error: Error, variables: TVariables) => void;
   onSettled?: (data: TData | undefined, error: Error | null, variables: TVariables) => void;
@@ -115,7 +120,28 @@ interface CreateOptimisticMutationConfig<TData, TVariables> {
   mutationFn: (variables: TVariables) => Promise<TData>;
   queryClient: QueryClient;
   queryKeys: QueryKey[];
-  optimisticUpdate?: (oldData: unknown, variables: TVariables) => unknown;
+  /**
+   * Per-cache-entry optimistic updater. Receives the concrete query key of
+   * the entry being updated so a single updater can treat list, detail, and
+   * aggregation caches differently (merge the doc into `[e,'detail',id]`,
+   * map items inside `[e,'list',…]`, leave `[e,'aggregation',…]` untouched).
+   * Return the input unchanged to skip the write for that entry.
+   */
+  optimisticUpdate?: (oldData: unknown, variables: TVariables, queryKey: QueryKey) => unknown;
+  /**
+   * Shared identity for this resource's write mutations. When set, settled
+   * invalidation only fires from the LAST pending mutation carrying the same
+   * key (`isMutating === 1`) — rapid sequential writes produce one refetch
+   * at the end instead of N racing refetches, and a refetch triggered by
+   * write #1 can never clobber write #2's optimistic state.
+   */
+  mutationKey?: readonly unknown[];
+  /**
+   * Post-success cache reconciliation, run BEFORE any invalidation while the
+   * optimistic state is still in place. Use to swap temp IDs for server
+   * documents or seed detail caches from the response.
+   */
+  reconcile?: (data: TData, variables: TVariables) => void;
   onSuccess?: (data: TData, variables: TVariables) => void;
   onError?: (error: Error, variables: TVariables) => void;
   onSettled?: (data: TData | undefined, error: Error | null, variables: TVariables) => void;
@@ -124,7 +150,7 @@ interface CreateOptimisticMutationConfig<TData, TVariables> {
   shouldToast?: () => boolean;
   toastHandler?: ToastHandler;
 }
-declare function useOptimisticMutation<TData, TVariables>(config: CreateOptimisticMutationConfig<TData, TVariables>): _$_tanstack_react_query0.UseMutationResult<TData, Error, TVariables, {
+declare function useOptimisticMutation<TData, TVariables>(config: CreateOptimisticMutationConfig<TData, TVariables>): import("@tanstack/react-query").UseMutationResult<TData, Error, TVariables, {
   previous: {
     key: readonly unknown[];
     data: [readonly unknown[], unknown][];

package/dist/mutation.js

@@ -2,12 +2,12 @@
 
 import { getQuotaDetails, isArcApiError, isAutoIdempotency } from "./client.js";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { useCallback, useRef, useTransition } from "react";
+import { useRef, useTransition } from "react";
 
 //#region src/mutation.ts
 let toastHandler = {
-	success: (msg) => console.log("[Success]", msg),
-	error: (msg) => console.error("[Error]", msg)
+	success: () => {},
+	error: () => {}
 };
 /**
 * Configure toast handler. Call once at app init.
@@ -78,9 +78,11 @@ function useMutationWithTransition(config) {
 		},
 		onSuccess: (data, variables) => {
 			const invalidate = () => {
-				invalidateQueries.forEach((key) => queryClient.invalidateQueries({ queryKey: key }));
+				invalidateQueries.forEach((key) => {
+					queryClient.invalidateQueries({ queryKey: key });
+				});
 			};
-			if (withTransition && invalidateQueries.length > 0) startTransition(invalidate);
+			if (invalidateQueries.length > 0 && (config.shouldInvalidate?.(data) ?? true)) if (withTransition) startTransition(invalidate);
 			else invalidate();
 			if (toast && (config.shouldToast?.() ?? true)) showToast("success", messages, data, variables, void 0, instanceToast);
 			onSuccess?.(data, variables);
@@ -121,12 +123,16 @@ function useMutationWithOptimistic(config) {
 			return { previous };
 		},
 		onSuccess: (data, variables) => {
-			queryKeys.forEach((key) => queryClient.invalidateQueries({ queryKey: key }));
+			queryKeys.forEach((key) => {
+				queryClient.invalidateQueries({ queryKey: key });
+			});
 			if (toast) showToast("success", messages, data, variables, void 0, instanceToast);
 			onSuccess?.(data, variables);
 		},
 		onError: (error, variables, context) => {
-			context?.previous?.forEach(({ key, data }) => queryClient.setQueryData(key, data));
+			context?.previous?.forEach(({ key, data }) => {
+				queryClient.setQueryData(key, data);
+			});
 			if (toast) showToast("error", messages, null, variables, error, instanceToast);
 			onError?.(error, variables);
 		},
@@ -146,9 +152,15 @@ function useMutationWithOptimistic(config) {
 	};
 }
 function useOptimisticMutation(config) {
-	const { mutationFn, queryClient, queryKeys, optimisticUpdate, onSuccess, onError, onSettled, messages, toastHandler: instanceToast } = config;
+	const { mutationFn, queryClient, queryKeys, optimisticUpdate, mutationKey, reconcile, onSuccess, onError, onSettled, messages, toastHandler: instanceToast } = config;
+	const invalidateAll = () => {
+		queryKeys.forEach((key) => {
+			queryClient.invalidateQueries({ queryKey: key });
+		});
+	};
 	return useMutation({
 		mutationFn,
+		...mutationKey ? { mutationKey } : {},
 		onMutate: async (variables) => {
 			await Promise.all(queryKeys.map((key) => queryClient.cancelQueries({
 				queryKey: key,
@@ -160,24 +172,29 @@ function useOptimisticMutation(config) {
 			}));
 			if (optimisticUpdate) queryKeys.forEach((key) => {
 				queryClient.getQueriesData({ queryKey: key }).forEach(([qKey, qData]) => {
-					queryClient.setQueryData(qKey, optimisticUpdate(qData, variables));
+					const next = optimisticUpdate(qData, variables, qKey);
+					if (next !== qData) queryClient.setQueryData(qKey, next);
 				});
 			});
 			return { previous };
 		},
 		onSuccess: (data, variables) => {
 			if ((config.shouldToast?.() ?? true) && messages?.success) showToast("success", messages, data, variables, void 0, instanceToast);
-			queryKeys.forEach((key) => queryClient.invalidateQueries({ queryKey: key }));
+			reconcile?.(data, variables);
+			if (!mutationKey) invalidateAll();
 			onSuccess?.(data, variables);
 		},
 		onError: (error, variables, context) => {
 			context?.previous?.forEach(({ data }) => {
-				data.forEach(([qKey, qData]) => queryClient.setQueryData(qKey, qData));
+				data.forEach(([qKey, qData]) => {
+					queryClient.setQueryData(qKey, qData);
+				});
 			});
 			if (config.shouldToast?.() ?? true) showToast("error", messages, null, variables, error, instanceToast);
 			onError?.(error, variables);
 		},
 		onSettled: (data, error, variables) => {
+			if (mutationKey && queryClient.isMutating({ mutationKey }) === 1) invalidateAll();
 			onSettled?.(data, error, variables);
 		}
 	});

package/dist/prefetch.d.ts

@@ -1,6 +1,5 @@
 import { EntityReadApi } from "./query-options.js";
 import { HydrationBoundary, InfiniteData, QueryClient, dehydrate } from "@tanstack/react-query";
-
 //#region src/prefetch.d.ts
 interface PrefetchAuthContext {
   /** Auth token for protected endpoints. Required for bearer/header auth on server. */

package/dist/presets/bulk.d.ts

@@ -1,6 +1,5 @@
 import { AnyBaseApi, CreateOf, DocOf, ScopedArgs, UpdateOf } from "../api.js";
 import { BulkCreateResult, DeleteManyResult, UpdateManyResult } from "@classytic/repo-core/repository";
-
 //#region src/presets/bulk.d.ts
 interface BulkMethods<TDoc, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>> {
   /** Insert many docs in one round-trip. Backend mounts `POST /:resource/bulk`. */

package/dist/presets/history.d.ts

@@ -1,12 +1,11 @@
 import { AnyBaseApi, ScopedArgs } from "../api.js";
-
 //#region src/presets/history.d.ts
 /** One audit-trail entry — arc's `AuditEntry` wire shape for a single record. */
 interface HistoryEntry {
   id: string;
   resource: string;
   documentId: string;
-  action: 'create' | 'update' | 'delete' | 'restore' | 'custom';
+  action: "create" | "update" | "delete" | "restore" | "custom";
   userId?: string;
   organizationId?: string;
   before?: Record<string, unknown>;

package/dist/presets/search.d.ts

@@ -1,6 +1,5 @@
 import { AnyBaseApi, DocOf, ScopedArgs } from "../api.js";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
-
 //#region src/presets/search.d.ts
 interface SearchPresetMethods<TDoc> {
   /**
@@ -8,8 +7,11 @@ interface SearchPresetMethods<TDoc> {
    * Backend mounts `POST /:resource/search` via `searchPreset()`.
    */
   searchEngine<TResult = TDoc, TBody extends Record<string, unknown> = Record<string, unknown>>(args?: ScopedArgs & {
-    /** Free-text query forwarded as `body.query`. */query?: string; /** Engine-specific options merged into the request body. */
-    body?: TBody; /** Override path (default `/search`). */
+    /** Free-text query forwarded as `body.query`. */
+    query?: string;
+    /** Engine-specific options merged into the request body. */
+    body?: TBody;
+    /** Override path (default `/search`). */
     path?: string;
   }): Promise<TResult[] | PaginatedResult<TResult>>;
   /**
@@ -17,9 +19,13 @@ interface SearchPresetMethods<TDoc> {
    * Backend mounts `POST /:resource/search-similar`.
    */
   searchSimilar<TResult = TDoc, TBody extends Record<string, unknown> = Record<string, unknown>>(args?: ScopedArgs & {
-    /** Text query — backend embeds and searches for nearest neighbors. */query?: string; /** Pre-computed embedding vector — used directly for similarity search. */
-    vector?: number[]; /** Vector-engine options (`topK`, `filter`, `index`, ...). */
-    body?: TBody; /** Override path (default `/search-similar`). */
+    /** Text query — backend embeds and searches for nearest neighbors. */
+    query?: string;
+    /** Pre-computed embedding vector — used directly for similarity search. */
+    vector?: number[];
+    /** Vector-engine options (`topK`, `filter`, `index`, ...). */
+    body?: TBody;
+    /** Override path (default `/search-similar`). */
     path?: string;
   }): Promise<TResult[]>;
   /**
@@ -27,8 +33,11 @@ interface SearchPresetMethods<TDoc> {
    * Backend mounts `POST /:resource/embed`.
    */
   embed(args: ScopedArgs & {
-    /** Text or array of texts to embed. */input: string | string[]; /** Embed-engine options (`model`, `dimensions`, ...). */
-    body?: Record<string, unknown>; /** Override path (default `/embed`). */
+    /** Text or array of texts to embed. */
+    input: string | string[];
+    /** Embed-engine options (`model`, `dimensions`, ...). */
+    body?: Record<string, unknown>;
+    /** Override path (default `/embed`). */
     path?: string;
   }): Promise<number[] | number[][]>;
 }

package/dist/presets/slug.d.ts

@@ -1,5 +1,4 @@
 import { AnyBaseApi, DocOf, ScopedArgs } from "../api.js";
-
 //#region src/presets/slug.d.ts
 interface SlugLookupMethods<TDoc> {
   /** Fetch a single doc by slug. Backend mounts `GET /:resource/slug/:slug`. */

package/dist/presets/soft-delete.d.ts

@@ -1,6 +1,5 @@
 import { AnyBaseApi, DocOf, QueryParams, ScopedArgs } from "../api.js";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
-
 //#region src/presets/soft-delete.d.ts
 interface SoftDeleteMethods<TDoc> {
   /** List soft-deleted docs. Backend mounts `GET /:resource/deleted`. */

package/dist/presets/tree.d.ts

@@ -1,6 +1,5 @@
 import { AnyBaseApi, DocOf, QueryParams, ScopedArgs } from "../api.js";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
-
 //#region src/presets/tree.d.ts
 interface TreeMethods<TDoc> {
   /** Fetch the full hierarchy. Backend mounts `GET /:resource/tree`. */

package/dist/query-client.d.ts

@@ -1,5 +1,4 @@
 import { QueryClient } from "@tanstack/react-query";
-
 //#region src/query-client.d.ts
 interface QueryClientOverrides {
   staleTime?: number;