@classytic/arc-next 0.4.1 → 0.6.0

package/dist/cache.d.ts

@@ -0,0 +1,125 @@
+import { QueryClient, QueryKey } from "@tanstack/react-query";
+
+//#region src/cache.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;
+}
+declare const DEFAULT_QUERY_CONFIG: {
+  readonly staleTime: number;
+  readonly gcTime: number;
+  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;
+  };
+};
+/**
+ * Extract `_id` or `id` from any item. Returns `null` if neither exists.
+ * Coerces numeric IDs to strings so cache keys stay consistent.
+ */
+declare function getItemId(item: unknown): string | null;
+/**
+ * Normalize any pagination response shape (offset / keyset / aggregate) to a
+ * uniform `PaginationData` object. Returns `null` when no pagination signal
+ * is present.
+ */
+declare function normalizePagination(data: unknown): PaginationData | null;
+/**
+ * Permissive list extractor. Checks well-known keys (`docs`, `data`, `items`,
+ * `results`) then falls back to *any* top-level array — so `{ products: [...] }`
+ * and `{ users: [...] }` work without per-resource configuration.
+ */
+declare function extractItems<T>(data: unknown): T[];
+/**
+ * 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.
+ */
+declare function extractItem<T>(data: unknown): T | null;
+/**
+ * Optimistic-update helper that mutates the items array of a list cache
+ * regardless of which key holds it. Auto-adjusts `total`/`totalDocs` when
+ * the array length changes.
+ */
+declare function updateListCache<T>(listData: unknown, updater: (items: T[]) => T[]): unknown;
+interface QueryKeys {
+  all: string[];
+  lists: () => QueryKey;
+  list: (params?: unknown) => QueryKey;
+  details: () => QueryKey;
+  detail: (id: string) => QueryKey;
+  /** Tenant-scoped detail key. Use when IDs are only unique within an org. */
+  scopedDetail: (id: string, organizationId: string | null) => QueryKey;
+  custom: (key: string, ...args: unknown[]) => QueryKey;
+  scopedList: (scope: string, params?: unknown) => QueryKey;
+  /** Prefix for every aggregation on this resource — invalidate all at once. */
+  aggregations: () => QueryKey;
+  /**
+   * Aggregation key (`arc 2.13+ /aggregations/:name`). The `filter` arg is
+   * structurally hashed by TanStack — pass the same object identity (or
+   * structurally identical) you pass to `useAggregation` so the cache hits.
+   */
+  aggregation: (name: string, filter?: unknown) => QueryKey;
+}
+/**
+ * Build a hierarchical query-key factory for a resource. The returned shape
+ * is identical between server (prefetch) and client (hooks), so RSC SSR
+ * hydration matches what client-side `useList`/`useDetail` produce.
+ */
+declare function createQueryKeys(entityKey: string): QueryKeys;
+interface CacheUtils<T> {
+  invalidateAll: (client: QueryClient) => Promise<void>;
+  invalidateLists: (client: QueryClient) => Promise<void>;
+  /** Invalidate detail by ID (prefix-matches all scoped/parameterized variants). */
+  invalidateDetail: (client: QueryClient, id: string) => Promise<void>;
+  setDetail: (client: QueryClient, id: string, data: T) => void;
+  getDetail: (client: QueryClient, id: string) => T | undefined;
+  removeDetail: (client: QueryClient, id: string) => void;
+  /** Invalidate tenant-scoped detail (prefix-matches parameterized variants within org). */
+  invalidateScopedDetail: (client: QueryClient, id: string, organizationId: string | null) => Promise<void>;
+  /** Set tenant-scoped detail cache. */
+  setScopedDetail: (client: QueryClient, id: string, organizationId: string | null, data: T) => void;
+  /** Get tenant-scoped detail from cache. */
+  getScopedDetail: (client: QueryClient, id: string, organizationId: string | null) => T | undefined;
+  /** Remove tenant-scoped detail from cache. */
+  removeScopedDetail: (client: QueryClient, id: string, organizationId: string | null) => void;
+  /**
+   * Invalidate every aggregation for this resource. Call from mutation
+   * `onSuccess` so dashboards refresh after CRUD writes.
+   *
+   * For targeted invalidation of a single aggregation pass the name —
+   * prefix-matches every parameterized variant.
+   */
+  invalidateAggregations: (client: QueryClient, name?: string) => Promise<void>;
+}
+/**
+ * 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.
+ */
+declare function createCacheUtils<T>(KEYS: QueryKeys): CacheUtils<T>;
+//#endregion
+export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache };

package/dist/cache.js

@@ -0,0 +1,211 @@
+//#region src/cache.ts
+const DEFAULT_QUERY_CONFIG = {
+	staleTime: 300 * 1e3,
+	gcTime: 1800 * 1e3,
+	refetchOnWindowFocus: false,
+	retry: 0
+};
+/** 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.
+*
+* 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 = [
+	"data",
+	"items",
+	"results"
+];
+/**
+* Extract `_id` or `id` from any item. Returns `null` if neither exists.
+* Coerces numeric IDs to strings so cache keys stay consistent.
+*/
+function getItemId(item) {
+	if (!item || typeof item !== "object") return null;
+	const obj = item;
+	const id = obj._id ?? obj.id;
+	return typeof id === "string" ? id : id ? String(id) : null;
+}
+/**
+* Normalize any pagination response shape (offset / keyset / aggregate) to a
+* uniform `PaginationData` object. Returns `null` when no pagination signal
+* is present.
+*/
+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 && !isKeyset) return null;
+	return {
+		method,
+		total: Number(d.total ?? d.totalDocs ?? 0),
+		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),
+		...isKeyset ? { next: d.next ?? null } : {}
+	};
+}
+/**
+* Permissive list extractor. Checks well-known keys (`docs`, `data`, `items`,
+* `results`) then falls back to *any* top-level array — so `{ products: [...] }`
+* and `{ users: [...] }` work without per-resource configuration.
+*/
+function extractItems(data) {
+	if (!data) return [];
+	if (Array.isArray(data)) return data;
+	if (typeof data !== "object") return [];
+	const d = data;
+	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 [];
+}
+/**
+* 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;
+	return data;
+}
+/**
+* Optimistic-update helper that mutates the items array of a list cache
+* regardless of which key holds it. Auto-adjusts `total`/`totalDocs` when
+* the array length changes.
+*/
+function updateListCache(listData, updater) {
+	if (!listData) return listData;
+	if (Array.isArray(listData)) return updater(listData);
+	if (typeof listData !== "object") return listData;
+	const d = listData;
+	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];
+	const delta = updated.length - original.length;
+	const result = {
+		...d,
+		[arrayField]: updated
+	};
+	if (delta !== 0) {
+		if (d.total != null) result.total = Math.max(0, Number(d.total) + delta);
+		if (d.totalDocs != null) result.totalDocs = Math.max(0, Number(d.totalDocs) + delta);
+	}
+	return result;
+}
+/**
+* Build a hierarchical query-key factory for a resource. The returned shape
+* is identical between server (prefetch) and client (hooks), so RSC SSR
+* hydration matches what client-side `useList`/`useDetail` produce.
+*/
+function createQueryKeys(entityKey) {
+	return {
+		all: [entityKey],
+		lists: () => [entityKey, "list"],
+		list: (params) => [
+			entityKey,
+			"list",
+			params
+		],
+		details: () => [entityKey, "detail"],
+		detail: (id) => [
+			entityKey,
+			"detail",
+			id
+		],
+		scopedDetail: (id, organizationId) => organizationId ? [
+			entityKey,
+			"detail",
+			id,
+			{ _org: organizationId }
+		] : [
+			entityKey,
+			"detail",
+			id
+		],
+		custom: (key, ...args) => [
+			entityKey,
+			key,
+			...args
+		],
+		scopedList: (scope, params) => [
+			entityKey,
+			"list",
+			{
+				_scope: scope,
+				...params
+			}
+		],
+		aggregations: () => [entityKey, "aggregation"],
+		aggregation: (name, filter) => filter !== void 0 ? [
+			entityKey,
+			"aggregation",
+			name,
+			filter
+		] : [
+			entityKey,
+			"aggregation",
+			name
+		]
+	};
+}
+/**
+* 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.
+*/
+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;
+		},
+		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) }),
+		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 };