@classytic/arc-next 0.11.1 → 0.12.0

package/dist/client.js

@@ -1,3 +1,5 @@
+import { ERROR_CODES } from "@classytic/repo-core/errors";
+
 //#region src/client.ts
 /**
 * Canonical error codes arc and repo-core emit on `json.code`. Single
@@ -21,17 +23,7 @@
 * `errorMappers` codes still satisfy it.
 */
 const KNOWN_ARC_ERROR_CODES = [
-	"validation_error",
-	"not_found",
-	"conflict",
-	"unauthorized",
-	"forbidden",
-	"rate_limited",
-	"idempotency_conflict",
-	"precondition_failed",
-	"internal_error",
-	"service_unavailable",
-	"timeout",
+	...Object.values(ERROR_CODES),
 	"arc.bad_request",
 	"arc.unauthorized",
 	"arc.forbidden",
@@ -75,6 +67,13 @@ var ArcApiError = class extends Error {
 	json;
 	endpoint;
 	method;
+	/**
+	* Server-directed retry pacing from the `Retry-After` response header
+	* (seconds or HTTP-date form, normalized to ms). Populated on 429/503;
+	* the SDK's retry loop honors it INSTEAD of computed backoff so clients
+	* come back exactly when the server says capacity returns.
+	*/
+	retryAfterMs;
 	constructor(message, options) {
 		super(message);
 		this.name = "ArcApiError";
@@ -83,6 +82,7 @@ var ArcApiError = class extends Error {
 		this.json = options.json;
 		this.endpoint = options.endpoint;
 		this.method = options.method;
+		this.retryAfterMs = options.retryAfterMs ?? null;
 	}
 	/**
 	* Canonical error code from arc's wire envelope (`json.code`).
@@ -435,7 +435,7 @@ function isAuthRecoverable(error, retryOn403) {
 function runAuthRecovery(handler, ctx) {
 	if (pendingAuthRecovery) return pendingAuthRecovery;
 	pendingAuthRecovery = (async () => {
-		let overrideToken = void 0;
+		let overrideToken;
 		const setToken = (token) => {
 			overrideToken = token;
 		};
@@ -652,6 +652,44 @@ function createAuthAwareClient(overrides = {}) {
 	};
 }
 /**
+* Create a **request-scoped** client for server environments (Next.js App
+* Router route handlers / Server Components, or any SSR runtime).
+*
+* Unlike `configureClient`/`configureAuth` — which set module-level state
+* that leaks across concurrent server requests — this returns an isolated
+* client whose credentials live only in the returned instance. Construct one
+* per request, read cookies/headers in YOUR framework code, and pass the
+* values in. The SDK stays framework-free: no `next` dependency, no
+* `next/headers` import, no hidden cookie access.
+*
+* @example Next.js App Router (Server Component or route handler)
+* ```ts
+* import { cookies, headers } from 'next/headers';   // host code, not SDK code
+* import { createServerClient } from '@classytic/arc-next/client';
+* import { createCrudApi } from '@classytic/arc-next/api';
+*
+* export async function loadOrders() {
+*   const jar = await cookies();
+*   const client = createServerClient({
+*     baseUrl: process.env.API_URL!,
+*     token: jar.get('session')?.value ?? null,
+*     organizationId: (await headers()).get('x-organization-id'),
+*   });
+*   const orders = createCrudApi<Order>('orders', { client });
+*   // Next fetch-cache passthrough works per call:
+*   return orders.getAll({ options: { next: { revalidate: 60, tags: ['orders'] } } });
+* }
+* ```
+*/
+function createServerClient(config) {
+	const { token = null, organizationId = null, ...rest } = config;
+	return createClient({
+		...rest,
+		getToken: () => token,
+		getOrgId: () => organizationId
+	});
+}
+/**
 * Get auth context for a specific client instance, falling back to global.
 */
 function getClientAuthContext(client) {
@@ -668,11 +706,11 @@ function defaultShouldRetry(error) {
 	return error instanceof Error;
 }
 /** Compute the delay in ms before the Nth retry. */
-function computeBackoff(retry, attempt) {
+function computeBackoff(retry, attempt, error) {
+	if (isArcApiError(error) && error.retryAfterMs != null && (error.status === 429 || error.status === 503)) return error.retryAfterMs;
 	const strategy = retry.backoff ?? "exponential";
-	if (typeof strategy === "function") return Math.max(0, strategy(attempt));
-	if (strategy === "linear") return 300 * (attempt + 1);
-	return Math.min(300 * Math.pow(2, attempt), 1e4);
+	const base = typeof strategy === "function" ? Math.max(0, strategy(attempt)) : strategy === "linear" ? 300 * (attempt + 1) : Math.min(300 * 2 ** attempt, 1e4);
+	return retry.jitter === "full" ? Math.random() * base : base;
 }
 /**
 * Inner request loop — handles 5xx + network-failure backoff per
@@ -695,7 +733,7 @@ async function executeWithBackoff(config, method, endpoint, options = {}) {
 	} catch (error) {
 		lastError = error;
 		if (attempt === totalAttempts - 1 || !shouldRetry(error)) throw error;
-		const delay = computeBackoff(config.retry ?? {}, attempt);
+		const delay = computeBackoff(config.retry ?? {}, attempt, error);
 		if (delay > 0) await sleepAbortable(delay, options.signal);
 	}
 	throw lastError;
@@ -714,6 +752,10 @@ async function executeWithBackoff(config, method, endpoint, options = {}) {
 * surfaces immediately, no extra round-trip).
 */
 async function executeRequest(config, method, endpoint, options = {}) {
+	if (config.autoIdempotency && options.idempotencyKey === void 0 && (method === "POST" || method === "PUT" || method === "PATCH")) options = {
+		...options,
+		idempotencyKey: globalThis.crypto.randomUUID()
+	};
 	const handler = authConfig?.onAuthError;
 	if (!handler) return executeWithBackoff(config, method, endpoint, options);
 	const retryOn403 = authConfig?.retryOn403 ?? false;
@@ -741,6 +783,15 @@ async function executeRequest(config, method, endpoint, options = {}) {
 	}
 	throw new Error("arc-next: auth retry loop terminated without resolution");
 }
+/** Parse `Retry-After` (delta-seconds or HTTP-date) to ms; null when absent/invalid. */
+function parseRetryAfterMs(header) {
+	if (!header) return null;
+	const seconds = Number(header);
+	if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1e3);
+	const date = Date.parse(header);
+	if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+	return null;
+}
 /** Sleep that resolves early if the signal aborts. */
 function sleepAbortable(ms, signal) {
 	return new Promise((resolve, reject) => {
@@ -759,9 +810,42 @@ function sleepAbortable(ms, signal) {
 		signal?.addEventListener("abort", onAbort, { once: true });
 	});
 }
+/**
+* Compose the caller's AbortSignal with a per-attempt timeout. Returns the
+* effective signal plus a `timedOut()` probe so the catch path can tell a
+* timeout abort (retryable failure) apart from a deliberate caller abort
+* (silent cancellation).
+*/
+function withTimeoutSignal(signal, timeoutMs) {
+	if (!(timeoutMs > 0)) return {
+		signal,
+		timedOut: () => false,
+		cleanup: () => {}
+	};
+	const controller = new AbortController();
+	let timedOut = false;
+	const onCallerAbort = () => controller.abort();
+	if (signal) if (signal.aborted) controller.abort();
+	else signal.addEventListener("abort", onCallerAbort, { once: true });
+	const timer = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, timeoutMs);
+	return {
+		signal: controller.signal,
+		timedOut: () => timedOut,
+		cleanup: () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onCallerAbort);
+		}
+	};
+}
 /** A single fetch attempt — used by executeRequest's retry loop. */
 async function executeAttempt(config, method, endpoint, options, attempt) {
-	const { body, token, organizationId, revalidate, headerOptions, tags, next, cache, signal, idempotencyKey, elevated } = options;
+	const { body, token, organizationId, revalidate, headerOptions, tags, next, cache, signal: callerSignal, idempotencyKey, elevated } = options;
+	const timeoutMs = options.timeoutMs ?? config.timeoutMs ?? 0;
+	const timeout = withTimeoutSignal(callerSignal, timeoutMs);
+	const signal = timeout.signal;
 	const startTime = Date.now();
 	try {
 		let headers = {
@@ -773,7 +857,7 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 			if (config.authMode === "header") {
 				const headerName = authConfig?.headerName ?? "x-api-key";
 				headers[headerName] = token;
-			} else if (config.authMode !== "cookie") headers["Authorization"] = `Bearer ${token}`;
+			} else if (config.authMode !== "cookie") headers.Authorization = `Bearer ${token}`;
 		}
 		if (config.apiVersion) headers["Accept-Version"] = config.apiVersion;
 		if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
@@ -784,7 +868,7 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 			...headerOptions
 		};
 		const credentials = config.credentials ?? (config.authMode === "cookie" ? "include" : "same-origin");
-		let serializedBody = void 0;
+		let serializedBody;
 		if (body !== void 0 && body !== null) serializedBody = isNonJsonBody(body) ? body : JSON.stringify(body);
 		const encryption = config.encryption;
 		if (encryption?.encryptRequests && encryption.encrypt && typeof serializedBody === "string") {
@@ -838,7 +922,8 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 				statusText: response.statusText,
 				json,
 				endpoint,
-				method
+				method,
+				retryAfterMs: parseRetryAfterMs(response.headers.get("Retry-After"))
 			});
 		}
 		const contentType = response.headers.get("Content-Type");
@@ -886,8 +971,11 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 		})).body;
 		return data;
 	} catch (error) {
+		if (timeout.timedOut() && isAbortError(error)) throw Object.assign(/* @__PURE__ */ new Error(`[arc-next] Request timed out after ${timeoutMs}ms: ${method} ${endpoint}`), { name: "TimeoutError" });
 		if (error instanceof Error) throw error;
 		throw new Error("An error occurred while fetching data.");
+	} finally {
+		timeout.cleanup();
 	}
 }
 /**
@@ -1139,4 +1227,4 @@ const arc = {
 };
 
 //#endregion
-export { ArcApiError, KNOWN_ARC_ERROR_CODES, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isValidationError };
+export { ArcApiError, KNOWN_ARC_ERROR_CODES, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, createServerClient, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isValidationError };

package/dist/encryption.d.ts

@@ -31,6 +31,6 @@ interface JoseEncryptionOptions {
  * using `jose`. Spread the result into `encryption` and add `encryptRequests`
  * / content-type overrides as needed.
  */
-declare function createJoseEncryption(options: JoseEncryptionOptions): Pick<ClientEncryptionConfig, 'encrypt' | 'decrypt'>;
+declare function createJoseEncryption(options: JoseEncryptionOptions): Pick<ClientEncryptionConfig, "encrypt" | "decrypt">;
 //#endregion
 export { JoseEncryptionOptions, createJoseEncryption };

package/dist/hooks.d.ts

@@ -2,12 +2,12 @@ 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";
 
@@ -22,11 +22,11 @@ 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>> {
@@ -335,12 +335,12 @@ 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`. */
+    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. */

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

@@ -60,6 +60,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 +122,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;