experimental_createQueryPersister

Installation

Dieses Dienstprogramm ist Teil eines separaten Pakets und unter dem Import '@tanstack/query-persist-client-core' verfügbar.

bash

npm install @tanstack/query-persist-client-core

npm install @tanstack/query-persist-client-core

oder

bash

pnpm add @tanstack/query-persist-client-core

pnpm add @tanstack/query-persist-client-core

oder

bash

yarn add @tanstack/query-persist-client-core

yarn add @tanstack/query-persist-client-core

oder

bash

bun add @tanstack/query-persist-client-core

bun add @tanstack/query-persist-client-core

Hinweis: Dieses Hilfsprogramm ist auch im Paket @tanstack/solid-query-persist-client enthalten, sodass Sie es nicht separat installieren müssen, wenn Sie dieses Paket verwenden.

Verwendung

Importieren Sie die Funktion experimental_createQueryPersister
Erstellen Sie einen neuen experimental_createQueryPersister
- Sie können ihm jeden Speicher übergeben, der der AsyncStorage-Schnittstelle entspricht - das folgende Beispiel verwendet den Async-Storage von React Native.
Übergeben Sie diesen Persister als Option an Ihre Abfrage. Dies kann entweder geschehen, indem Sie ihn an die Standardoptionen des QueryClient übergeben oder an eine beliebige Instanz des useQuery-Hooks.
- Wenn Sie diesen Persister als Standardoptionen übergeben, werden alle Abfragen im bereitgestellten Speicher gespeichert. Sie können dies zusätzlich einschränken, indem Sie Filter übergeben. Im Gegensatz zum persistClient-Plugin wird hier nicht der gesamte QueryClient als einzelnes Element gespeichert, sondern jede Abfrage separat. Als Schlüssel wird der Query-Hash verwendet.
- Wenn Sie diesen Persister einem einzelnen useQuery-Hook übergeben, wird nur diese Abfrage gespeichert.
Hinweis: queryClient.setQueryData() Operationen werden nicht gespeichert. Das bedeutet, dass, wenn Sie ein optimistisches Update durchführen und die Seite aktualisieren, bevor die Abfrage ungültig gemacht wurde, Ihre Änderungen an den Abfragedaten verloren gehen. Siehe https://github.com/TanStack/query/issues/6310

Auf diese Weise müssen Sie nicht den gesamten QueryClient speichern, sondern können wählen, was in Ihrer Anwendung gespeichert werden soll. Jede Abfrage wird lazy wiederhergestellt (wenn die Abfrage zum ersten Mal verwendet wird) und gespeichert (nach jedem Durchlauf der queryFn), sodass sie nicht gedrosselt werden muss. staleTime wird auch nach der Wiederherstellung der Abfrage berücksichtigt. Wenn Daten als stale gelten, werden sie sofort nach der Wiederherstellung neu abgerufen. Wenn Daten fresh sind, wird die queryFn nicht ausgeführt.

Das Garbage Collecting einer Abfrage aus dem Speicher hat **keine** Auswirkung auf die gespeicherten Daten. Das bedeutet, Abfragen können für kürzere Zeit im Speicher gehalten werden, um **speichereffizienter** zu sein. Wenn sie das nächste Mal verwendet werden, werden sie einfach wieder aus dem persistenten Speicher wiederhergestellt.

tsx

import AsyncStorage from '@react-native-async-storage/async-storage'
import { QueryClient } from '@tanstack/solid-query'
import { experimental_createQueryPersister } from '@tanstack/query-persist-client-core'

const persister = experimental_createQueryPersister({
  storage: AsyncStorage,
  maxAge: 1000 * 60 * 60 * 12, // 12 hours
})

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 30, // 30 seconds
      persister: persister.persisterFn,
    },
  },
})

import AsyncStorage from '@react-native-async-storage/async-storage'
import { QueryClient } from '@tanstack/solid-query'
import { experimental_createQueryPersister } from '@tanstack/query-persist-client-core'

const persister = experimental_createQueryPersister({
  storage: AsyncStorage,
  maxAge: 1000 * 60 * 60 * 12, // 12 hours
})

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 30, // 30 seconds
      persister: persister.persisterFn,
    },
  },
})

Angepasste Standardwerte

Das createPersister-Plugin wickelt technisch die queryFn ein, sodass es nicht wiederhergestellt wird, wenn die queryFn nicht ausgeführt wird. Auf diese Weise fungiert es als Caching-Schicht zwischen der Abfrage und dem Netzwerk. Daher ist der networkMode standardmäßig auf 'offlineFirst' gesetzt, wenn ein Persister verwendet wird, sodass die Wiederherstellung aus dem persistenten Speicher auch dann erfolgen kann, wenn keine Netzwerkverbindung besteht.

Zusätzliche Hilfsprogramme

Das Aufrufen von experimental_createQueryPersister gibt zusätzlich zu persisterFn weitere Hilfsprogramme für eine einfachere Implementierung von benutzerdefinierten Funktionalitäten zurück.

persistQueryByKey(queryKey: QueryKey, queryClient: QueryClient): Promise<void>

Diese Funktion speichert Query im Speicher und verwendet den beim Erstellen des Persisters definierten Schlüssel.
Dieses Hilfsprogramm kann zusammen mit setQueryData verwendet werden, um optimistische Updates im Speicher zu speichern, ohne auf die Invalidierung zu warten.

tsx

const persister = experimental_createQueryPersister({
  storage: AsyncStorage,
  maxAge: 1000 * 60 * 60 * 12, // 12 hours
})

const queryClient = useQueryClient()

useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo) => {
    ...
    // Optimistically update to the new value
    queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
    // And persist it to storage
    persister.persistQueryByKey(['todos'], queryClient)
    ...
  },
})

const persister = experimental_createQueryPersister({
  storage: AsyncStorage,
  maxAge: 1000 * 60 * 60 * 12, // 12 hours
})

const queryClient = useQueryClient()

useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo) => {
    ...
    // Optimistically update to the new value
    queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
    // And persist it to storage
    persister.persistQueryByKey(['todos'], queryClient)
    ...
  },
})

retrieveQuery<T>(queryHash: string): Promise<T | undefined>

Diese Funktion versucht, die gespeicherte Abfrage anhand des queryHash abzurufen.
Wenn eine Abfrage abgelaufen, beschädigt oder fehlerhaft ist, wird sie stattdessen aus dem Speicher entfernt und undefined zurückgegeben.

persisterGc(): Promise<void>

Diese Funktion kann verwendet werden, um den Speicher sporadisch von abgelaufenen, beschädigten oder fehlerhaften Einträgen zu bereinigen.

Damit diese Funktion funktioniert, muss Ihr Speicher eine entries Methode bereitstellen, die ein Schlüssel-Wert-Tupel-Array zurückgibt.
Zum Beispiel Object.entries(localStorage) für localStorage oder entries von idb-keyval.

restoreQueries(queryClient: QueryClient, filters): Promise<void>

Diese Funktion kann verwendet werden, um Abfragen wiederherzustellen, die derzeit vom Persister gespeichert werden.
Zum Beispiel, wenn Ihre App im Offline-Modus startet oder Sie alle oder nur bestimmte Daten aus der vorherigen Sitzung sofort verfügbar haben möchten, ohne einen zwischenzeitlichen loading Status.

Das Filterobjekt unterstützt die folgenden Eigenschaften

queryKey?: QueryKey
- Setzen Sie diese Eigenschaft, um einen Query-Schlüssel für den Abgleich zu definieren.
exact?: boolean
- Wenn Sie nicht inklusiv nach Query-Schlüssel suchen möchten, können Sie die Option exact: true übergeben, um nur die Abfrage mit dem exakten von Ihnen übergebenen Query-Schlüssel zurückzugeben.

API

tsx

experimental_createQueryPersister(options: StoragePersisterOptions)

experimental_createQueryPersister(options: StoragePersisterOptions)

Optionen

tsx

export interface StoragePersisterOptions {
  /** The storage client used for setting and retrieving items from cache.
   * For SSR pass in `undefined`.
   */
  storage: AsyncStorage | Storage | undefined | null
  /**
   * How to serialize the data to storage.
   * @default `JSON.stringify`
   */
  serialize?: (persistedQuery: PersistedQuery) => string
  /**
   * How to deserialize the data from storage.
   * @default `JSON.parse`
   */
  deserialize?: (cachedString: string) => PersistedQuery
  /**
   * A unique string that can be used to forcefully invalidate existing caches,
   * if they do not share the same buster string
   */
  buster?: string
  /**
   * The max-allowed age of the cache in milliseconds.
   * If a persisted cache is found that is older than this
   * time, it will be discarded
   * @default 24 hours
   */
  maxAge?: number
  /**
   * Prefix to be used for storage key.
   * Storage key is a combination of prefix and query hash in a form of `prefix-queryHash`.
   */
  prefix?: string
  /**
   * Filters to narrow down which Queries should be persisted.
   */
  filters?: QueryFilters
}

interface AsyncStorage<TStorageValue = string> {
  getItem: (key: string) => MaybePromise<TStorageValue | undefined | null>
  setItem: (key: string, value: TStorageValue) => MaybePromise<unknown>
  removeItem: (key: string) => MaybePromise<void>
  entries?: () => MaybePromise<Array<[key: string, value: TStorageValue]>>
}

export interface StoragePersisterOptions {
  /** The storage client used for setting and retrieving items from cache.
   * For SSR pass in `undefined`.
   */
  storage: AsyncStorage | Storage | undefined | null
  /**
   * How to serialize the data to storage.
   * @default `JSON.stringify`
   */
  serialize?: (persistedQuery: PersistedQuery) => string
  /**
   * How to deserialize the data from storage.
   * @default `JSON.parse`
   */
  deserialize?: (cachedString: string) => PersistedQuery
  /**
   * A unique string that can be used to forcefully invalidate existing caches,
   * if they do not share the same buster string
   */
  buster?: string
  /**
   * The max-allowed age of the cache in milliseconds.
   * If a persisted cache is found that is older than this
   * time, it will be discarded
   * @default 24 hours
   */
  maxAge?: number
  /**
   * Prefix to be used for storage key.
   * Storage key is a combination of prefix and query hash in a form of `prefix-queryHash`.
   */
  prefix?: string
  /**
   * Filters to narrow down which Queries should be persisted.
   */
  filters?: QueryFilters
}

interface AsyncStorage<TStorageValue = string> {
  getItem: (key: string) => MaybePromise<TStorageValue | undefined | null>
  setItem: (key: string, value: TStorageValue) => MaybePromise<unknown>
  removeItem: (key: string) => MaybePromise<void>
  entries?: () => MaybePromise<Array<[key: string, value: TStorageValue]>>
}

Die Standardoptionen sind

tsx

{
  prefix = 'tanstack-query',
  maxAge = 1000 * 60 * 60 * 24,
  serialize = JSON.stringify,
  deserialize = JSON.parse,
}

{
  prefix = 'tanstack-query',
  maxAge = 1000 * 60 * 60 * 24,
  serialize = JSON.stringify,
  deserialize = JSON.parse,
}

experimental_createQueryPersister

Installation

Verwendung

Angepasste Standardwerte

Zusätzliche Hilfsprogramme

persistQueryByKey(queryKey: QueryKey, queryClient: QueryClient): Promise<void>

retrieveQuery<T>(queryHash: string): Promise<T | undefined>

persisterGc(): Promise<void>

restoreQueries(queryClient: QueryClient, filters): Promise<void>

API

experimental_createQueryPersister

Optionen

Möchten Sie die Dokumentation überspringen?

Möchten Sie die Dokumentation überspringen?