QueryCacheControls

Defined in: react/src/types.ts:330

The operations every query object has on its own cache entry, on the reactor’s QueryClient. They act on that one entry: other args of the same method, and other queries under the same key prefix, are left alone.

Extended by

• InfiniteQueryResult
• SuspenseInfiniteQueryResult
• BaseQueryResult

Type Parameters

TQueryFnData

TQueryFnData

The raw (pre-select) data the entry holds

Properties

cancel

cancel: () => Promise<void>

Defined in: react/src/types.ts:343

Cancel this query’s fetch in flight, if there is one. The entry keeps the value it held before that fetch started, and a later refetch runs as usual.

Returns

Promise<void>

Example

// Before writing to the cache, so an older answer cannot land on top
await postQuery.cancel()
postQuery.setData(draft)

---

reset

reset: () => Promise<void>

Defined in: react/src/types.ts:357

Reset this query’s entry to its initial state, as TanStack Query’s resetQueries does: its data is cleared, or goes back to initialData when one was given. A mounted hook then fetches it again, and a suspense hook suspends until it has. It resolves once that fetch settles.

Returns

Promise<void>

Example

// A reload button that shows the Suspense fallback again
<button onClick={() => void statsQuery.reset()}>Reload</button>

---

optimisticUpdate

optimisticUpdate: (updater) => Promise<OptimisticRollback>

Defined in: react/src/types.ts:398

Replace this query’s cached value for the duration of a mutation, and get back a rollback for when it fails.

It cancels the query’s fetch in flight, so an answer from before the mutation cannot overwrite the new value, then writes what updater returns for the cached value. updater gets and returns the raw, pre-select data. When nothing is cached yet it is not called, nothing is cancelled or written, and rollback() does nothing: there is no value on screen to update, and the query’s own fetch will bring one. The same goes when another principal signs in or out while it cancels, since the cached value is then the previous principal’s.

The fetch it cancels may be a refetch an invalidation or a sign-in started, so refetch the query once the mutation settles, with invalidate() in onSettled or the query in invalidateQueries.

Return it from onMutate, so the rollback reaches onError.

Parameters

updater

(old) => TQueryFnData

The new value, from the cached one. Do not mutate the cached value in place; return a new one.

Returns

Promise<OptimisticRollback>

Example

const getPost = createQueryFactory(backend, { functionName: "getPost" })
const likePost = createMutation(backend, { functionName: "likePost" })

const { mutate } = likePost.useMutation({
  onMutate: ([postId]) =>
    getPost([postId]).optimisticUpdate((post) => ({
      ...post,
      likes: post.likes + 1n,
    })),
  onError: (_error, _args, update) => update?.rollback(),
  // Refetch either way: a call that failed in transit may still have run
  onSettled: (_data, _error, [postId]) => getPost([postId]).invalidate(),
})