@classytic/arc-next 0.11.1 → 0.13.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Classytic
+Copyright (c) 2025 Classytic LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,5 +1,7 @@
 # @classytic/arc-next
 
+[![Sponsor](https://img.shields.io/github/sponsors/classytic?style=flat-square&label=Sponsor&logo=GitHub&color=EA4AAA)](https://github.com/sponsors/classytic)
+
 React + TanStack Query SDK for the Arc backend framework. Typed CRUD hooks, optimistic updates with rollback, multi-tenant cache scoping, pagination normalization, real-time SSE.
 
 **Peers:** React 19+, TanStack React Query 5+
@@ -37,6 +39,10 @@ configureToast({ success: toast.success, error: toast.error });
 configureNavigation(useRouter);
 ```
 
+Without `configureToast`, mutation feedback is a silent no-op (0.12+) — the SDK never writes to your console; errors still reach `onError` / the rejected promise.
+
+> **Targets:** React 19 browser apps + Next.js App Router. React Native is NOT officially supported — the fetch client may work, but SSE needs an `EventSource` polyfill, uploads depend on RN's XHR/FormData behavior, and field encryption needs Web Crypto. File an issue if you need an RN adapter.
+
 `getToken` **must be synchronous** — cache async tokens out-of-band. Promise returns are dropped + warned in dev.
 
 ## Quick Start
@@ -388,6 +394,44 @@ Pure helpers (`createQueryKeys`, `extractItem`, `updateListCache`, etc.) live in
 
 TanStack Query manages a client-side cache; data fetched through arc-next hooks should NOT be wrapped in a Server Component's `'use cache'` directive (which would bake the hook output into the static render). Use `'use cache'` for non-arc Server Component fetches (e.g., direct DB queries, third-party APIs). The two layers compose cleanly because they target different cache tiers.
 
+## Request-Scoped Server Clients (0.12+)
+
+`configureClient` / `configureAuth` set module singletons — correct for the browser, wrong for servers where concurrent requests would share state. On the server, build a **request-scoped** client instead. The SDK never imports `next` or reads cookies itself: your framework code reads the request, the SDK gets plain values.
+
+```ts
+// app/orders/page.tsx (Server Component) — host reads cookies, SDK stays framework-free
+import { cookies } from 'next/headers';
+import { createServerClient } from '@classytic/arc-next/client';
+import { createCrudApi } from '@classytic/arc-next/api';
+
+export default async function OrdersPage() {
+  const client = createServerClient({
+    baseUrl: process.env.API_URL!,
+    token: (await cookies()).get('session')?.value ?? null,
+    organizationId: null,
+  });
+  const orders = createCrudApi<Order>('orders', { client });
+  const page = await orders.getAll({
+    options: { next: { revalidate: 60, tags: ['orders'] } },  // Next fetch-cache passthrough
+  });
+  // render...
+}
+```
+
+`next: { tags, revalidate }` and `cache:` are typed pass-throughs to `fetch` — inert on non-Next runtimes, no `next` peer dependency.
+
+## Optimistic Updates — the guarantees (0.12+)
+
+`useActions()` mutations uphold, in order:
+
+1. **Cancel-before-write** — in-flight refetches for affected keys are cancelled before the snapshot, so a late response can't be captured as "previous" state.
+2. **Every affected cache** — detail (bare + org-scoped + parameterized), flat lists, **infinite lists** (per-page; a create inserts into the first page only), while aggregation caches are never optimistically mutated (refetch-only).
+3. **Exact rollback** — on failure every touched entry is restored to its snapshot; untouched entries are never rewritten.
+4. **Temp-ID reconciliation** — `create` inserts a `_optimistic` placeholder with a `temp-…` id, then swaps it in place for the server document on success (and seeds `KEYS.detail(realId)`), so the row never flickers and the real id is immediately navigable.
+5. **Per-record ordering** — sequential `update`/`remove`/`restore` calls to the same record are chained (call order = server order); different records stay parallel.
+6. **Last-standing invalidation** — rapid sequential writes trigger ONE settled refetch (from the last pending write), so an early write's refetch can never overwrite a later write's optimistic state.
+7. **Bulk partial success** — `bulkUpdate`/`bulkRemove` reporting zero changes skip invalidation entirely; `bulkCreate` seeds detail caches from the returned documents.
+
 ## Errors
 
 ```ts
@@ -425,11 +469,17 @@ Network resilience for mutations + direct `handleApiRequest` calls (TanStack Que
 ```ts
 configureClient({
   baseUrl: process.env.NEXT_PUBLIC_API_URL!,
+  timeoutMs: 15_000,                   // per-attempt request timeout; hung fetches fail
+                                       // with a RETRYABLE TimeoutError. Default: disabled.
+                                       // Per-request override: options.timeoutMs (0 disables).
   retry: {
     attempts: 3,                       // 1 initial + 2 retries; default off
     backoff: 'exponential',            // 'exponential' | 'linear' | (attempt) => ms
+    jitter: 'full',                    // randomize delays in [0, computed] — anti-stampede. Default 'none'.
     // retryOn: [502, 503, 504],       // optional whitelist; default = network failures + 5xx, never 4xx, never AbortError
   },
+  // 429/503 responses with a Retry-After header override computed backoff —
+  // the parsed value is also exposed as ArcApiError.retryAfterMs.
   // Mutate outgoing requests (per attempt — retries re-run this)
   beforeRequest: (ctx) => ({
     ...ctx,
@@ -600,3 +650,10 @@ const { mutateAsync: publish, isPending } = useMutationWithTransition({
 ## License
 
 MIT
+
+
+## Trademark
+
+The code is MIT-licensed. **"Classytic", "arc", and the logos are trademarks of
+Classytic LLC** and are **not** licensed under MIT — see [TRADEMARK.md](TRADEMARK.md).
+Forks must be renamed; the license covers the code, not the brand.

package/dist/api.d.ts

@@ -1,15 +1,25 @@
 import { ArcClient, NextFetchOptions } from "./client.js";
-import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult, PaginatedResult } from "@classytic/repo-core/pagination";
+import { BracketOperator, BracketOperator as BracketOperator$1, ParsedPopulate } from "@classytic/repo-core/query-parser";
+import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult, PaginatedResult, SortDirection as SortDirection$1 } from "@classytic/repo-core/pagination";
 import { AggResult, AggRow, BulkCreateResult, DeleteManyResult, DeleteResult, UpdateManyResult } from "@classytic/repo-core/repository";
-import { BracketOperator, BracketOperator as BracketOperator$1 } from "@classytic/repo-core/query-parser";
-
 //#region src/api.d.ts
-interface PopulateOption {
-  path: string;
-  select?: string;
-  match?: Record<string, unknown>;
-}
-type SortDirection = 1 | -1 | 'asc' | 'desc';
+/**
+ * URL-emittable subset of repo-core's canonical {@link ParsedPopulate} —
+ * the exact three fields `populate[path][select]` / `populate[path][match]`
+ * bracket emission supports. Derived (not re-declared) so a canonical field
+ * rename breaks HERE at compile time instead of silently drifting.
+ * `options` / nested `populate` are parse-side-only in repo-core and have
+ * no URL grammar, so they're intentionally absent.
+ */
+type PopulateOption = Pick<ParsedPopulate, "path" | "select" | "match">;
+/**
+ * Canonical repo-core sort direction (`1 | -1`) plus the URL-ergonomic
+ * string forms. The numeric core comes from `@classytic/repo-core/pagination`
+ * so the wire vocabulary can't drift; `'asc' | 'desc'` are an SDK-side
+ * convenience serialized to the same URL grammar.
+ */
+type SortDirection = SortDirection$1 | "asc" | "desc";
+/** Sort spec: record form (repo-core `SortSpec` widened to string directions) or the raw URL string. */
 type SortSpec = Record<string, SortDirection> | string;
 /**
  * Filter operators supported by arc-next URL emission.
@@ -26,17 +36,23 @@ type SortSpec = Record<string, SortDirection> | string;
  *    don't emit them; the union stays open with `(string & {})` so custom
  *    domain operators still satisfy the type.
  */
-type FilterOperator = BracketOperator$1 | 'size' | 'type' | 'near' | 'nearSphere' | 'geoWithin' | 'withinRadius' | (string & {});
+type FilterOperator = BracketOperator$1 | "size" | "type" | "near" | "nearSphere" | "geoWithin" | "withinRadius" | (string & {});
 interface QueryParams {
   page?: number;
   limit?: number;
+  /** Keyset cursor — the CANONICAL wire param (repo-core `STANDARD_RESERVED_PARAMS`). */
   after?: string;
+  /**
+   * Alias for {@link QueryParams.after}. The server only knows `after`;
+   * `prepareParams` rewrites `cursor` → `after` at emission (explicit
+   * `after` wins when both are set). Prefer `after` in new code.
+   */
   cursor?: string;
   sort?: string;
   select?: string;
   populate?: string | string[];
   populateOptions?: PopulateOption[];
-  lean?: boolean | 'true' | 'false';
+  lean?: boolean | "true" | "false";
   /** Database-agnostic joins. Maps alias → collection or full lookup config. */
   lookup?: Record<string, string | {
     from: string;
@@ -59,7 +75,7 @@ interface RequestOptions {
    */
   next?: NextFetchOptions;
   headerOptions?: Record<string, string>;
-  responseType?: 'json' | 'blob' | 'text';
+  responseType?: "json" | "blob" | "text";
   signal?: AbortSignal;
 }
 /**
@@ -72,7 +88,7 @@ interface RequestOptions {
 interface ScopedArgs {
   token?: string | null;
   organizationId?: string | null;
-  options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  options?: Omit<RequestOptions, "token" | "organizationId">;
 }
 interface BaseApiConfig {
   basePath?: string;
@@ -83,11 +99,22 @@ interface BaseApiConfig {
   };
   cache?: RequestCache;
   headers?: Record<string, string>;
-  client?: ArcClient;
+  /**
+   * Transport for this API instance.
+   *
+   * - `ArcClient` — RETAINED: the instance is captured and every request goes
+   *   through it (isolated multi-client setups, tests, background jobs).
+   * - `() => ArcClient` — PROVIDER: re-resolved on EVERY request, so a
+   *   consumer SDK can swap/reconfigure the underlying client after APIs are
+   *   constructed without Proxy tricks or stale-capture bugs (the reason the
+   *   commerce SDK previously wrapped its default client in a `Proxy`).
+   * - omitted — the module-global transport (`configureClient`/`configureAuth`).
+   */
+  client?: ArcClient | (() => ArcClient);
 }
 declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>> {
   readonly entity: string;
-  readonly config: Required<Omit<BaseApiConfig, 'client'>>;
+  readonly config: Required<Omit<BaseApiConfig, "client">>;
   readonly baseUrl: string;
   private readonly requestFn;
   constructor(entity: string, config?: BaseApiConfig);
@@ -112,68 +139,41 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
   private withCacheDefault;
   createQueryString(params?: Record<string, unknown>): string;
   prepareParams(params?: QueryParams): Record<string, unknown>;
-  getAll({
-    token,
-    organizationId,
-    params,
-    options
-  }?: {
+  getAll({ token, organizationId, params, options }?: {
     token?: string | null;
     organizationId?: string | null;
     params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<PaginatedResult<TDoc>>;
   /**
    * Count records matching the filters — arc's list-route dispatch verb
    * (`?_count=true`): same permissions/row-filters/tenant scoping as
    * `getAll`, ZERO documents fetched. Cheapest way to answer "how many".
    */
-  count({
-    token,
-    organizationId,
-    params,
-    options
-  }?: {
+  count({ token, organizationId, params, options }?: {
     token?: string | null;
     organizationId?: string | null;
     params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<number>;
   /** Whether ANY record matches the filters (`?_exists=true`). */
-  exists({
-    token,
-    organizationId,
-    params,
-    options
-  }?: {
+  exists({ token, organizationId, params, options }?: {
     token?: string | null;
     organizationId?: string | null;
     params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<boolean>;
   /** Distinct values of a field across matching records (`?_distinct=field`). */
-  distinct<TValue = unknown>({
-    token,
-    organizationId,
-    field,
-    params,
-    options
-  }: {
+  distinct<TValue = unknown>({ token, organizationId, field, params, options }: {
     token?: string | null;
     organizationId?: string | null;
     field: string;
     params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<TValue[]>;
   /** Shared raw GET against the list route (dispatch verbs bypass pagination parsing). */
   private getAllRaw;
-  getById({
-    token,
-    organizationId,
-    id,
-    params,
-    options
-  }: {
+  getById({ token, organizationId, id, params, options }: {
     token?: string | null;
     organizationId?: string | null;
     id: string;
@@ -181,62 +181,35 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
       select?: string;
       populate?: string | string[];
     };
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<TDoc>;
-  create({
-    token,
-    organizationId,
-    data,
-    options
-  }: {
+  create({ token, organizationId, data, options }: {
     token?: string | null;
     organizationId?: string | null;
     data: TCreate;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<TDoc>;
-  update({
-    token,
-    organizationId,
-    id,
-    data,
-    options
-  }: {
+  update({ token, organizationId, id, data, options }: {
     token?: string | null;
     organizationId?: string | null;
     id: string;
     data: TUpdate;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<TDoc>;
-  delete({
-    token,
-    organizationId,
-    id,
-    options
-  }: {
+  delete({ token, organizationId, id, options }: {
     token?: string | null;
     organizationId?: string | null;
     id: string;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<DeleteResult>;
-  upload({
-    token,
-    organizationId,
-    data,
-    id,
-    path,
-    options
-  }: ScopedArgs & {
-    data: FormData; /** Resource ID — shorthand for path, appended as `baseUrl/{id}/upload` */
-    id?: string; /** Custom sub-path appended as `baseUrl/{path}`. Takes precedence over `id`. */
+  upload({ token, organizationId, data, id, path, options }: ScopedArgs & {
+    data: FormData;
+    /** Resource ID — shorthand for path, appended as `baseUrl/{id}/upload` */
+    id?: string;
+    /** Custom sub-path appended as `baseUrl/{path}`. Takes precedence over `id`. */
     path?: string;
   }): Promise<TDoc>;
-  request<TResponse = unknown>(method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', endpoint: string, {
-    token,
-    organizationId,
-    data,
-    params,
-    options
-  }?: ScopedArgs & {
+  request<TResponse = unknown>(method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE", endpoint: string, { token, organizationId, data, params, options }?: ScopedArgs & {
     data?: unknown;
     params?: QueryParams;
   }): Promise<TResponse>;
@@ -273,16 +246,9 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
    *   data: { source: 'csv', items: [...] },
    * });
    */
-  invokeRoute<TResponse = unknown>({
-    token,
-    organizationId,
-    method,
-    path,
-    data,
-    params,
-    options
-  }: ScopedArgs & {
-    method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'; /** Path relative to the resource baseUrl. Leading slash optional. */
+  invokeRoute<TResponse = unknown>({ token, organizationId, method, path, data, params, options }: ScopedArgs & {
+    method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+    /** Path relative to the resource baseUrl. Leading slash optional. */
     path: string;
     data?: unknown;
     params?: QueryParams;
@@ -296,14 +262,9 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
    *   filter: { from: '2025-01-01', to: '2025-12-31' },
    * });
    */
-  aggregate<TRow extends AggRow = AggRow>({
-    token,
-    organizationId,
-    name,
-    filter,
-    options
-  }: ScopedArgs & {
-    /** Aggregation name as declared on the resource. */name: string;
+  aggregate<TRow extends AggRow = AggRow>({ token, organizationId, name, filter, options }: ScopedArgs & {
+    /** Aggregation name as declared on the resource. */
+    name: string;
     /**
      * URL-encoded filter narrows + dimension args. Reserved keys (`page`,
      * `limit`, etc.) are stripped server-side; everything else flows into
@@ -311,14 +272,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
      */
     filter?: Record<string, unknown>;
   }): Promise<AggResult<TRow>>;
-  dispatchAction<TResult = unknown, TBody extends Record<string, unknown> = Record<string, unknown>>({
-    token,
-    organizationId,
-    id,
-    action,
-    data,
-    options
-  }: ScopedArgs & {
+  dispatchAction<TResult = unknown, TBody extends Record<string, unknown> = Record<string, unknown>>({ token, organizationId, id, action, data, options }: ScopedArgs & {
     id: string;
     action: string;
     data?: TBody;

package/dist/api.js

@@ -1,6 +1,12 @@
 import { createQueryString, handleApiRequest } from "./client.js";
+import { STANDARD_RESERVED_PARAMS } from "@classytic/repo-core/query-parser";
 
 //#region src/api.ts
+for (const verb of [
+	"_count",
+	"_exists",
+	"_distinct"
+]) if (!STANDARD_RESERVED_PARAMS.has(verb)) throw new Error(`[arc-next] dispatch verb '${verb}' is not in repo-core STANDARD_RESERVED_PARAMS`);
 var BaseApi = class {
 	entity;
 	config;
@@ -8,7 +14,8 @@ var BaseApi = class {
 	requestFn;
 	constructor(entity, config = {}) {
 		this.entity = entity;
-		this.requestFn = config.client?.request ?? handleApiRequest;
+		const client = config.client;
+		this.requestFn = typeof client === "function" ? (method, endpoint, options) => client().request(method, endpoint, options) : client?.request ?? handleApiRequest;
 		this.config = {
 			basePath: config.basePath ?? "/api/v1",
 			defaultParams: {
@@ -62,6 +69,13 @@ var BaseApi = class {
 	prepareParams(params = {}) {
 		const result = {};
 		const CRITICAL_FILTERS = ["organizationId", "ownerId"];
+		if (params.cursor !== void 0) {
+			const { cursor, ...rest } = params;
+			params = params.after !== void 0 ? rest : {
+				...rest,
+				after: cursor
+			};
+		}
 		Object.entries(params).forEach(([key, value]) => {
 			if (CRITICAL_FILTERS.includes(key)) {
 				result[key] = value || null;
@@ -84,7 +98,7 @@ var BaseApi = class {
 				});
 				return;
 			}
-			if (value !== void 0 && value !== "") if (["page", "limit"].includes(key)) result[key] = parseInt(String(value)) || (key === "page" ? 1 : 10);
+			if (value !== void 0 && value !== "") if (["page", "limit"].includes(key)) result[key] = parseInt(String(value), 10) || (key === "page" ? 1 : 10);
 			else if (Array.isArray(value)) {
 				if (/\[([^\]]+)\]$/.test(key)) result[key] = value.join(",");
 				else if (value.length > 1) result[`${key}[in]`] = value.join(",");

package/dist/cache.d.ts

@@ -1,9 +1,8 @@
 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;
+  method: "offset" | "keyset" | "aggregate" | null;
   total: number;
   pages: number;
   page: number;
@@ -21,16 +20,20 @@ declare const DEFAULT_QUERY_CONFIG: {
 };
 /** Pre-built query config presets for common data freshness patterns. */
 declare const QUERY_CONFIGS: {
-  /** Live data: 20s stale, 30s polling */readonly realtime: {
+  /** Live data: 20s stale, 30s polling */
+  readonly realtime: {
     readonly staleTime: 20000;
     readonly refetchInterval: 30000;
-  }; /** Frequently updated: 60s stale */
+  };
+  /** Frequently updated: 60s stale */
   readonly frequent: {
     readonly staleTime: 60000;
-  }; /** Stable data: 5min stale (same as default) */
+  };
+  /** Stable data: 5min stale (same as default) */
   readonly stable: {
     readonly staleTime: 300000;
-  }; /** Rarely changes: 10min stale */
+  };
+  /** Rarely changes: 10min stale */
   readonly static: {
     readonly staleTime: 600000;
   };
@@ -65,6 +68,24 @@ declare function extractItem<T>(data: unknown): T | null;
  * the array length changes.
  */
 declare function updateListCache<T>(listData: unknown, updater: (items: T[]) => T[]): unknown;
+/**
+ * Insert an item at the head of a list cache entry — the optimistic-create
+ * primitive. Unlike {@link updateListCache} with a prepending updater (which,
+ * on an infinite cache, would insert into EVERY page), this targets exactly
+ * one location: the first page of an infinite cache, or the single payload of
+ * a flat list. Totals adjust via `updateListCache`'s existing delta logic.
+ */
+declare function prependToListCache(listData: unknown, item: unknown): unknown;
+/**
+ * Replace an item (matched by id) across a list cache entry — the
+ * temp-ID-reconciliation primitive. After a create succeeds, the optimistic
+ * placeholder (`temp-…` id) is swapped for the server document in place, so
+ * the UI keeps the row (no flicker) while the id becomes real. Works on flat
+ * and infinite shapes via {@link updateListCache}.
+ */
+declare function replaceItemInListCache(listData: unknown, matchId: string, replacement: unknown, opts?: {
+  idField?: string;
+}): unknown;
 /**
  * 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
@@ -163,4 +184,4 @@ interface CacheUtils<T> {
  */
 declare function createCacheUtils<T>(KEYS: QueryKeys): CacheUtils<T>;
 //#endregion
-export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache, withOrgParams };
+export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, prependToListCache, replaceItemInListCache, syncDetailToLists, updateListCache, withOrgParams };

package/dist/cache.js

@@ -101,6 +101,18 @@ function updateListCache(listData, updater) {
 	if (Array.isArray(listData)) return updater(listData);
 	if (typeof listData !== "object") return listData;
 	const d = listData;
+	if (Array.isArray(d.pages) && Array.isArray(d.pageParams)) {
+		let changed = false;
+		const nextPages = d.pages.map((page) => {
+			const next = updateListCache(page, updater);
+			if (next !== page) changed = true;
+			return next;
+		});
+		return changed ? {
+			...d,
+			pages: nextPages
+		} : listData;
+	}
 	let arrayField = null;
 	for (const key of LIST_KEYS) if (Array.isArray(d[key])) {
 		arrayField = key;
@@ -127,6 +139,45 @@ function updateListCache(listData, updater) {
 	}
 	return result;
 }
+/**
+* Insert an item at the head of a list cache entry — the optimistic-create
+* primitive. Unlike {@link updateListCache} with a prepending updater (which,
+* on an infinite cache, would insert into EVERY page), this targets exactly
+* one location: the first page of an infinite cache, or the single payload of
+* a flat list. Totals adjust via `updateListCache`'s existing delta logic.
+*/
+function prependToListCache(listData, item) {
+	if (!listData) return listData;
+	if (typeof listData === "object" && !Array.isArray(listData) && Array.isArray(listData.pages) && Array.isArray(listData.pageParams)) {
+		const d = listData;
+		if (d.pages.length === 0) return listData;
+		const first = updateListCache(d.pages[0], (items) => [item, ...items || []]);
+		if (first === d.pages[0]) return listData;
+		return {
+			...d,
+			pages: [first, ...d.pages.slice(1)]
+		};
+	}
+	return updateListCache(listData, (items) => [item, ...items || []]);
+}
+/**
+* Replace an item (matched by id) across a list cache entry — the
+* temp-ID-reconciliation primitive. After a create succeeds, the optimistic
+* placeholder (`temp-…` id) is swapped for the server document in place, so
+* the UI keeps the row (no flicker) while the id becomes real. Works on flat
+* and infinite shapes via {@link updateListCache}.
+*/
+function replaceItemInListCache(listData, matchId, replacement, opts = {}) {
+	return updateListCache(listData, (items) => {
+		let changed = false;
+		const next = items.map((item) => {
+			if ((opts.idField ? String(item?.[opts.idField] ?? "") || getItemId(item) : getItemId(item)) !== matchId) return item;
+			changed = true;
+			return replacement;
+		});
+		return changed ? next : items;
+	});
+}
 /** Item-identity helper that respects a custom idField, falling back to `_id` / `id`. */
 function resolveId(item, idField) {
 	if (!item || typeof item !== "object") return null;
@@ -320,4 +371,4 @@ function createCacheUtils(KEYS) {
 }
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache, withOrgParams };
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, prependToListCache, replaceItemInListCache, syncDetailToLists, updateListCache, withOrgParams };