@classytic/arc-next 0.3.1 → 0.4.0

package/dist/query.d.ts

@@ -103,6 +103,22 @@ 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;
@@ -117,6 +133,8 @@ 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 useListQuery<T>({
@@ -126,6 +144,7 @@ declare function useListQuery<T>({
   options,
   prefillDetailCache,
   detailKeyBuilder,
+  itemIdResolver,
   select
 }: CreateListQueryConfig): ListQueryResult<T>;
 interface CreateDetailQueryConfig {
@@ -155,6 +174,12 @@ interface InfiniteListQueryOptions {
   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[];
@@ -183,6 +208,8 @@ 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 useInfiniteListQuery<T>({
   queryKey,
@@ -191,7 +218,8 @@ declare function useInfiniteListQuery<T>({
   options,
   initialPageParam,
   getNextPageParam,
-  getPreviousPageParam
+  getPreviousPageParam,
+  maxPages
 }: CreateInfiniteListQueryConfig): InfiniteListQueryResult<T>;
 /** @deprecated Use `useListQuery` */
 declare const createListQuery: typeof useListQuery;
@@ -200,4 +228,4 @@ 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, extractItem, getItemId, updateListCache, useDetailQuery, useInfiniteListQuery, useListQuery };
+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

@@ -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;
@@ -137,7 +147,7 @@ function createCacheUtils(KEYS) {
 		removeDetail: (client, id) => client.removeQueries({ queryKey: KEYS.detail(id) })
 	};
 }
-function useListQuery({ 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,
@@ -152,8 +162,9 @@ function useListQuery({ queryKey, queryFn, enabled = true, options = {}, prefill
 	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 });
 		});
 	}, [
@@ -196,7 +207,7 @@ function useDetailQuery({ queryKey, queryFn, enabled = true, options = {}, selec
 		data: query.data
 	};
 }
-function useInfiniteListQuery({ 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({
@@ -207,6 +218,7 @@ function useInfiniteListQuery({ queryKey, queryFn, enabled = true, options = {},
 		initialPageParam,
 		getNextPageParam,
 		getPreviousPageParam,
+		...maxPages != null ? { maxPages } : {},
 		...DEFAULT_QUERY_CONFIG,
 		...options
 	});
@@ -235,4 +247,4 @@ const createDetailQuery = useDetailQuery;
 const createInfiniteListQuery = useInfiniteListQuery;
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, createCacheUtils, createDetailQuery, createInfiniteListQuery, createListQuery, createQueryKeys, extractItem, getItemId, updateListCache, useDetailQuery, useInfiniteListQuery, useListQuery };
+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 };

package/dist/sse.js

@@ -0,0 +1,144 @@
+"use client";
+
+import { getAuthContext, getAuthMode } from "./client.js";
+import { useQueryClient } from "@tanstack/react-query";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+//#region src/sse.ts
+/**
+* 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()],
+* });
+*/
+function useEventStream(options) {
+	const { url, resource, basePath = "/api/v1", enabled = true, reconnectDelay = 3e3, maxReconnectAttempts = Infinity, withCredentials } = options;
+	const queryClient = useQueryClient();
+	const [isConnected, setIsConnected] = useState(false);
+	const [lastEvent, setLastEvent] = useState(null);
+	const [eventCount, setEventCount] = useState(0);
+	const esRef = useRef(null);
+	const reconnectAttemptsRef = useRef(0);
+	const reconnectTimerRef = useRef(null);
+	const manualCloseRef = useRef(false);
+	const onEventRef = useRef(options.onEvent);
+	onEventRef.current = options.onEvent;
+	const onConnectionChangeRef = useRef(options.onConnectionChange);
+	onConnectionChangeRef.current = options.onConnectionChange;
+	const patternsRef = useRef(options.patterns ?? []);
+	patternsRef.current = options.patterns ?? [];
+	const invalidateKeysRef = useRef(options.invalidateQueries ?? []);
+	invalidateKeysRef.current = options.invalidateQueries ?? [];
+	const buildUrl = useCallback(() => {
+		if (url) return url;
+		if (!resource) throw new Error("[arc-next] useEventStream requires either `url` or `resource`");
+		const auth = getAuthContext();
+		const params = new URLSearchParams();
+		const patterns = patternsRef.current;
+		if (patterns.length > 0) params.set("patterns", patterns.join(","));
+		if (auth.organizationId) params.set("organizationId", auth.organizationId);
+		if (auth.token) params.set("token", auth.token);
+		const qs = params.toString();
+		const base = `${basePath}/${resource}/events/stream`;
+		return qs ? `${base}?${qs}` : base;
+	}, [
+		url,
+		resource,
+		basePath
+	]);
+	const connect = useCallback(() => {
+		if (esRef.current) esRef.current.close();
+		manualCloseRef.current = false;
+		const eventUrl = buildUrl();
+		const authMode = getAuthMode();
+		const es = new EventSource(eventUrl, { withCredentials: withCredentials ?? authMode === "cookie" });
+		esRef.current = es;
+		es.onopen = () => {
+			reconnectAttemptsRef.current = 0;
+			setIsConnected(true);
+			onConnectionChangeRef.current?.(true);
+		};
+		es.onmessage = (event) => {
+			try {
+				const parsed = JSON.parse(event.data);
+				const patterns = patternsRef.current;
+				if (patterns.length > 0 && !patterns.includes(parsed.type)) return;
+				setLastEvent(parsed);
+				setEventCount((c) => c + 1);
+				onEventRef.current?.(parsed);
+				const keys = invalidateKeysRef.current;
+				for (const key of keys) queryClient.invalidateQueries({ queryKey: key });
+			} catch {}
+		};
+		es.onerror = () => {
+			es.close();
+			setIsConnected(false);
+			onConnectionChangeRef.current?.(false);
+			if (manualCloseRef.current) return;
+			if (reconnectAttemptsRef.current < maxReconnectAttempts) {
+				reconnectAttemptsRef.current += 1;
+				const delay = Math.min(reconnectDelay * Math.pow(1.5, reconnectAttemptsRef.current - 1), 3e4);
+				reconnectTimerRef.current = setTimeout(connect, delay);
+			}
+		};
+	}, [
+		buildUrl,
+		queryClient,
+		withCredentials,
+		reconnectDelay,
+		maxReconnectAttempts
+	]);
+	const close = useCallback(() => {
+		manualCloseRef.current = true;
+		if (reconnectTimerRef.current) {
+			clearTimeout(reconnectTimerRef.current);
+			reconnectTimerRef.current = null;
+		}
+		if (esRef.current) {
+			esRef.current.close();
+			esRef.current = null;
+		}
+		setIsConnected(false);
+		onConnectionChangeRef.current?.(false);
+	}, []);
+	const reconnect = useCallback(() => {
+		reconnectAttemptsRef.current = 0;
+		connect();
+	}, [connect]);
+	useEffect(() => {
+		if (!enabled) {
+			close();
+			return;
+		}
+		connect();
+		return () => {
+			manualCloseRef.current = true;
+			if (reconnectTimerRef.current) clearTimeout(reconnectTimerRef.current);
+			if (esRef.current) {
+				esRef.current.close();
+				esRef.current = null;
+			}
+		};
+	}, [
+		enabled,
+		connect,
+		close
+	]);
+	return {
+		isConnected,
+		lastEvent,
+		eventCount,
+		close,
+		reconnect
+	};
+}
+
+//#endregion
+export { useEventStream };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-next",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "React + TanStack Query SDK for Arc resources",
   "type": "module",
   "sideEffects": false,
@@ -21,7 +21,11 @@
     "pagination",
     "multi-tenant",
     "arc",
-    "mongokit"
+    "mongokit",
+    "sse",
+    "real-time",
+    "soft-delete",
+    "bulk-operations"
   ],
   "main": "./dist/hooks.js",
   "types": "./dist/hooks.d.ts",
@@ -57,7 +61,12 @@
     "./prefetch": {
       "types": "./dist/prefetch.d.ts",
       "default": "./dist/prefetch.js"
-    }
+    },
+    "./sse": {
+      "types": "./dist/sse.d.ts",
+      "default": "./dist/sse.js"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist"
@@ -78,20 +87,20 @@
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "peerDependencies": {
-    "@tanstack/react-query": "^5.0.0",
-    "react": "^19.0.0"
+    "@tanstack/react-query": ">=5.0.0",
+    "react": ">=19.0.0"
   },
   "devDependencies": {
-    "@tanstack/react-query": "^5.95.2",
+    "@tanstack/react-query": "^5.97.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
-    "@types/react": "^19.0.0",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "jsdom": "^28.1.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.2.4",
-    "tsdown": "^0.21.4",
-    "typescript": "^5.7.2",
-    "vitest": "^4.0.18"
+    "jsdom": "^29.0.2",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
   }
 }