@classytic/arc-next 0.2.1 → 0.4.0

package/dist/mutation.d.ts

@@ -1,5 +1,6 @@
 import { ToastHandler } from "./client.js";
-import * as _tanstack_react_query0 from "@tanstack/react-query";
+import { QUERY_CONFIGS } from "./query.js";
+import * as _$_tanstack_react_query0 from "@tanstack/react-query";
 import { QueryClient, QueryKey, UseMutateAsyncFunction, UseMutateFunction } from "@tanstack/react-query";
 
 //#region src/mutation.d.ts
@@ -26,6 +27,8 @@ interface TransitionMutationReturn<TData, TVariables> {
 /**
  * Configure toast handler. Call once at app init.
  *
+ * **SSR safety:** This sets module-level state. Call only in client-side code.
+ *
  * @example
  * import { toast } from "sonner";
  * configureToast({ success: toast.success, error: toast.error });
@@ -45,8 +48,8 @@ interface TransitionMutationConfig<TData, TVariables> {
   toastHandler?: ToastHandler;
 }
 declare function useMutationWithTransition<TData, TVariables>(config: TransitionMutationConfig<TData, TVariables>): {
-  mutate: UseMutateFunction<TData, Error, TVariables, unknown>;
-  mutateAsync: UseMutateAsyncFunction<TData, Error, TVariables, unknown>;
+  mutate: UseMutateFunction<TData, Error, TVariables, void>;
+  mutateAsync: UseMutateAsyncFunction<TData, Error, TVariables, void>;
   isPending: boolean;
   isSuccess: boolean;
   isError: boolean;
@@ -98,27 +101,13 @@ interface CreateOptimisticMutationConfig<TData, TVariables> {
   shouldToast?: () => boolean;
   toastHandler?: ToastHandler;
 }
-declare function createOptimisticMutation<TData, TVariables>(config: CreateOptimisticMutationConfig<TData, TVariables>): _tanstack_react_query0.UseMutationResult<TData, Error, TVariables, {
+declare function useOptimisticMutation<TData, TVariables>(config: CreateOptimisticMutationConfig<TData, TVariables>): _$_tanstack_react_query0.UseMutationResult<TData, Error, TVariables, {
   previous: {
     key: readonly unknown[];
     data: [readonly unknown[], unknown][];
   }[];
 }>;
-declare const QUERY_CONFIGS: {
-  readonly realtime: {
-    readonly staleTime: 20000;
-    readonly refetchInterval: 30000;
-  };
-  readonly frequent: {
-    readonly staleTime: 60000;
-  };
-  readonly stable: {
-    readonly staleTime: 300000;
-  };
-  readonly static: {
-    readonly staleTime: 600000;
-  };
-};
+/** @deprecated Use `useOptimisticMutation` */
+declare const createOptimisticMutation: typeof useOptimisticMutation;
 //#endregion
-export { CreateOptimisticMutationConfig, MutationCallbacks, MutationMessages, OptimisticMutationConfig, QUERY_CONFIGS, type ToastHandler, TransitionMutationConfig, TransitionMutationReturn, configureToast, createOptimisticMutation, useMutationWithOptimistic, useMutationWithTransition };
-//# sourceMappingURL=mutation.d.ts.map
+export { CreateOptimisticMutationConfig, MutationCallbacks, MutationMessages, OptimisticMutationConfig, QUERY_CONFIGS, TransitionMutationConfig, TransitionMutationReturn, configureToast, createOptimisticMutation, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };

package/dist/mutation.js

@@ -1,8 +1,9 @@
 "use client";
 
-import { isArcApiError } from "./client.js";
+import { isArcApiError, isAutoIdempotency } from "./client.js";
+import { QUERY_CONFIGS } from "./query.js";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { useTransition } from "react";
+import { useCallback, useRef, useTransition } from "react";
 
 //#region src/mutation.ts
 let toastHandler = {
@@ -12,6 +13,8 @@ let toastHandler = {
 /**
 * Configure toast handler. Call once at app init.
 *
+* **SSR safety:** This sets module-level state. Call only in client-side code.
+*
 * @example
 * import { toast } from "sonner";
 * configureToast({ success: toast.success, error: toast.error });
@@ -41,8 +44,18 @@ function useMutationWithTransition(config) {
 	const { mutationFn, invalidateQueries = [], onSuccess, onError, onSettled, messages, useTransition: withTransition = true, showToast: toast = true, toastHandler: instanceToast } = config;
 	const queryClient = useQueryClient();
 	const [isTransitioning, startTransition] = useTransition();
+	const idempotencyKeyRef = useRef(null);
 	const mutation = useMutation({
-		mutationFn,
+		mutationFn: (variables) => {
+			if (idempotencyKeyRef.current && typeof variables === "object" && variables !== null) {
+				const vars = variables;
+				if (vars.options && typeof vars.options === "object") vars.options.idempotencyKey ??= idempotencyKeyRef.current;
+			}
+			return mutationFn(variables);
+		},
+		onMutate: () => {
+			idempotencyKeyRef.current = isAutoIdempotency() ? globalThis.crypto.randomUUID() : null;
+		},
 		onSuccess: (data, variables) => {
 			const invalidate = () => {
 				invalidateQueries.forEach((key) => queryClient.invalidateQueries({ queryKey: key }));
@@ -112,7 +125,7 @@ function useMutationWithOptimistic(config) {
 		reset: mutation.reset
 	};
 }
-function createOptimisticMutation(config) {
+function useOptimisticMutation(config) {
 	const { mutationFn, queryClient, queryKeys, optimisticUpdate, onSuccess, onError, onSettled, messages, toastHandler: instanceToast } = config;
 	return useMutation({
 		mutationFn,
@@ -149,16 +162,8 @@ function createOptimisticMutation(config) {
 		}
 	});
 }
-const QUERY_CONFIGS = {
-	realtime: {
-		staleTime: 2e4,
-		refetchInterval: 3e4
-	},
-	frequent: { staleTime: 6e4 },
-	stable: { staleTime: 3e5 },
-	static: { staleTime: 6e5 }
-};
+/** @deprecated Use `useOptimisticMutation` */
+const createOptimisticMutation = useOptimisticMutation;
 
 //#endregion
-export { QUERY_CONFIGS, configureToast, createOptimisticMutation, useMutationWithOptimistic, useMutationWithTransition };
-//# sourceMappingURL=mutation.js.map
+export { QUERY_CONFIGS, configureToast, createOptimisticMutation, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };

package/dist/prefetch.d.ts

@@ -4,6 +4,13 @@ import { QueryClient, dehydrate } from "@tanstack/react-query";
 interface PrefetchOptions {
   staleTime?: number;
 }
+interface PrefetchDetailOptions extends PrefetchOptions {
+  /** Query params (select, populate) — key must match useDetail's params to share cache */
+  params?: {
+    select?: string;
+    populate?: string | string[];
+  };
+}
 interface CrudPrefetcher {
   /**
    * Prefetch a list query on the server. Uses the same query keys as useList.
@@ -20,7 +27,22 @@ interface CrudPrefetcher {
    * const queryClient = getQueryClient();
    * await productsPrefetcher.prefetchDetail(queryClient, productId);
    */
-  prefetchDetail: (queryClient: QueryClient, id: string, options?: PrefetchOptions) => Promise<void>;
+  prefetchDetail: (queryClient: QueryClient, id: string, options?: PrefetchDetailOptions) => Promise<void>;
+  /**
+   * Prefetch a detail-by-slug query. Uses the same query keys as useDetailBySlug.
+   * Only available when the API has a `getBySlug` method (slugLookup preset).
+   */
+  prefetchBySlug: (queryClient: QueryClient, slug: string, options?: PrefetchDetailOptions) => Promise<void>;
+  /**
+   * Prefetch soft-deleted items. Uses the same query keys as useDeleted.
+   * Only available when the API has a `getDeleted` method (softDelete preset).
+   */
+  prefetchDeleted: (queryClient: QueryClient, params?: Record<string, unknown>, options?: PrefetchOptions) => Promise<void>;
+  /**
+   * Prefetch a tree query. Uses the same query keys as useTree.
+   * Only available when the API has a `getTree` method (tree preset).
+   */
+  prefetchTree: (queryClient: QueryClient, params?: Record<string, unknown>, options?: PrefetchOptions) => Promise<void>;
 }
 /**
  * Create server-safe prefetch helpers for CRUD queries.
@@ -58,7 +80,22 @@ declare function createCrudPrefetcher(api: {
     token?: string | null;
     organizationId?: string | null;
   }) => Promise<unknown>;
+  getBySlug?: (opts: {
+    slug: string;
+    token?: string | null;
+    organizationId?: string | null;
+    params?: Record<string, unknown>;
+  }) => Promise<unknown>;
+  getDeleted?: (opts: {
+    params?: Record<string, unknown>;
+    token?: string | null;
+    organizationId?: string | null;
+  }) => Promise<unknown>;
+  getTree?: (opts: {
+    params?: Record<string, unknown>;
+    token?: string | null;
+    organizationId?: string | null;
+  }) => Promise<unknown>;
 }, entityKey: string): CrudPrefetcher;
 //#endregion
-export { CrudPrefetcher, PrefetchOptions, createCrudPrefetcher, dehydrate };
-//# sourceMappingURL=prefetch.d.ts.map
+export { CrudPrefetcher, PrefetchDetailOptions, PrefetchOptions, createCrudPrefetcher, dehydrate };

package/dist/prefetch.js

@@ -1,23 +1,7 @@
+import { createQueryKeys } from "./query.js";
 import { dehydrate } from "@tanstack/react-query";
 
 //#region src/prefetch.ts
-function scopedListKey(entityKey, scope, params) {
-	return [
-		entityKey,
-		"list",
-		{
-			_scope: scope,
-			...params || {}
-		}
-	];
-}
-function detailKey(entityKey, id) {
-	return [
-		entityKey,
-		"detail",
-		id
-	];
-}
 /**
 * Create server-safe prefetch helpers for CRUD queries.
 * Use in Next.js server components to pre-populate the query cache before rendering.
@@ -44,10 +28,12 @@ function detailKey(entityKey, id) {
 * }
 */
 function createCrudPrefetcher(api, entityKey) {
+	const KEYS = createQueryKeys(entityKey);
 	return {
 		async prefetchList(queryClient, params = {}, options = {}) {
 			const { organizationId, ...restParams } = params;
-			const queryKey = scopedListKey(entityKey, organizationId ? "tenant" : "super-admin", {
+			const scope = organizationId ? "tenant" : "super-admin";
+			const queryKey = KEYS.scopedList(scope, {
 				organizationId,
 				...restParams
 			});
@@ -61,10 +47,60 @@ function createCrudPrefetcher(api, entityKey) {
 			});
 		},
 		async prefetchDetail(queryClient, id, options = {}) {
-			const queryKey = detailKey(entityKey, id);
+			const { params, staleTime } = options;
+			const baseKey = KEYS.detail(id);
+			const queryKey = params ? [...baseKey, params] : baseKey;
+			await queryClient.prefetchQuery({
+				queryKey,
+				queryFn: () => api.getById({
+					id,
+					...params ? { params } : {}
+				}),
+				staleTime
+			});
+		},
+		async prefetchBySlug(queryClient, slug, options = {}) {
+			if (!api.getBySlug) throw new Error(`[arc-next] prefetchBySlug requires an api with getBySlug (slugLookup preset)`);
+			const { params, staleTime } = options;
+			const queryKey = params ? KEYS.custom("slug", slug, params) : KEYS.custom("slug", slug);
+			await queryClient.prefetchQuery({
+				queryKey,
+				queryFn: () => api.getBySlug({
+					slug,
+					...params ? { params } : {}
+				}),
+				staleTime
+			});
+		},
+		async prefetchDeleted(queryClient, params = {}, options = {}) {
+			if (!api.getDeleted) throw new Error(`[arc-next] prefetchDeleted requires an api with getDeleted (softDelete preset)`);
+			const { organizationId, ...restParams } = params;
+			const queryKey = KEYS.custom("deleted", {
+				organizationId,
+				...restParams
+			});
+			await queryClient.prefetchQuery({
+				queryKey,
+				queryFn: () => api.getDeleted({
+					params: restParams,
+					organizationId: organizationId ?? null
+				}),
+				staleTime: options.staleTime
+			});
+		},
+		async prefetchTree(queryClient, params = {}, options = {}) {
+			if (!api.getTree) throw new Error(`[arc-next] prefetchTree requires an api with getTree (tree preset)`);
+			const { organizationId, ...restParams } = params;
+			const queryKey = KEYS.custom("tree", {
+				organizationId,
+				...restParams
+			});
 			await queryClient.prefetchQuery({
 				queryKey,
-				queryFn: () => api.getById({ id }),
+				queryFn: () => api.getTree({
+					params: restParams,
+					organizationId: organizationId ?? null
+				}),
 				staleTime: options.staleTime
 			});
 		}
@@ -72,5 +108,4 @@ function createCrudPrefetcher(api, entityKey) {
 }
 
 //#endregion
-export { createCrudPrefetcher, dehydrate };
-//# sourceMappingURL=prefetch.js.map
+export { createCrudPrefetcher, dehydrate };

package/dist/query-client.d.ts

@@ -21,5 +21,4 @@ interface QueryClientOverrides {
  */
 declare function getQueryClient(overrides?: QueryClientOverrides): QueryClient;
 //#endregion
-export { QueryClientOverrides, getQueryClient };
-//# sourceMappingURL=query-client.d.ts.map
+export { QueryClientOverrides, getQueryClient };

package/dist/query-client.js

@@ -38,9 +38,9 @@ let browserQueryClient;
 function getQueryClient(overrides) {
 	if (isServer) return makeQueryClient(overrides);
 	if (!browserQueryClient) browserQueryClient = makeQueryClient(overrides);
+	else if (overrides) console.warn("[arc-next] getQueryClient(): Browser singleton already exists — overrides are ignored. Pass overrides only on the first call.");
 	return browserQueryClient;
 }
 
 //#endregion
-export { getQueryClient };
-//# sourceMappingURL=query-client.js.map
+export { getQueryClient };

package/dist/query.d.ts

@@ -2,12 +2,16 @@ import { InfiniteData, QueryClient, QueryKey } from "@tanstack/react-query";
 
 //#region src/query.d.ts
 interface PaginationData {
+  /** Pagination method detected from response (offset | keyset | aggregate) */
+  method: 'offset' | 'keyset' | 'aggregate' | null;
   total: number;
   pages: number;
   page: number;
   limit: number;
   hasNext: boolean;
   hasPrev: boolean;
+  /** Keyset cursor for next page (keyset pagination only) */
+  next?: string | null;
 }
 /** Request-level options passed through to the fetch call */
 interface RequestPassthrough {
@@ -39,6 +43,7 @@ interface DetailQueryOptions<TData = unknown> {
   enabled?: boolean;
   staleTime?: number;
   gcTime?: number;
+  refetchOnWindowFocus?: boolean;
   structuralSharing?: boolean;
   refetchInterval?: number | false;
   refetchIntervalInBackground?: boolean;
@@ -98,7 +103,24 @@ declare const DEFAULT_QUERY_CONFIG: {
   readonly refetchOnWindowFocus: false;
   readonly retry: 0;
 };
+/** Pre-built query config presets for common data freshness patterns. */
+declare const QUERY_CONFIGS: {
+  /** Live data: 20s stale, 30s polling */readonly realtime: {
+    readonly staleTime: 20000;
+    readonly refetchInterval: 30000;
+  }; /** Frequently updated: 60s stale */
+  readonly frequent: {
+    readonly staleTime: 60000;
+  }; /** Stable data: 5min stale (same as default) */
+  readonly stable: {
+    readonly staleTime: 300000;
+  }; /** Rarely changes: 10min stale */
+  readonly static: {
+    readonly staleTime: 600000;
+  };
+};
 declare function getItemId(item: unknown): string | null;
+declare function extractItem<T>(data: unknown): T | null;
 declare function updateListCache<T>(listData: unknown, updater: (items: T[]) => T[]): unknown;
 declare function createQueryKeys(entityKey: string): QueryKeys;
 declare function createCacheUtils<T>(KEYS: QueryKeys): CacheUtils<T>;
@@ -111,15 +133,18 @@ interface CreateListQueryConfig {
   options?: Record<string, unknown>;
   prefillDetailCache?: boolean;
   detailKeyBuilder?: (id: string) => QueryKey;
+  /** Custom ID extractor for cache prefill. Falls back to getItemId (_id → id). */
+  itemIdResolver?: (item: unknown) => string | null;
   select?: (data: unknown) => unknown;
 }
-declare function createListQuery<T>({
+declare function useListQuery<T>({
   queryKey,
   queryFn,
   enabled,
   options,
   prefillDetailCache,
   detailKeyBuilder,
+  itemIdResolver,
   select
 }: CreateListQueryConfig): ListQueryResult<T>;
 interface CreateDetailQueryConfig {
@@ -131,7 +156,7 @@ interface CreateDetailQueryConfig {
   options?: Record<string, unknown>;
   select?: (data: unknown) => unknown;
 }
-declare function createDetailQuery<T>({
+declare function useDetailQuery<T>({
   queryKey,
   queryFn,
   enabled,
@@ -145,8 +170,16 @@ interface InfiniteListQueryOptions {
   gcTime?: number;
   refetchOnWindowFocus?: boolean;
   structuralSharing?: boolean;
+  refetchInterval?: number | false;
+  refetchIntervalInBackground?: boolean;
   _scope?: string;
   request?: RequestPassthrough;
+  /**
+   * Max pages to keep in memory. Old pages are evicted and re-fetched on scroll-back.
+   * Requires `getPreviousPageParam` for backward re-fetching.
+   * When unset, all fetched pages are retained (default TanStack Query behavior).
+   */
+  maxPages?: number;
 }
 interface InfiniteListQueryResult<T> {
   items: T[];
@@ -175,16 +208,24 @@ interface CreateInfiniteListQueryConfig {
   initialPageParam?: unknown;
   getNextPageParam: (lastPage: unknown) => unknown;
   getPreviousPageParam?: (firstPage: unknown) => unknown;
+  /** Max pages to keep in memory. Old pages are evicted when exceeded. */
+  maxPages?: number;
 }
-declare function createInfiniteListQuery<T>({
+declare function useInfiniteListQuery<T>({
   queryKey,
   queryFn,
   enabled,
   options,
   initialPageParam,
   getNextPageParam,
-  getPreviousPageParam
+  getPreviousPageParam,
+  maxPages
 }: CreateInfiniteListQueryConfig): InfiniteListQueryResult<T>;
+/** @deprecated Use `useListQuery` */
+declare const createListQuery: typeof useListQuery;
+/** @deprecated Use `useDetailQuery` */
+declare const createDetailQuery: typeof useDetailQuery;
+/** @deprecated Use `useInfiniteListQuery` */
+declare const createInfiniteListQuery: typeof useInfiniteListQuery;
 //#endregion
-export { CacheUtils, CreateDetailQueryConfig, CreateInfiniteListQueryConfig, CreateListQueryConfig, DEFAULT_QUERY_CONFIG, DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, PaginationData, QueryKeys, RequestPassthrough, createCacheUtils, createDetailQuery, createInfiniteListQuery, createListQuery, createQueryKeys, getItemId, updateListCache };
-//# sourceMappingURL=query.d.ts.map
+export { CacheUtils, CreateDetailQueryConfig, CreateInfiniteListQueryConfig, CreateListQueryConfig, DEFAULT_QUERY_CONFIG, DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, PaginationData, QUERY_CONFIGS, QueryKeys, RequestPassthrough, createCacheUtils, createDetailQuery, createInfiniteListQuery, createListQuery, createQueryKeys, extractItem, getItemId, updateListCache, useDetailQuery, useInfiniteListQuery, useListQuery };

package/dist/query.js

@@ -1,7 +1,7 @@
 "use client";
 
 import { keepPreviousData, useInfiniteQuery, useQuery, useQueryClient } from "@tanstack/react-query";
-import { useEffect } from "react";
+import { useEffect, useMemo } from "react";
 
 //#region src/query.ts
 const DEFAULT_QUERY_CONFIG = {
@@ -10,6 +10,16 @@ const DEFAULT_QUERY_CONFIG = {
 	refetchOnWindowFocus: false,
 	retry: 0
 };
+/** Pre-built query config presets for common data freshness patterns. */
+const QUERY_CONFIGS = {
+	realtime: {
+		staleTime: 2e4,
+		refetchInterval: 3e4
+	},
+	frequent: { staleTime: 6e4 },
+	stable: { staleTime: 3e5 },
+	static: { staleTime: 6e5 }
+};
 function getItemId(item) {
 	if (!item || typeof item !== "object") return null;
 	const obj = item;
@@ -19,38 +29,68 @@ function getItemId(item) {
 function normalizePagination(data) {
 	if (!data || typeof data !== "object") return null;
 	const d = data;
+	const method = d.method ?? null;
+	const isKeyset = method === "keyset" || d.hasMore != null && d.total == null && d.pages == null;
 	const hasTotal = d.total != null || d.totalDocs != null;
 	const hasPages = d.pages != null || d.totalPages != null;
-	if (!hasTotal && !hasPages) return null;
+	if (!hasTotal && !hasPages && !isKeyset) return null;
 	return {
+		method,
 		total: Number(d.total ?? d.totalDocs ?? 0),
-		pages: Number(d.pages ?? d.totalPages ?? 1),
-		page: Number(d.page ?? d.currentPage ?? 1),
+		pages: Number(d.pages ?? d.totalPages ?? (isKeyset ? 0 : 1)),
+		page: Number(d.page ?? d.currentPage ?? (isKeyset ? 0 : 1)),
 		limit: Number(d.limit ?? 10),
 		hasNext: Boolean(d.hasNext ?? d.hasNextPage ?? d.hasMore ?? false),
-		hasPrev: Boolean(d.hasPrev ?? d.hasPrevPage ?? false)
+		hasPrev: Boolean(d.hasPrev ?? d.hasPrevPage ?? false),
+		...isKeyset ? { next: d.next ?? null } : {}
 	};
 }
+/** Well-known keys checked in order for list responses. */
+const LIST_KEYS = [
+	"docs",
+	"data",
+	"items",
+	"results"
+];
+/** Well-known keys checked in order for detail responses. */
+const DETAIL_KEYS = [
+	"data",
+	"doc",
+	"item",
+	"result"
+];
 function extractItems(data) {
 	if (!data) return [];
 	if (Array.isArray(data)) return data;
 	if (typeof data !== "object") return [];
 	const d = data;
-	const items = d.docs ?? d.data ?? d.items ?? d.results;
-	return Array.isArray(items) ? items : [];
+	for (const key of LIST_KEYS) if (Array.isArray(d[key])) return d[key];
+	for (const value of Object.values(d)) if (Array.isArray(value)) return value;
+	return [];
 }
 function extractItem(data) {
-	if (!data) return null;
-	if (typeof data !== "object") return null;
+	if (data == null) return null;
+	if (typeof data !== "object") return data;
 	const d = data;
-	return d.data ?? d;
+	for (const key of DETAIL_KEYS) if (d[key] != null) return d[key];
+	return d;
 }
 function updateListCache(listData, updater) {
 	if (!listData) return listData;
 	if (Array.isArray(listData)) return updater(listData);
 	if (typeof listData !== "object") return listData;
 	const d = listData;
-	const arrayField = "docs" in d ? "docs" : Array.isArray(d.data) ? "data" : "items" in d && Array.isArray(d.items) ? "items" : "results" in d && Array.isArray(d.results) ? "results" : null;
+	let arrayField = null;
+	for (const key of LIST_KEYS) if (Array.isArray(d[key])) {
+		arrayField = key;
+		break;
+	}
+	if (!arrayField) {
+		for (const [key, value] of Object.entries(d)) if (Array.isArray(value)) {
+			arrayField = key;
+			break;
+		}
+	}
 	if (!arrayField) return listData;
 	const updated = updater(d[arrayField]);
 	const original = d[arrayField];
@@ -107,7 +147,7 @@ function createCacheUtils(KEYS) {
 		removeDetail: (client, id) => client.removeQueries({ queryKey: KEYS.detail(id) })
 	};
 }
-function createListQuery({ queryKey, queryFn, enabled = true, options = {}, prefillDetailCache = true, detailKeyBuilder, select }) {
+function useListQuery({ queryKey, queryFn, enabled = true, options = {}, prefillDetailCache = true, detailKeyBuilder, itemIdResolver, select }) {
 	const queryClient = useQueryClient();
 	const query = useQuery({
 		queryKey,
@@ -118,12 +158,13 @@ function createListQuery({ queryKey, queryFn, enabled = true, options = {}, pref
 		...select ? { select } : {},
 		placeholderData: keepPreviousData
 	});
-	const items = extractItems(query.data);
-	const pagination = normalizePagination(query.data);
+	const items = useMemo(() => extractItems(query.data), [query.data]);
+	const pagination = useMemo(() => normalizePagination(query.data), [query.data]);
 	useEffect(() => {
 		if (!prefillDetailCache || !detailKeyBuilder || items.length === 0) return;
+		const resolveId = itemIdResolver ?? getItemId;
 		items.forEach((item) => {
-			const id = getItemId(item);
+			const id = resolveId(item);
 			if (id) queryClient.setQueryData(detailKeyBuilder(id), { data: item });
 		});
 	}, [
@@ -145,7 +186,7 @@ function createListQuery({ queryKey, queryFn, enabled = true, options = {}, pref
 		data: query.data
 	};
 }
-function createDetailQuery({ queryKey, queryFn, enabled = true, options = {}, select }) {
+function useDetailQuery({ queryKey, queryFn, enabled = true, options = {}, select }) {
 	const query = useQuery({
 		queryKey,
 		queryFn: ({ signal }) => queryFn({ signal }),
@@ -166,7 +207,7 @@ function createDetailQuery({ queryKey, queryFn, enabled = true, options = {}, se
 		data: query.data
 	};
 }
-function createInfiniteListQuery({ queryKey, queryFn, enabled = true, options = {}, initialPageParam = 1, getNextPageParam, getPreviousPageParam }) {
+function useInfiniteListQuery({ queryKey, queryFn, enabled = true, options = {}, initialPageParam = 1, getNextPageParam, getPreviousPageParam, maxPages }) {
 	const query = useInfiniteQuery({
 		queryKey,
 		queryFn: ({ pageParam, signal }) => queryFn({
@@ -177,11 +218,12 @@ function createInfiniteListQuery({ queryKey, queryFn, enabled = true, options =
 		initialPageParam,
 		getNextPageParam,
 		getPreviousPageParam,
+		...maxPages != null ? { maxPages } : {},
 		...DEFAULT_QUERY_CONFIG,
 		...options
 	});
 	return {
-		items: query.data?.pages.flatMap((page) => extractItems(page)) ?? [],
+		items: useMemo(() => query.data?.pages.flatMap((page) => extractItems(page)) ?? [], [query.data]),
 		hasNextPage: query.hasNextPage,
 		hasPreviousPage: query.hasPreviousPage,
 		isFetchingNextPage: query.isFetchingNextPage,
@@ -197,7 +239,12 @@ function createInfiniteListQuery({ queryKey, queryFn, enabled = true, options =
 		data: query.data
 	};
 }
+/** @deprecated Use `useListQuery` */
+const createListQuery = useListQuery;
+/** @deprecated Use `useDetailQuery` */
+const createDetailQuery = useDetailQuery;
+/** @deprecated Use `useInfiniteListQuery` */
+const createInfiniteListQuery = useInfiniteListQuery;
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, createCacheUtils, createDetailQuery, createInfiniteListQuery, createListQuery, createQueryKeys, getItemId, updateListCache };
-//# sourceMappingURL=query.js.map
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createDetailQuery, createInfiniteListQuery, createListQuery, createQueryKeys, extractItem, getItemId, updateListCache, useDetailQuery, useInfiniteListQuery, useListQuery };

package/dist/sse.d.ts

@@ -0,0 +1,62 @@
+import { QueryKey } from "@tanstack/react-query";
+
+//#region src/sse.d.ts
+interface ArcServerEvent {
+  type: string;
+  resource: string;
+  data: unknown;
+  timestamp: string;
+  id?: string;
+}
+interface EventStreamOptions {
+  /** SSE endpoint URL (absolute or relative to baseUrl). Default: `/{basePath}/{resource}/events/stream` */
+  url?: string;
+  /** Resource name used for the default endpoint path and event filtering. */
+  resource?: string;
+  /** Base path for the events endpoint. Default: '/api/v1' */
+  basePath?: string;
+  /** Event patterns to listen for (e.g., ['agents.created', 'agents.updated']). When empty, all events are received. */
+  patterns?: string[];
+  /** Query keys to invalidate when any event is received. */
+  invalidateQueries?: QueryKey[];
+  /** Callback for each event. */
+  onEvent?: (event: ArcServerEvent) => void;
+  /** Callback for connection state changes. */
+  onConnectionChange?: (connected: boolean) => void;
+  /** Whether the stream is enabled. Default: true */
+  enabled?: boolean;
+  /** Reconnect delay in ms. Default: 3000 */
+  reconnectDelay?: number;
+  /** Maximum reconnect attempts before giving up. Default: Infinity */
+  maxReconnectAttempts?: number;
+  /** Whether to include credentials (cookies). Derived from authMode when not set. */
+  withCredentials?: boolean;
+}
+interface EventStreamResult {
+  /** Whether the EventSource is currently connected. */
+  isConnected: boolean;
+  /** The most recently received event. */
+  lastEvent: ArcServerEvent | null;
+  /** Number of events received since connection. */
+  eventCount: number;
+  /** Close the connection manually. */
+  close: () => void;
+  /** Reconnect after a manual close. */
+  reconnect: () => void;
+}
+/**
+ * Subscribe to Arc server-sent events for real-time cache invalidation.
+ *
+ * Uses the browser's native `EventSource` API for automatic reconnection
+ * and efficient server-push. Events trigger query invalidation so TanStack Query
+ * refetches affected data automatically.
+ *
+ * @example
+ * const { isConnected } = useEventStream({
+ *   resource: 'agents',
+ *   invalidateQueries: [agentKeys.lists()],
+ * });
+ */
+declare function useEventStream(options: EventStreamOptions): EventStreamResult;
+//#endregion
+export { ArcServerEvent, EventStreamOptions, EventStreamResult, useEventStream };