@classytic/arc-next 0.5.0 → 0.7.0

package/dist/cache.js

@@ -7,28 +7,32 @@ const DEFAULT_QUERY_CONFIG = {
 };
 /** Pre-built query config presets for common data freshness patterns. */
 const QUERY_CONFIGS = {
+	/** Live data: 20s stale, 30s polling */
 	realtime: {
 		staleTime: 2e4,
 		refetchInterval: 3e4
 	},
+	/** Frequently updated: 60s stale */
 	frequent: { staleTime: 6e4 },
+	/** Stable data: 5min stale (same as default) */
 	stable: { staleTime: 3e5 },
+	/** Rarely changes: 10min stale */
 	static: { staleTime: 6e5 }
 };
-/** Well-known keys checked in order for list responses. */
+/**
+* Well-known keys checked in order for list responses.
+*
+* Arc emits `{data: T[]}` for both paginated and bare-list endpoints, so
+* `docs` is the canonical key. `items` / `results` cover non-arc backends
+* the permissive detector still supports — the any-array fallback below
+* keeps `{products: [...]}` / `{users: [...]}` working without per-resource
+* configuration.
+*/
 const LIST_KEYS = [
-	"docs",
 	"data",
 	"items",
 	"results"
 ];
-/** Well-known keys checked in order for detail responses. */
-const DETAIL_KEYS = [
-	"data",
-	"doc",
-	"item",
-	"result"
-];
 /**
 * Extract `_id` or `id` from any item. Returns `null` if neither exists.
 * Coerces numeric IDs to strings so cache keys stay consistent.
@@ -78,16 +82,14 @@ function extractItems(data) {
 	return [];
 }
 /**
-* Strict detail extractor. Checks well-known keys (`data`, `doc`, `item`,
-* `result`); falls back to returning the response as-is. Primitive responses
-* (string/number/boolean) pass through.
+* Detail extractor. Arc emits the doc directly (no envelope wrapper) — this
+* function is identity-with-null-guard. Kept as a named helper so callers
+* have a stable seam if a future backend ever ships an envelope, and so
+* `null` / `undefined` responses normalize to `null` consistently.
 */
 function extractItem(data) {
 	if (data == null) return null;
-	if (typeof data !== "object") return data;
-	const d = data;
-	for (const key of DETAIL_KEYS) if (d[key] != null) return d[key];
-	return d;
+	return data;
 }
 /**
 * Optimistic-update helper that mutates the items array of a list cache
@@ -113,6 +115,7 @@ function updateListCache(listData, updater) {
 	if (!arrayField) return listData;
 	const updated = updater(d[arrayField]);
 	const original = d[arrayField];
+	if (updated === original) return listData;
 	const delta = updated.length - original.length;
 	const result = {
 		...d,
@@ -124,6 +127,95 @@ function updateListCache(listData, updater) {
 	}
 	return result;
 }
+/** Item-identity helper that respects a custom idField, falling back to `_id` / `id`. */
+function resolveId(item, idField) {
+	if (!item || typeof item !== "object") return null;
+	if (idField) {
+		const v = item[idField];
+		if (v != null) return String(v);
+	}
+	return getItemId(item);
+}
+/**
+* Shallow-merge updater that preserves the receiver's key set. Detail payloads
+* are often richer than list payloads (populated relations, full body fields).
+* If we replaced wholesale we'd bloat list caches with detail-only fields and
+* force a full re-render on every value change. Merge keeps lists lean while
+* still picking up updates to fields the list already cares about.
+*/
+function shallowMergeKept(receiver, source) {
+	let changed = false;
+	const next = { ...receiver };
+	for (const key of Object.keys(receiver)) if (key in source && !Object.is(receiver[key], source[key])) {
+		next[key] = source[key];
+		changed = true;
+	}
+	return changed ? next : receiver;
+}
+/**
+* After a detail fetch lands, propagate the fresh values into every cached
+* list entry that contains this item. The item's ID is resolved via
+* `idField`, falling back to `_id` / `id`. Handles both flat list payloads
+* and infinite-query page arrays.
+*
+* Only updates EXISTING list entries — never creates new caches or new items
+* in lists. If the item moved between filter buckets (e.g. status changed),
+* the relevant lists will refetch on their own; we don't try to predict
+* filter membership.
+*
+* Returns the number of cache entries updated (useful for tests + telemetry).
+*
+* @param qc TanStack QueryClient
+* @param listsKey Prefix key for this entity's lists (typically `KEYS.lists()`)
+* @param item Fresh entity to merge into matching list items
+* @param opts.idField Custom ID field name (defaults to `_id` / `id` lookup)
+*/
+function syncDetailToLists(qc, listsKey, item, opts = {}) {
+	const targetId = resolveId(item, opts.idField);
+	if (!targetId) return 0;
+	let updates = 0;
+	const entries = qc.getQueriesData({ queryKey: listsKey });
+	for (const [qKey, raw] of entries) {
+		if (!raw) continue;
+		if (typeof raw === "object" && raw !== null && Array.isArray(raw.pages)) {
+			const inf = raw;
+			let pagesChanged = false;
+			const nextPages = inf.pages.map((page) => {
+				const merged = mergeItemIntoListPage(page, targetId, item, opts.idField);
+				if (merged !== page) pagesChanged = true;
+				return merged;
+			});
+			if (pagesChanged) {
+				qc.setQueryData(qKey, {
+					...inf,
+					pages: nextPages
+				});
+				updates += 1;
+			}
+			continue;
+		}
+		const merged = mergeItemIntoListPage(raw, targetId, item, opts.idField);
+		if (merged !== raw) {
+			qc.setQueryData(qKey, merged);
+			updates += 1;
+		}
+	}
+	return updates;
+}
+/** Internal — merge an item into a single list payload (one filter result or one infinite page). */
+function mergeItemIntoListPage(page, targetId, item, idField) {
+	return updateListCache(page, (items) => {
+		let changed = false;
+		const next = items.map((listItem) => {
+			if (!listItem || typeof listItem !== "object") return listItem;
+			if (resolveId(listItem, idField) !== targetId) return listItem;
+			const merged = shallowMergeKept(listItem, item);
+			if (merged !== listItem) changed = true;
+			return merged;
+		});
+		return changed ? next : items;
+	});
+}
 /**
 * Build a hierarchical query-key factory for a resource. The returned shape
 * is identical between server (prefetch) and client (hooks), so RSC SSR
@@ -166,6 +258,17 @@ function createQueryKeys(entityKey) {
 				_scope: scope,
 				...params
 			}
+		],
+		aggregations: () => [entityKey, "aggregation"],
+		aggregation: (name, filter) => filter !== void 0 ? [
+			entityKey,
+			"aggregation",
+			name,
+			filter
+		] : [
+			entityKey,
+			"aggregation",
+			name
 		]
 	};
 }
@@ -173,25 +276,28 @@ function createQueryKeys(entityKey) {
 * Build cache read/write/invalidate helpers bound to the given key factory.
 * Server-safe — operates on a `QueryClient` instance which can be a per-request
 * server client (during prefetch) or the browser singleton.
+*
+* **Wire shape:** Arc 2.13+ emits raw documents on `GET /:resource/:id` — no
+* `{ data: ... }` envelope. `setDetail` / `getDetail` write and read the raw
+* doc directly so the cache shape matches `useDetail`'s `queryFn` output,
+* `useNavigation`'s pre-populated entries, and `prefetchDetail`'s server seed.
+* All four paths converge on the same shape: TDoc, not `{ data: TDoc }`.
 */
 function createCacheUtils(KEYS) {
 	return {
 		invalidateAll: (client) => client.invalidateQueries({ queryKey: KEYS.all }),
 		invalidateLists: (client) => client.invalidateQueries({ queryKey: KEYS.lists() }),
 		invalidateDetail: (client, id) => client.invalidateQueries({ queryKey: KEYS.detail(id) }),
-		setDetail: (client, id, data) => client.setQueryData(KEYS.detail(id), { data }),
-		getDetail: (client, id) => {
-			return client.getQueryData(KEYS.detail(id))?.data;
-		},
+		setDetail: (client, id, data) => client.setQueryData(KEYS.detail(id), data),
+		getDetail: (client, id) => client.getQueryData(KEYS.detail(id)) ?? void 0,
 		removeDetail: (client, id) => client.removeQueries({ queryKey: KEYS.detail(id) }),
 		invalidateScopedDetail: (client, id, organizationId) => client.invalidateQueries({ queryKey: KEYS.scopedDetail(id, organizationId) }),
-		setScopedDetail: (client, id, organizationId, data) => client.setQueryData(KEYS.scopedDetail(id, organizationId), { data }),
-		getScopedDetail: (client, id, organizationId) => {
-			return client.getQueryData(KEYS.scopedDetail(id, organizationId))?.data;
-		},
-		removeScopedDetail: (client, id, organizationId) => client.removeQueries({ queryKey: KEYS.scopedDetail(id, organizationId) })
+		setScopedDetail: (client, id, organizationId, data) => client.setQueryData(KEYS.scopedDetail(id, organizationId), data),
+		getScopedDetail: (client, id, organizationId) => client.getQueryData(KEYS.scopedDetail(id, organizationId)) ?? void 0,
+		removeScopedDetail: (client, id, organizationId) => client.removeQueries({ queryKey: KEYS.scopedDetail(id, organizationId) }),
+		invalidateAggregations: (client, name) => client.invalidateQueries({ queryKey: name ? KEYS.aggregation(name) : KEYS.aggregations() })
 	};
 }
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache };
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache };