@classytic/arc-next 0.11.0 → 0.12.0

package/dist/mutation.d.ts

@@ -3,9 +3,16 @@ import * as _$_tanstack_react_query0 from "@tanstack/react-query";
 import { QueryClient, QueryKey, UseMutateAsyncFunction, UseMutateFunction } from "@tanstack/react-query";
 
 //#region src/mutation.d.ts
-interface MutationMessages {
-  success?: string | ((data: unknown, variables: unknown) => string);
-  error?: string | ((error: Error, variables: unknown) => string);
+/**
+ * Toast copy for a mutation. Generic over the mutation's result/variables so
+ * `success: (result) => ...` sees the TYPED FLAT action result (arc 2.13+
+ * returns results with no `{ data }` envelope) — the stale-envelope
+ * `(data as { data: T }).data` cast class is a compile error now. Defaults
+ * keep pre-0.11.1 unparameterized usage compiling unchanged.
+ */
+interface MutationMessages<TData = unknown, TVariables = unknown> {
+  success?: string | ((data: TData, variables: TVariables) => string);
+  error?: string | ((error: Error, variables: TVariables) => string);
 }
 interface MutationCallbacks<TData, TVariables, TContext = unknown> {
   onMutate?: (variables: TVariables) => TContext | Promise<TContext>;
@@ -53,10 +60,17 @@ 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;
-  messages?: MutationMessages;
+  messages?: MutationMessages<TData, TVariables>;
   useTransition?: boolean;
   showToast?: boolean;
   /** Per-call toast guard — return false to suppress toast for this invocation */
@@ -80,7 +94,7 @@ interface OptimisticMutationConfig<TData, TVariables> {
   onSuccess?: (data: TData, variables: TVariables) => void;
   onError?: (error: Error, variables: TVariables) => void;
   onSettled?: (data: TData | undefined, error: Error | null, variables: TVariables) => void;
-  messages?: MutationMessages;
+  messages?: MutationMessages<TData, TVariables>;
   showToast?: boolean;
   toastHandler?: ToastHandler;
 }
@@ -108,11 +122,32 @@ 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;
-  messages?: MutationMessages;
+  messages?: MutationMessages<TData, TVariables>;
   /** Per-call toast guard — return false to suppress toast for this invocation */
   shouldToast?: () => boolean;
   toastHandler?: ToastHandler;

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/presets/history.d.ts

@@ -6,7 +6,7 @@ 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/query.d.ts

@@ -286,7 +286,7 @@ interface UseApiQueryOptions {
   refetchIntervalInBackground?: boolean;
   retry?: boolean | number;
   /** Limit re-renders to changes in these specific fields (perf optimization). */
-  notifyOnChangeProps?: ('data' | 'error' | 'isLoading' | 'isFetching' | 'isError' | 'isSuccess' | 'isStale')[];
+  notifyOnChangeProps?: ("data" | "error" | "isLoading" | "isFetching" | "isError" | "isSuccess" | "isStale")[];
 }
 interface UseApiQueryConfig<TResponse, TData> {
   queryKey: QueryKey;

package/dist/sse.js

@@ -166,7 +166,7 @@ function subscribeToEvents(options) {
 	const scheduleReconnect = () => {
 		if (reconnectAttempts < maxReconnectAttempts) {
 			reconnectAttempts += 1;
-			const delay = Math.min(reconnectDelay * Math.pow(1.5, reconnectAttempts - 1), 3e4);
+			const delay = Math.min(reconnectDelay * 1.5 ** (reconnectAttempts - 1), 3e4);
 			reconnectTimer = setTimeout(connect, delay);
 		}
 	};

package/dist/upload.d.ts

@@ -71,6 +71,15 @@ interface UploadWithProgressOptions {
    * an image and returns the resized binary). Default: false (parse JSON).
    */
   responseType?: "json" | "text" | "blob";
+  /**
+   * Upload timeout in ms, assigned to `xhr.timeout` — the whole request
+   * (upload + server processing + response) must finish within this window
+   * or the promise rejects with a `TimeoutError`. Default: disabled (0) —
+   * large files on slow links legitimately take minutes; size it to your
+   * payload ceiling when you enable it. (`ClientConfig.timeoutMs` does NOT
+   * apply to uploads — the fetch pipeline and XHR transport stay isolated.)
+   */
+  timeoutMs?: number;
 }
 /**
  * Upload a `FormData` payload via XHR with native progress events.

package/dist/upload.js

@@ -1,3 +1,5 @@
+"use client";
+
 import { ArcApiError, _getAuthErrorHandler, _isAuthRecoverable, _resolveRefreshedToken, _runAuthRecovery, getAuthMode, getBaseUrl, getClientAuthContext } from "./client.js";
 import { getToastHandler } from "./mutation.js";
 import { useQueryClient } from "@tanstack/react-query";
@@ -110,7 +112,7 @@ async function uploadWithProgress(options) {
 * in the outer loop; this function just performs one upload.
 */
 function uploadAttempt(options) {
-	const { url, formData, method = "POST", onProgress, signal, client, headers: extraHeaders, elevated, idempotencyKey, responseType = "json" } = options;
+	const { url, formData, method = "POST", onProgress, signal, client, headers: extraHeaders, elevated, idempotencyKey, responseType = "json", timeoutMs = 0 } = options;
 	return new Promise((resolve, reject) => {
 		if (signal?.aborted) {
 			reject(abortReason(signal));
@@ -119,6 +121,7 @@ function uploadAttempt(options) {
 		const xhr = new XMLHttpRequest();
 		const fullUrl = resolveUrl(url, client);
 		xhr.open(method, fullUrl, true);
+		if (timeoutMs > 0) xhr.timeout = timeoutMs;
 		xhr.responseType = responseType === "blob" ? "blob" : "";
 		const authMode = client?.config?.authMode ?? getAuthMode();
 		if (authMode === "cookie") xhr.withCredentials = true;
@@ -130,7 +133,7 @@ function uploadAttempt(options) {
 			if (authMode === "header") {
 				const headerName = client?.auth?.headerName ?? "x-api-key";
 				builtHeaders[headerName] = token;
-			} else if (authMode !== "cookie") builtHeaders["Authorization"] = `Bearer ${token}`;
+			} else if (authMode !== "cookie") builtHeaders.Authorization = `Bearer ${token}`;
 		}
 		if (orgId) builtHeaders["x-organization-id"] = orgId;
 		if (elevated ?? client?.config?.elevated) builtHeaders["x-arc-scope"] = "platform";
@@ -191,7 +194,7 @@ function uploadAttempt(options) {
 		};
 		xhr.ontimeout = () => {
 			if (abortListener && signal) signal.removeEventListener("abort", abortListener);
-			reject(/* @__PURE__ */ new Error(`Upload timed out: ${fullUrl}`));
+			reject(Object.assign(/* @__PURE__ */ new Error(`Upload timed out after ${timeoutMs}ms: ${fullUrl}`), { name: "TimeoutError" }));
 		};
 		xhr.send(formData);
 	});

package/dist/ws.d.ts

@@ -21,7 +21,7 @@ interface ArcWsMessage<TData = unknown> {
  * Backend also accepts `channel` as alias.
  */
 interface ArcSubscribeFrame {
-  type: 'subscribe' | 'unsubscribe';
+  type: "subscribe" | "unsubscribe";
   resource?: string;
   channel?: string;
   /** Free-form additional fields the backend may use (token, filters, etc.). */

package/dist/ws.js

@@ -150,7 +150,7 @@ function connectWs(options = {}) {
 			}
 			if (reconnectAttempts < maxReconnectAttempts) {
 				reconnectAttempts += 1;
-				const delay = Math.min(reconnectDelay * Math.pow(1.5, reconnectAttempts - 1), 3e4);
+				const delay = Math.min(reconnectDelay * 1.5 ** (reconnectAttempts - 1), 3e4);
 				reconnectTimer = setTimeout(connect, delay);
 			}
 		};