atomic-query

Idiomatic composition recipes for `@mongez/atomic-query` — optimistic updates with rollback, list mutation + invalidation, infinite scroll wiring, prefetch on hover, SSR data hand-off via `<HydrateQueries>`, suspense-driven detail pages, and segment-aware cross-query invalidation. TRIGGER when: code combines `useQuery`, `useMutation`, `useInfiniteQuery`, `useSuspenseQuery`, `<HydrateQueries>`, or `queryClient` across more than one component; user asks "show me an end-to-end optimistic update", "how do I prefetch on hover", "SSR hand-off with atomic-query", "infinite scroll integration", or "how do I invalidate multiple queries at once". SKIP: single-feature dives — load `mongez-atomic-query-queries`, `mongez-atomic-query-mutations`, `mongez-atomic-query-infinite`, `mongez-atomic-query-invalidation`, `mongez-atomic-query-suspense`, `mongez-atomic-query-ssr`, or `mongez-atomic-query-cache` instead; vanilla `@mongez/atom` state without a server-data layer (use `mongez-atom-recipes`); React-Query interop — patter

What @mongez/atomic-query is, how it relates to @mongez/react-atom, and when to reach for it instead of TanStack Query. TRIGGER when: code imports `queryAtom` or `HydrateQueries` from `@mongez/atomic-query` for the first time in a project; user asks "what is @mongez/atomic-query / should I use it / how is it different from TanStack Query / how does it fit with @mongez/atom / why is it client-only"; typical import `import { queryAtom } from "@mongez/atomic-query"`. SKIP: concrete hook usage (`useQuery`, `useMutation`, `useInfiniteQuery`, `useSuspenseQuery`) — use the matching task-specific skill; cache management — use `mongez-atomic-query-cache` or `mongez-atomic-query-invalidation`; SSR seeding mechanics — use `mongez-atomic-query-ssr`; list/array helpers — use `mongez-atomic-query-list-helpers`.

How to use queryAtom.useQuery — options, return shape, granular field hooks, suspense mode, and cache key serialisation rules. TRIGGER when: code imports `queryAtom`, `useQuery`, `useSuspenseQuery`, `useLoadChange`, `useErrorChange`, `useDataChange`, `useQueryChange`, `onQueryChange`, `getData`, `getQuery`, or `invalidate` from `@mongez/atomic-query`; user asks "how do I fetch data / write a useQuery / configure staleTime / avoid unnecessary re-renders / subscribe to one field"; typical import `import { queryAtom } from "@mongez/atomic-query"`. SKIP: write-side operations (POST/PUT/DELETE) — use `mongez-atomic-query-mutations`; cache invalidation and refetch patterns — use `mongez-atomic-query-invalidation` or `mongez-atomic-query-cache`; cursor/page-based pagination — use `mongez-atomic-query-infinite`; server-side seeding via `<HydrateQueries>` — use `mongez-atomic-query-ssr`; suspense-only `useSuspenseQuery` deep-dives — use `mongez-atomic-query-suspense`.

All cache management operations in @mongez/atomic-query — invalidation, refetch, optimistic writes, seeding, direct reads, destruction, GC, and non-React subscriptions. TRIGGER when: code imports `invalidate`, `invalidateAll`, `invalidateBackground`, `invalidateBackgroundAll`, `refetchQuery`, `refetchMultipleQueries`, `refetchQueryBackground`, `refetchMultipleQueriesBackground`, `updateQueryData`, `seedQuery`, `getQuery`, `getData`, `isStale`, `destroyQuery`, `clearCache`, `garbageCollect`, `limitCacheSize`, `getCacheStats`, `setupAutoGC`, or `onQueryChange` from `@mongez/atomic-query`; user asks "how do I read/write/expire the cache without a hook / invalidate after a mutation / configure GC"; typical import `import { queryAtom, invalidate, updateQueryData } from "@mongez/atomic-query"`. SKIP: writing `useQuery`/`useSuspenseQuery` calls — use `mongez-atomic-query-basic-query` or `mongez-atomic-query-queries`; running mutations (POST/PUT/PATCH/DELETE) — use `mongez-atomic-query-mutations`; array-shaped helper

How to use useInfiniteQuery for cursor-based and offset-based paginated lists, including fetchNextPage, hasNextPage, and invalidation behavior. TRIGGER when: code imports `useInfiniteQuery`, `InfiniteQueryData`, `InfiniteQueryFnContext`, `UseInfiniteQueryOptions`, or `UseInfiniteQueryResult` from `@mongez/atomic-query`, or calls `fetchNextPage`, `getNextPageParam`, `hasNextPage`, or `isFetchingNextPage`; user asks "how do I implement infinite scroll / load more / cursor pagination / offset pagination"; typical import `import { useInfiniteQuery } from "@mongez/atomic-query"`. SKIP: single-page `useQuery` calls — use `mongez-atomic-query-basic-query` or `mongez-atomic-query-queries`; mutating cached array values via `push`/`unshift`/`remove`/`sort` — use `mongez-atomic-query-list-helpers`; write-side mutations — use `mongez-atomic-query-mutations`.

How to invalidate cached queries (prefix and exact match), refetch on demand, seed from a server loader, and manage cache lifecycle (GC, destroy, stats). TRIGGER when: code imports `invalidate`, `invalidateAll`, `invalidateBackground`, `invalidateBackgroundAll`, `refetchQuery`, `refetchMultipleQueries`, `refetchQueryBackground`, `refetchMultipleQueriesBackground`, `seedQuery`, `HydrateQueries`, `destroyQuery`, `clearCache`, `garbageCollect`, `limitCacheSize`, `getCacheStats`, `setupAutoGC`, `getQuery`, `getData`, or `isStale` from `@mongez/atomic-query`; user asks "how do I force a refetch after a mutation / invalidate a group of queries / seed cache from loader / configure GC"; typical import `import { queryAtom, invalidate } from "@mongez/atomic-query"`. SKIP: pure cache-API reference (no invalidation framing) — use `mongez-atomic-query-cache`; defining the `useQuery` hook itself — use `mongez-atomic-query-basic-query` or `mongez-atomic-query-queries`; SSR boundary integration with framework loaders — use `

Array mutation helpers on queryAtom (push, unshift, pop, shift, replace, remove, removeByIndex, clear, sort, reverse) that update a cached array value in-place without triggering a refetch. TRIGGER when: code imports `push`, `unshift`, `pop`, `shift`, `replace`, `remove`, `removeByIndex`, `clear`, `sort`, or `reverse` from `@mongez/atomic-query`, or calls `queryAtom.push`/`queryAtom.remove`/`queryAtom.sort` etc.; user asks "how do I append/prepend/remove/reorder items in a cached list without refetching"; typical import `import { queryAtom, push, remove } from "@mongez/atomic-query"`. SKIP: cursor/offset pagination via `useInfiniteQuery` — use `mongez-atomic-query-infinite`; full-replacement optimistic writes via `updateQueryData` — use `mongez-atomic-query-mutations` or `mongez-atomic-query-cache`; invalidating instead of mutating — use `mongez-atomic-query-invalidation`; native `Array.prototype` work that doesn't go through `queryAtom`.

Built-in array helpers (push, unshift, pop, shift, replace, remove, removeByIndex, clear, sort, reverse) for queries that hold a list, plus useInfiniteQuery for cursor/page-based pagination. TRIGGER when: code imports `push`, `unshift`, `pop`, `shift`, `replace`, `remove`, `removeByIndex`, `clear`, `sort`, `reverse`, `useInfiniteQuery`, `updateQueryData`, `fetchNextPage`, or `getNextPageParam` from `@mongez/atomic-query`; user asks "how do I work with a list-shaped query / append after create / remove after delete / paginate / load more"; typical import `import { queryAtom, useInfiniteQuery, push } from "@mongez/atomic-query"`. SKIP: pure array-helper reference (no pagination context) — use `mongez-atomic-query-list-helpers`; deep `useInfiniteQuery` mechanics only — use `mongez-atomic-query-infinite`; non-list `useQuery` calls — use `mongez-atomic-query-basic-query` or `mongez-atomic-query-queries`; write-side `useMutation` hooks — use `mongez-atomic-query-mutations`.

How to use useMutation for write-side operations, including optimistic updates with onMutate/onError rollback and direct cache writes with updateQueryData. TRIGGER when: code imports `useMutation`, `updateQueryData`, `UseMutationOptions`, `UseMutationResult`, or `MutationStatus` from `@mongez/atomic-query`, or references `mutate`, `mutateAsync`, `onMutate`, `onSuccess`, `onError`, `onSettled`, `isPending`, or `reset` in a mutation context; user asks "how do I POST / PUT / PATCH / DELETE / do an optimistic update / roll back on error / write to the cache without refetching"; typical import `import { useMutation, queryAtom } from "@mongez/atomic-query"`. SKIP: read-side `useQuery` calls — use `mongez-atomic-query-basic-query` or `mongez-atomic-query-queries`; forcing a refetch after a mutation completes — use `mongez-atomic-query-invalidation`; array-shaped helpers `push`/`remove`/`sort` for list updates — use `mongez-atomic-query-list-helpers`; cache lifecycle/GC questions — use `mongez-atomic-query-cache`.

Full reference for queryAtom.useQuery — all options, the Query<T> return shape, retry configuration, window-focus/reconnect refetch, granular field subscriptions, key hashing, and abort behavior. TRIGGER when: code imports `useQuery`, `queryAtom`, `useLoadChange`, `useDataChange`, `useErrorChange`, `useQueryChange`, `Query`, `QueryKey`, `QueryState`, or `AddQueryOptions` from `@mongez/atomic-query`; user asks "how does useQuery work / what's in Query<T> / what is staleTime vs gcTime / how does retry / refetchOnWindowFocus work / how are query keys hashed"; typical import `import { queryAtom, useQuery } from "@mongez/atomic-query"`. SKIP: quick-start framing for first-time users — use `mongez-atomic-query-basic-query`; suspense-mode behavior — use `mongez-atomic-query-suspense`; write-side mutations — use `mongez-atomic-query-mutations`; invalidation/refetch patterns — use `mongez-atomic-query-invalidation` or `mongez-atomic-query-cache`; cursor/page-based pagination — use `mongez-atomic-query-infinite`.

How to seed the @mongez/atomic-query client cache from server-side data using HydrateQueries, with examples for Next.js App Router, Remix, and TanStack Start. TRIGGER when: code imports `HydrateQueries`, `seedQuery`, `SeedEntry`, or `HydrateQueriesProps` from `@mongez/atomic-query`; user asks "how do I SSR with atomic-query / seed cache from Next.js server component / hydrate from a Remix loader / prefetch on hover"; typical import `import { HydrateQueries } from "@mongez/atomic-query"`. SKIP: pure client-side `useQuery` usage — use `mongez-atomic-query-basic-query` or `mongez-atomic-query-queries`; cache invalidation/refetch after first paint — use `mongez-atomic-query-invalidation`; suspense rendering boundaries — use `mongez-atomic-query-suspense`; non-SSR cache-API questions — use `mongez-atomic-query-cache`.

How to use useSuspenseQuery from @mongez/atomic-query to suspend a React subtree while a query loads, including ErrorBoundary pairing and behavioral gotchas. TRIGGER when: code imports `useSuspenseQuery` from `@mongez/atomic-query`, or uses it together with `<Suspense>` and `ErrorBoundary`; user asks "how do I use React Suspense with atomic-query / get data typed as non-undefined / pair Suspense with ErrorBoundary"; typical import `import { useSuspenseQuery } from "@mongez/atomic-query"`. SKIP: plain non-suspense `useQuery` usage — use `mongez-atomic-query-basic-query` or `mongez-atomic-query-queries`; SSR streaming / server-component-driven loading — use `mongez-atomic-query-ssr`; write-side mutations — use `mongez-atomic-query-mutations`; cache invalidation triggered while suspended — use `mongez-atomic-query-invalidation`.