API Slices: Cache Management Utilities

The API slice object includes cache management utilities that are used for implementing optimistic updates. These are included in a util field inside the slice object.

updateQueryResult

Signature

const updateQueryResult = (
endpointName: string,
args: any,
updateRecipe: (draft: Draft<CachedState>) => void
) => ThunkAction<PatchCollection, PartialState, any, AnyAction>;
interface PatchCollection {
patches: Patch[];
inversePatches: Patch[];
}
  • Parameters
    • endpointName: a string matching an existing endpoint name
    • args: a cache key, used to determine which cached dataset needs to be updated
    • updateRecipe: an Immer produce callback that can apply changes to the cached state

Description

A Redux thunk action creator that, when dispatched, creates and applies a set of JSON diff/patch objects to the current state. This immediately updates the Redux state with those changes.

The thunk action creator accepts three arguments: the name of the endpoint we are updating (such as 'getPost'), any relevant query arguments, and a callback function. The callback receives an Immer-wrapped draft of the current state, and may modify the draft to match the expected results after the mutation completes successfully.

The thunk returns an object containing {patches: Patch[], inversePatches: Patch[]}, generated using Immer's produceWithPatches method.

This is typically used as the first step in implementing optimistic updates. The generated inversePatches can be passed between the onStart and onError callbacks in a mutation definition by assigning the inversePatches array to the provided context object, and then the updates can be reverted by calling patchQueryResult(endpointName, args, inversePatches).

patchQueryResult

Signature

const patchQueryResult = (
endpointName: string,
args: any
patches: Patch[]
) => ThunkAction<void, PartialState, any, AnyAction>;

A Redux thunk that applies a JSON diff/patch array to the cached data for a given query result. This immediately updates the Redux state with those changes.

The thunk accepts three arguments: the name of the endpoint we are updating (such as 'getPost'), any relevant query arguments, and a JSON diff/patch array as produced by Immer's produceWithPatches.

This is typically used as the second step in implementing optimistic updates. If a request fails, the optimistically-applied changes can be reverted by dispatching patchQueryResult with the inversePatches that were generated by updateQueryResult earlier.

prefetch

Signature

type PrefetchOptions = { ifOlderThan?: false | number } | { force?: boolean };
const prefetch = (
endpointName: string,
arg: any,
options: PrefetchOptions
) => ThunkAction<void, any, any, AnyAction>;

Description

A Redux thunk that can be used to manually trigger pre-fetching of data.

The thunk accepts three arguments: the name of the endpoint we are updating (such as 'getPost'), any relevant query arguments, and a set of options used to determine if the data actually should be re-fetched based on cache staleness.

React Hooks users will most likely never need to use this directly, as the usePrefetch hook will dispatch this thunk internally as needed when you call the prefetching function supplied by the hook.

Edit this page