QueryResult

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

Result from createQuery

Includes useQuery hook that:

• Supports enabled option for conditional fetching
• Data may be undefined during loading
• Uses regular useQuery with manual loading state handling

Extends

• BaseQueryResult<TQueryFnData, TSelected, TError>

Type Parameters

TQueryFnData

TQueryFnData

The raw data type

TSelected

TSelected = TQueryFnData

The type after select transformation

TError

TError = Error

The error type

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)

Inherited from

BaseQueryResult.cancel

---

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>

Inherited from

BaseQueryResult.reset

---

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(),
})

Inherited from

BaseQueryResult.optimisticUpdate

---

fetch

fetch: () => Promise<TSelected>

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

Fetch data in loader (uses ensureQueryData for cache-first)

Returns

Promise<TSelected>

Inherited from

BaseQueryResult.fetch

---

prefetch

prefetch: () => Promise<void>

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

Eagerly prefetch data into the cache without blocking. Useful for preloading data before navigating to a route.

Unlike fetch(), this returns a void promise so it can be fire-and-forget. It never rejects: after a failed fetch the cached data is left as it was.

A sign-in or sign-out while it is in flight cancels the fetch, so the previous principal’s answer is never cached, and it runs again for the principal signed in, as fetch() does. When that run succeeds, the cache holds that principal’s answer by the time the promise resolves.

Returns

Promise<void>

Example

// In a route hover handler
button.addEventListener("mouseenter", () => userQuery.prefetch())

Inherited from

BaseQueryResult.prefetch

---

invalidate

invalidate: () => Promise<void>

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

Invalidate the cache (refetches if query is active)

Returns

Promise<void>

Inherited from

BaseQueryResult.invalidate

---

getQueryKey

getQueryKey: () => readonly unknown[]

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

Get query key (for advanced React Query usage)

Returns

readonly unknown[]

Inherited from

BaseQueryResult.getQueryKey

---

getCacheData

getCacheData: {(): TSelected | undefined; <TFinal>(select): TFinal | undefined; }

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

Read data directly from cache without fetching. Returns undefined if data is not in cache.

Call Signature

(): TSelected | undefined

Returns

TSelected | undefined

Call Signature

<TFinal>(select): TFinal | undefined

Type Parameters

TFinal

TFinal

Parameters

select

(data) => TFinal

Returns

TFinal | undefined

Template

TFinal

Type returned after optional select transformation

Param

select

Optional select function to transform cached data further

Returns

Cached data with select applied, or undefined if not in cache

Example

// Just get the cached data
const user = userQuery.getCacheData()

// With additional select transformation
const name = userQuery.getCacheData((user) => user.name)

Inherited from

BaseQueryResult.getCacheData

---

setData

setData: (updater) => TQueryFnData | undefined

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

Write raw data directly into the cache (useful for optimistic updates). Accepts a new value or an updater function that receives the current cached raw data.

Note: The value is stored as raw (pre-select) data. Any active select transformations are automatically re-applied by React Query on the next render.

Parameters

updater

TQueryFnData | ((old) => TQueryFnData | undefined)

Returns

TQueryFnData | undefined

Example

// Optimistic update before a mutation
userQuery.setData({ id: "1", name: "Alice" })

// Functional update
counterQuery.setData((prev) => (prev ?? 0) + 1)

Inherited from

BaseQueryResult.setData

---

useQuery

useQuery: UseQueryWithSelect<TQueryFnData, TSelected, TError>

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

React hook for components - supports chained select and enabled option