API reference > @kontsedal/olas-persist > persistQueryCachePlugin

persistQueryCachePlugin() function

Persist the query cache across reloads. The plugin stores each opted-in entry's server truth, throttled, and restores the stored cache when the root starts. Server truth is what dehydrate() would ship: while an optimistic write is live, the data beneath it, so a guess is never stored, whichever write carried it, and a committed one is. An entry the cache garbage-collects is dropped from storage too.

const user = defineQuery({ id: 'user', key: () => [], fetcher, meta: { persist: true } })

createRoot(app, { deps, queries: queryEngine(), plugins: [persistQueryCachePlugin()] })

With synchronous storage (the default, localStorage) the restore happens during setup, before any controller subscribes, so a restored entry is there on the first read. With asynchronous storage the restore lands later. It fills only entries nothing has subscribed to yet, and never overwrites one a fetch is already filling. root.waitForIdle() waits for it. AwaitrestoreQueryCache before createRoot instead when the first render must see the restored data.

Every storage write carries the whole cache, and every tab of the app writes the same key. So each write reads what storage holds first and merges this session's writes into it. An entry this session never binds stays in storage until it passes maxAgeMs, and so does an entry another tab wrote. When both hold a copy of one entry, the one with the newerlastUpdatedAt is kept. A read that fails holds the write: the next write reads storage again, and writes once a read lands. A session whose reads all fail writes nothing, because its write would delete the entries it could not read.

The read and the write are two steps, not one transaction. Two tabs that write in the same moment can each miss the other's newest entry. The next write of the tab that lost it puts it back, since each write carries every entry its tab wrote.

Signature:

export declare function persistQueryCachePlugin(options?: PersistQueryCacheOptions): OlasPlugin;

Parameters

Parameter	Type	Description
options	PersistQueryCacheOptions	(Optional)

Returns:

OlasPlugin