# QueryCacheControls

Defined in: [react/src/types.ts:330](https://github.com/B3Pay/ic-reactor/blob/f1956947ae037304fce1675a38695964c1aa9e32/packages/react/src/types.ts#L330)

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`](https://ic-reactor.b3pay.net/v3/libs/interfaces/infinitequeryresult/)
- [`SuspenseInfiniteQueryResult`](https://ic-reactor.b3pay.net/v3/libs/interfaces/suspenseinfinitequeryresult/)
- [`BaseQueryResult`](https://ic-reactor.b3pay.net/v3/libs/interfaces/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](https://github.com/B3Pay/ic-reactor/blob/f1956947ae037304fce1675a38695964c1aa9e32/packages/react/src/types.ts#L343)

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

```typescript
// 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](https://github.com/B3Pay/ic-reactor/blob/f1956947ae037304fce1675a38695964c1aa9e32/packages/react/src/types.ts#L357)

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

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

***

### optimisticUpdate

> **optimisticUpdate**: (`updater`) => `Promise`\<[`OptimisticRollback`](https://ic-reactor.b3pay.net/v3/libs/interfaces/optimisticrollback/)\>

Defined in: [react/src/types.ts:398](https://github.com/B3Pay/ic-reactor/blob/f1956947ae037304fce1675a38695964c1aa9e32/packages/react/src/types.ts#L398)

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`](https://ic-reactor.b3pay.net/v3/libs/interfaces/optimisticrollback/)\>

#### Example

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