@tanstack/query-persist-client-core 5.104.1 → 5.104.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/query-persist-client-core",
-  "version": "5.104.1",
+  "version": "5.104.2",
   "description": "Set of utilities for interacting with persisters, which can save your queryClient for later use",
   "author": "tannerlinsley",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "!src/__tests__"
   ],
   "dependencies": {
-    "@tanstack/query-core": "5.104.1"
+    "@tanstack/query-core": "5.104.2"
   },
   "devDependencies": {
     "@tanstack/query-test-utils": "0.0.0",
@@ -49,14 +49,14 @@
   "scripts": {
     "clean": "premove ./build ./coverage ./dist-ts ./.cache/test-types",
     "compile": "tsc --project tsconfig.json",
-    "test:eslint": "eslint --concurrency=auto ./src",
+    "test:oxlint": "oxlint ./src",
     "test:types": "npm-run-all --serial test:types:*",
-    "test:types:ts56": "node ../../node_modules/typescript56/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts56 --tsBuildInfoFile .cache/test-types/ts56.tsbuildinfo",
     "test:types:ts57": "node ../../node_modules/typescript57/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts57 --tsBuildInfoFile .cache/test-types/ts57.tsbuildinfo",
     "test:types:ts58": "node ../../node_modules/typescript58/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts58 --tsBuildInfoFile .cache/test-types/ts58.tsbuildinfo",
     "test:types:ts59": "node ../../node_modules/typescript59/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts59 --tsBuildInfoFile .cache/test-types/ts59.tsbuildinfo",
     "test:types:tscurrent": "tsc --project tsconfig.json --outDir .cache/test-types/tscurrent --tsBuildInfoFile .cache/test-types/tscurrent.tsbuildinfo",
     "test:types:ts70": "node ../../node_modules/typescript70/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts70 --tsBuildInfoFile .cache/test-types/ts70.tsbuildinfo",
+    "test:types:ts71": "node ../../node_modules/typescript71/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts71 --tsBuildInfoFile .cache/test-types/ts71.tsbuildinfo",
     "test:lib": "vitest",
     "test:lib:dev": "pnpm run test:lib --watch",
     "test:build": "publint --strict && attw --pack",

package/src/createPersister.ts

@@ -13,24 +13,62 @@ import type {
   QueryState,
 } from '@tanstack/query-core'
 
+/**
+ * A single query as stored by {@link experimental_createQueryPersister}.
+ */
 export interface PersistedQuery {
+  /**
+   * The `buster` the query was saved with. Entries with a different `buster` are discarded.
+   */
   buster: string
+  /**
+   * The hash of the query.
+   */
   queryHash: string
+  /**
+   * The key of the query.
+   */
   queryKey: QueryKey
+  /**
+   * The state of the query, including its data and when it was last updated.
+   */
   state: QueryState
 }
 
+/**
+ * A value, or a promise that resolves to it.
+ */
 export type MaybePromise<T> = T | Promise<T>
 
+/**
+ * A key-value storage, such as `localStorage` or `AsyncStorage`, whose methods may be synchronous
+ * or return promises.
+ */
 export interface AsyncStorage<TStorageValue = string> {
+  /**
+   * Reads the value stored under `key`, or `null`/`undefined` if there is none.
+   */
   getItem: (key: string) => MaybePromise<TStorageValue | undefined | null>
+  /**
+   * Stores `value` under `key`.
+   */
   setItem: (key: string, value: TStorageValue) => MaybePromise<unknown>
+  /**
+   * Removes the value stored under `key`.
+   */
   removeItem: (key: string) => MaybePromise<void>
+  /**
+   * Returns all stored key-value pairs. Required for removing expired entries in bulk.
+   */
   entries?: () => MaybePromise<Array<[key: string, value: TStorageValue]>>
 }
 
+/**
+ * Options for {@link experimental_createQueryPersister}.
+ */
 export interface StoragePersisterOptions<TStorageValue = string> {
-  /** The storage client used for setting and retrieving items from cache.
+  /**
+   * The storage client used for setting and retrieving items from cache.
    * For SSR pass in `undefined`.
    */
   storage: AsyncStorage<TStorageValue> | undefined | null
@@ -66,7 +104,6 @@ export interface StoragePersisterOptions<TStorageValue = string> {
    * If set to `true`, the query will refetch on successful query restoration if the data is stale.
    * If set to `false`, the query will not refetch on successful query restoration.
    * If set to `'always'`, the query will always refetch on successful query restoration.
-   *
    * @defaultValue true
    */
   refetchOnRestore?: boolean | 'always'
@@ -85,13 +122,17 @@ export const PERSISTER_KEY_PREFIX = 'tanstack-query'
  *
  * ```
  * useQuery({
-     queryKey: ['myKey'],
-     queryFn: fetcher,
-     persister: createPersister({
-       storage: localStorage,
-     }),
-   })
-   ```
+ *   queryKey: ['myKey'],
+ *   queryFn: fetcher,
+ *   persister: createPersister({
+ *     storage: localStorage,
+ *   }),
+ * })
+ * ```
+ * @param options - The storage to persist to, and the options for serializing, expiring, and
+ * filtering persisted queries.
+ * @returns The `persisterFn` to pass as a query's `persister`, plus functions to persist, retrieve,
+ * restore, remove, and garbage collect persisted queries manually.
  */
 export function experimental_createQueryPersister<TStorageValue = string>({
   storage,
@@ -107,6 +148,12 @@ export function experimental_createQueryPersister<TStorageValue = string>({
   refetchOnRestore = true,
   filters,
 }: StoragePersisterOptions<TStorageValue>) {
+  /**
+   * Checks whether a persisted query should be discarded.
+   * @param persistedQuery - The persisted query to check.
+   * @returns `true` if it has no `dataUpdatedAt`, is older than `maxAge`, or has a different
+   * `buster`.
+   */
   function isExpiredOrBusted(persistedQuery: PersistedQuery) {
     if (persistedQuery.state.dataUpdatedAt) {
       const queryAge = Date.now() - persistedQuery.state.dataUpdatedAt
@@ -123,6 +170,14 @@ export function experimental_createQueryPersister<TStorageValue = string>({
     return true
   }
 
+  /**
+   * Reads the persisted data of a query from storage. Expired, busted, or unreadable entries are
+   * removed instead.
+   * @param queryHash - The hash of the query to read.
+   * @param afterRestoreMacroTask - Scheduled with the persisted query after it is restored.
+   * @returns A promise that resolves with the persisted data, or `undefined` if nothing was
+   * restored.
+   */
   async function retrieveQuery<T>(
     queryHash: string,
     afterRestoreMacroTask?: (persistedQuery: PersistedQuery) => void,
@@ -167,6 +222,12 @@ export function experimental_createQueryPersister<TStorageValue = string>({
     return
   }
 
+  /**
+   * Persists the query with the given key, if it exists in the client's cache.
+   * @param queryKey - The key of the query to persist.
+   * @param queryClient - The client whose cache holds the query.
+   * @returns A promise that resolves once the query is persisted.
+   */
   async function persistQueryByKey(
     queryKey: QueryKey,
     queryClient: QueryClient,
@@ -186,6 +247,11 @@ export function experimental_createQueryPersister<TStorageValue = string>({
     }
   }
 
+  /**
+   * Writes a query's state, key, hash, and `buster` to storage.
+   * @param query - The query to persist.
+   * @returns A promise that resolves once the entry is serialized and written.
+   */
   async function persistQuery(query: Query) {
     if (storage != null) {
       const storageKey = `${prefix}-${query.queryHash}`
@@ -201,6 +267,14 @@ export function experimental_createQueryPersister<TStorageValue = string>({
     }
   }
 
+  /**
+   * The `persister` of a query: restores its data from storage if the query has none yet, otherwise
+   * runs `queryFn` and persists the result.
+   * @param queryFn - The query's own query function.
+   * @param ctx - The context passed to `queryFn`.
+   * @param query - The query being fetched.
+   * @returns A promise that resolves with the restored or fetched data.
+   */
   async function persisterFn<T, TQueryKey extends QueryKey>(
     queryFn: (context: QueryFunctionContext<TQueryKey>) => T | Promise<T>,
     ctx: QueryFunctionContext<TQueryKey>,
@@ -246,6 +320,11 @@ export function experimental_createQueryPersister<TStorageValue = string>({
     return Promise.resolve(queryFnResult)
   }
 
+  /**
+   * Removes expired, busted, or unreadable entries from storage. Requires the storage to implement
+   * `entries`.
+   * @returns A promise that resolves once every entry is checked.
+   */
   async function persisterGc() {
     if (storage?.entries) {
       const storageKeyPrefix = `${prefix}-`
@@ -271,6 +350,14 @@ export function experimental_createQueryPersister<TStorageValue = string>({
     }
   }
 
+  /**
+   * Restores every persisted query matching `filters` into the client's cache with
+   * `queryClient.setQueryData`. Requires the storage to implement `entries`.
+   * @param queryClient - The client to restore the queries into.
+   * @param filters - The `queryKey` and `exact` filters to match. Without them, every query is
+   * restored.
+   * @returns A promise that resolves once every entry is checked.
+   */
   async function restoreQueries(
     queryClient: QueryClient,
     filters: Pick<QueryFilters, 'queryKey' | 'exact'> = {},
@@ -320,6 +407,13 @@ export function experimental_createQueryPersister<TStorageValue = string>({
     }
   }
 
+  /**
+   * Removes every persisted query matching `filters` from storage. Requires the storage to implement
+   * `entries`.
+   * @param filters - The `queryKey` and `exact` filters to match. Without them, every query is
+   * removed.
+   * @returns A promise that resolves once every entry is checked.
+   */
   async function removeQueries(
     filters: Pick<QueryFilters, 'queryKey' | 'exact'> = {},
   ): Promise<void> {

package/src/persist.ts

@@ -7,66 +7,120 @@ import type {
   QueryClient,
 } from '@tanstack/query-core'
 
+/**
+ * A value, or a promise-like that resolves to it.
+ */
 export type Promisable<T> = T | PromiseLike<T>
 
+/**
+ * Saves, restores, and removes a {@link PersistedClient} in a storage.
+ */
 export interface Persister {
+  /**
+   * Saves the persisted client to the storage.
+   */
   persistClient: (persistClient: PersistedClient) => Promisable<void>
+  /**
+   * Reads the persisted client from the storage, or `undefined` if nothing was saved.
+   */
   restoreClient: () => Promisable<PersistedClient | undefined>
+  /**
+   * Removes the persisted client from the storage.
+   */
   removeClient: () => Promisable<void>
 }
 
+/**
+ * The dehydrated state of a `QueryClient` as it is persisted, with the time it was saved and its
+ * `buster`.
+ */
 export interface PersistedClient {
+  /**
+   * When the client was saved, in milliseconds since the epoch. Compared with `maxAge` on restore.
+   */
   timestamp: number
+  /**
+   * The `buster` the client was saved with. A persisted client with a different `buster` is
+   * discarded.
+   */
   buster: string
+  /**
+   * The dehydrated cache of the `QueryClient`.
+   */
   clientState: DehydratedState
 }
 
+/**
+ * The options shared by restoring and saving a persisted `QueryClient`.
+ */
 export interface PersistQueryClientRootOptions {
   /** The QueryClient to persist */
   queryClient: QueryClient
-  /** The Persister interface for storing and restoring the cache
-   * to/from a persisted location */
+  /**
+   * The Persister interface for storing and restoring the cache
+   * to/from a persisted location
+   */
   persister: Persister
-  /** A unique string that can be used to forcefully
-   * invalidate existing caches if they do not share the same buster string */
+  /**
+   * A unique string that can be used to forcefully
+   * invalidate existing caches if they do not share the same buster string
+   */
   buster?: string
 }
 
+/**
+ * Options for restoring a persisted `QueryClient` with {@link persistQueryClientRestore}.
+ */
 export interface PersistedQueryClientRestoreOptions extends PersistQueryClientRootOptions {
-  /** The max-allowed age of the cache in milliseconds.
+  /**
+   * 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 */
+   * time, it will be discarded
+   */
   maxAge?: number
   /** The options passed to the hydrate function */
   hydrateOptions?: HydrateOptions
 }
 
+/**
+ * Options for saving a `QueryClient` with {@link persistQueryClientSave}.
+ */
 export interface PersistedQueryClientSaveOptions extends PersistQueryClientRootOptions {
   /** The options passed to the dehydrate function */
   dehydrateOptions?: DehydrateOptions
 }
 
+/**
+ * Options for {@link persistQueryClient}, which both restores and saves a `QueryClient`.
+ */
 export interface PersistQueryClientOptions
   extends
     PersistedQueryClientRestoreOptions,
     PersistedQueryClientSaveOptions,
     PersistQueryClientRootOptions {}
 
+const cacheEventTypes: Array<NotifyEventType> = ['added', 'removed', 'updated']
+
 /**
  * Checks if emitted event is about cache change and not about observers.
  * Useful for persist, where we only want to trigger save when cache is changed.
+ * @param eventType - The type of the emitted event.
+ * @returns `true` if the event is `'added'`, `'removed'`, or `'updated'`.
  */
-const cacheEventTypes: Array<NotifyEventType> = ['added', 'removed', 'updated']
-
 function isCacheEventType(eventType: NotifyEventType) {
   return cacheEventTypes.includes(eventType)
 }
 
 /**
- * Restores persisted data to the QueryCache
- *  - data obtained from persister.restoreClient
- *  - data is hydrated using hydrateOptions
- * If data is expired, busted, empty, or throws, it runs persister.removeClient
+ * Restores persisted data to the QueryCache.
+ *  - data obtained from persister.restoreClient.
+ *  - data is hydrated using hydrateOptions.
+ * If data is expired, busted, empty, or throws, it runs persister.removeClient.
+ * @param options - The `queryClient` to restore into, the `persister`, and the `maxAge`, `buster`,
+ * and `hydrateOptions` that decide whether and how the persisted data is restored.
+ * @returns A promise that resolves once the data is restored or removed. If restoring throws, it
+ * attempts to remove the persisted data and then rejects with the restore error, or with the removal
+ * error if the removal fails too.
  */
 export async function persistQueryClientRestore({
   queryClient,
@@ -106,9 +160,11 @@ export async function persistQueryClientRestore({
 }
 
 /**
- * Persists data from the QueryCache
- *  - data dehydrated using dehydrateOptions
- *  - data is persisted using persister.persistClient
+ * Persists data from the QueryCache.
+ *  - data dehydrated using dehydrateOptions.
+ *  - data is persisted using persister.persistClient.
+ * @param options - The `queryClient` to persist, the `persister`, the `buster`, and the
+ * `dehydrateOptions`.
  */
 export async function persistQueryClientSave({
   queryClient,
@@ -126,7 +182,9 @@ export async function persistQueryClientSave({
 }
 
 /**
- * Subscribe to QueryCache and MutationCache updates (for persisting)
+ * Subscribe to QueryCache and MutationCache updates (for persisting).
+ * @param props - The `queryClient` to monitor, the `persister`, the `buster`, and the
+ * `dehydrateOptions` used for each save.
  * @returns an unsubscribe function (to discontinue monitoring)
  */
 export function persistQueryClientSubscribe(
@@ -156,6 +214,9 @@ export function persistQueryClientSubscribe(
 
 /**
  * Restores persisted data to QueryCache and persists further changes.
+ * @param props - The options for both restoring and saving.
+ * @returns A tuple of a function that stops persisting, and a promise that resolves once the
+ * restore is done.
  */
 export function persistQueryClient(
   props: PersistQueryClientOptions,

package/src/retryStrategies.ts

@@ -1,11 +1,21 @@
 import type { PersistedClient } from './persist'
 
+/**
+ * Called when saving the persisted client fails. Returns a smaller client to try saving again, or
+ * `undefined` to give up.
+ */
 export type PersistRetryer = (props: {
   persistedClient: PersistedClient
   error: Error
   errorCount: number
 }) => PersistedClient | undefined
 
+/**
+ * A {@link PersistRetryer} that drops the query with the oldest `dataUpdatedAt` and tries again, until
+ * no queries are left.
+ * @param props - The `persistedClient` that failed to save.
+ * @returns A copy of the client without its oldest query, or `undefined` if it has no queries.
+ */
 export const removeOldestQuery: PersistRetryer = ({ persistedClient }) => {
   const mutations = [...persistedClient.clientState.mutations]
   const queries = [...persistedClient.clientState.queries]