@tanstack/query-persist-client-core 5.0.0-beta.23 → 5.0.0-beta.28

package/build/legacy/createPersister.cjs

@@ -0,0 +1,100 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/createPersister.ts
+var createPersister_exports = {};
+__export(createPersister_exports, {
+  PERSISTER_KEY_PREFIX: () => PERSISTER_KEY_PREFIX,
+  experimental_createPersister: () => experimental_createPersister
+});
+module.exports = __toCommonJS(createPersister_exports);
+var import_query_core = require("@tanstack/query-core");
+var PERSISTER_KEY_PREFIX = "tanstack-query";
+function experimental_createPersister({
+  storage,
+  buster = "",
+  maxAge = 1e3 * 60 * 60 * 24,
+  serialize = JSON.stringify,
+  deserialize = JSON.parse,
+  prefix = PERSISTER_KEY_PREFIX,
+  filters
+}) {
+  return async function persisterFn(queryFn, context, query) {
+    const storageKey = `${prefix}-${query.queryHash}`;
+    const matchesFilter = filters ? (0, import_query_core.matchQuery)(filters, query) : true;
+    if (matchesFilter && query.state.data === void 0 && storage != null) {
+      try {
+        const storedData = await storage.getItem(storageKey);
+        if (storedData) {
+          const persistedQuery = deserialize(storedData);
+          if (persistedQuery.state.dataUpdatedAt) {
+            const queryAge = Date.now() - persistedQuery.state.dataUpdatedAt;
+            const expired = queryAge > maxAge;
+            const busted = persistedQuery.buster !== buster;
+            if (expired || busted) {
+              await storage.removeItem(storageKey);
+            } else {
+              setTimeout(() => {
+                query.setState({
+                  dataUpdatedAt: persistedQuery.state.dataUpdatedAt,
+                  errorUpdatedAt: persistedQuery.state.errorUpdatedAt
+                });
+                if (query.isStale()) {
+                  query.fetch();
+                }
+              }, 0);
+              return Promise.resolve(persistedQuery.state.data);
+            }
+          } else {
+            await storage.removeItem(storageKey);
+          }
+        }
+      } catch (err) {
+        if (process.env.NODE_ENV === "development") {
+          console.error(err);
+          console.warn(
+            "Encountered an error attempting to restore query cache from persisted location."
+          );
+        }
+        await storage.removeItem(storageKey);
+      }
+    }
+    const queryFnResult = await queryFn(context);
+    if (matchesFilter && storage != null) {
+      setTimeout(() => {
+        storage.setItem(
+          storageKey,
+          serialize({
+            state: query.state,
+            queryKey: query.queryKey,
+            queryHash: query.queryHash,
+            buster
+          })
+        );
+      }, 0);
+    }
+    return Promise.resolve(queryFnResult);
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PERSISTER_KEY_PREFIX,
+  experimental_createPersister
+});
+//# sourceMappingURL=createPersister.cjs.map

package/build/legacy/createPersister.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/createPersister.ts"],"sourcesContent":["import { matchQuery } from '@tanstack/query-core'\nimport type { QueryFilters } from '@tanstack/query-core'\nimport type {\n  Query,\n  QueryFunctionContext,\n  QueryKey,\n  QueryState,\n} from '@tanstack/query-core'\n\nexport interface PersistedQuery {\n  buster: string\n  queryHash: string\n  queryKey: QueryKey\n  state: QueryState\n}\n\nexport interface AsyncStorage {\n  getItem: (key: string) => Promise<string | undefined | null>\n  setItem: (key: string, value: string) => Promise<unknown>\n  removeItem: (key: string) => Promise<void>\n}\n\nexport interface StoragePersisterOptions {\n  /** The storage client used for setting and retrieving items from cache.\n   * For SSR pass in `undefined`.\n   */\n  storage: AsyncStorage | Storage | undefined | null\n  /**\n   * How to serialize the data to storage.\n   * @default `JSON.stringify`\n   */\n  serialize?: (persistedQuery: PersistedQuery) => string\n  /**\n   * How to deserialize the data from storage.\n   * @default `JSON.parse`\n   */\n  deserialize?: (cachedString: string) => PersistedQuery\n  /**\n   * A unique string that can be used to forcefully invalidate existing caches,\n   * if they do not share the same buster string\n   */\n  buster?: string\n  /**\n   * The max-allowed age of the cache in milliseconds.\n   * If a persisted cache is found that is older than this\n   * time, it will be discarded\n   * @default 24 hours\n   */\n  maxAge?: number\n  /**\n   * Prefix to be used for storage key.\n   * Storage key is a combination of prefix and query hash in a form of `prefix-queryHash`.\n   * @default 'tanstack-query'\n   */\n  prefix?: string\n  /**\n   * Filters to narrow down which Queries should be persisted.\n   */\n  filters?: QueryFilters\n}\n\nexport const PERSISTER_KEY_PREFIX = 'tanstack-query'\n\n/**\n * Warning: experimental feature.\n * This utility function enables fine-grained query persistance.\n * Simple add it as a `persister` parameter to `useQuery` or `defaultOptions` on `queryClient`.\n *\n * ```\n * useQuery({\n     queryKey: ['myKey'],\n     queryFn: fetcher,\n     persister: createPersister({\n       storage: localStorage,\n     }),\n   })\n   ```\n */\nexport function experimental_createPersister({\n  storage,\n  buster = '',\n  maxAge = 1000 * 60 * 60 * 24,\n  serialize = JSON.stringify,\n  deserialize = JSON.parse,\n  prefix = PERSISTER_KEY_PREFIX,\n  filters,\n}: StoragePersisterOptions) {\n  return async function persisterFn<T, TQueryKey extends QueryKey>(\n    queryFn: (context: QueryFunctionContext<TQueryKey>) => T | Promise<T>,\n    context: QueryFunctionContext<TQueryKey>,\n    query: Query,\n  ) {\n    const storageKey = `${prefix}-${query.queryHash}`\n    const matchesFilter = filters ? matchQuery(filters, query) : true\n\n    // Try to restore only if we do not have any data in the cache and we have persister defined\n    if (matchesFilter && query.state.data === undefined && storage != null) {\n      try {\n        const storedData = await storage.getItem(storageKey)\n        if (storedData) {\n          const persistedQuery = deserialize(storedData)\n\n          if (persistedQuery.state.dataUpdatedAt) {\n            const queryAge = Date.now() - persistedQuery.state.dataUpdatedAt\n            const expired = queryAge > maxAge\n            const busted = persistedQuery.buster !== buster\n            if (expired || busted) {\n              await storage.removeItem(storageKey)\n            } else {\n              // Just after restoring we want to get fresh data from the server if it's stale\n              setTimeout(() => {\n                // Set proper updatedAt, since resolving in the first pass overrides those values\n                query.setState({\n                  dataUpdatedAt: persistedQuery.state.dataUpdatedAt,\n                  errorUpdatedAt: persistedQuery.state.errorUpdatedAt,\n                })\n\n                if (query.isStale()) {\n                  query.fetch()\n                }\n              }, 0)\n              // We must resolve the promise here, as otherwise we will have `loading` state in the app until `queryFn` resolves\n              return Promise.resolve(persistedQuery.state.data as T)\n            }\n          } else {\n            await storage.removeItem(storageKey)\n          }\n        }\n      } catch (err) {\n        if (process.env.NODE_ENV === 'development') {\n          console.error(err)\n          console.warn(\n            'Encountered an error attempting to restore query cache from persisted location.',\n          )\n        }\n        await storage.removeItem(storageKey)\n      }\n    }\n\n    // If we did not restore, or restoration failed - fetch\n    const queryFnResult = await queryFn(context)\n\n    if (matchesFilter && storage != null) {\n      // Persist if we have storage defined, we use timeout to get proper state to be persisted\n      setTimeout(() => {\n        storage.setItem(\n          storageKey,\n          serialize({\n            state: query.state,\n            queryKey: query.queryKey,\n            queryHash: query.queryHash,\n            buster: buster,\n          }),\n        )\n      }, 0)\n    }\n\n    return Promise.resolve(queryFnResult)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,wBAA2B;AA6DpB,IAAM,uBAAuB;AAiB7B,SAAS,6BAA6B;AAAA,EAC3C;AAAA,EACA,SAAS;AAAA,EACT,SAAS,MAAO,KAAK,KAAK;AAAA,EAC1B,YAAY,KAAK;AAAA,EACjB,cAAc,KAAK;AAAA,EACnB,SAAS;AAAA,EACT;AACF,GAA4B;AAC1B,SAAO,eAAe,YACpB,SACA,SACA,OACA;AACA,UAAM,aAAa,GAAG,MAAM,IAAI,MAAM,SAAS;AAC/C,UAAM,gBAAgB,cAAU,8BAAW,SAAS,KAAK,IAAI;AAG7D,QAAI,iBAAiB,MAAM,MAAM,SAAS,UAAa,WAAW,MAAM;AACtE,UAAI;AACF,cAAM,aAAa,MAAM,QAAQ,QAAQ,UAAU;AACnD,YAAI,YAAY;AACd,gBAAM,iBAAiB,YAAY,UAAU;AAE7C,cAAI,eAAe,MAAM,eAAe;AACtC,kBAAM,WAAW,KAAK,IAAI,IAAI,eAAe,MAAM;AACnD,kBAAM,UAAU,WAAW;AAC3B,kBAAM,SAAS,eAAe,WAAW;AACzC,gBAAI,WAAW,QAAQ;AACrB,oBAAM,QAAQ,WAAW,UAAU;AAAA,YACrC,OAAO;AAEL,yBAAW,MAAM;AAEf,sBAAM,SAAS;AAAA,kBACb,eAAe,eAAe,MAAM;AAAA,kBACpC,gBAAgB,eAAe,MAAM;AAAA,gBACvC,CAAC;AAED,oBAAI,MAAM,QAAQ,GAAG;AACnB,wBAAM,MAAM;AAAA,gBACd;AAAA,cACF,GAAG,CAAC;AAEJ,qBAAO,QAAQ,QAAQ,eAAe,MAAM,IAAS;AAAA,YACvD;AAAA,UACF,OAAO;AACL,kBAAM,QAAQ,WAAW,UAAU;AAAA,UACrC;AAAA,QACF;AAAA,MACF,SAAS,KAAK;AACZ,YAAI,QAAQ,IAAI,aAAa,eAAe;AAC1C,kBAAQ,MAAM,GAAG;AACjB,kBAAQ;AAAA,YACN;AAAA,UACF;AAAA,QACF;AACA,cAAM,QAAQ,WAAW,UAAU;AAAA,MACrC;AAAA,IACF;AAGA,UAAM,gBAAgB,MAAM,QAAQ,OAAO;AAE3C,QAAI,iBAAiB,WAAW,MAAM;AAEpC,iBAAW,MAAM;AACf,gBAAQ;AAAA,UACN;AAAA,UACA,UAAU;AAAA,YACR,OAAO,MAAM;AAAA,YACb,UAAU,MAAM;AAAA,YAChB,WAAW,MAAM;AAAA,YACjB;AAAA,UACF,CAAC;AAAA,QACH;AAAA,MACF,GAAG,CAAC;AAAA,IACN;AAEA,WAAO,QAAQ,QAAQ,aAAa;AAAA,EACtC;AACF;","names":[]}

package/build/legacy/createPersister.d.cts

@@ -0,0 +1,78 @@
+import { QueryKey, QueryState, QueryFilters, Query } from '@tanstack/query-core';
+
+interface PersistedQuery {
+    buster: string;
+    queryHash: string;
+    queryKey: QueryKey;
+    state: QueryState;
+}
+interface AsyncStorage {
+    getItem: (key: string) => Promise<string | undefined | null>;
+    setItem: (key: string, value: string) => Promise<unknown>;
+    removeItem: (key: string) => Promise<void>;
+}
+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`.
+     * @default 'tanstack-query'
+     */
+    prefix?: string;
+    /**
+     * Filters to narrow down which Queries should be persisted.
+     */
+    filters?: QueryFilters;
+}
+declare const PERSISTER_KEY_PREFIX = "tanstack-query";
+/**
+ * Warning: experimental feature.
+ * This utility function enables fine-grained query persistance.
+ * Simple add it as a `persister` parameter to `useQuery` or `defaultOptions` on `queryClient`.
+ *
+ * ```
+ * useQuery({
+     queryKey: ['myKey'],
+     queryFn: fetcher,
+     persister: createPersister({
+       storage: localStorage,
+     }),
+   })
+   ```
+ */
+declare function experimental_createPersister({ storage, buster, maxAge, serialize, deserialize, prefix, filters, }: StoragePersisterOptions): <T, TQueryKey extends QueryKey>(queryFn: (context: {
+    queryKey: TQueryKey;
+    signal: AbortSignal;
+    meta: Record<string, unknown> | undefined;
+}) => T | Promise<T>, context: {
+    queryKey: TQueryKey;
+    signal: AbortSignal;
+    meta: Record<string, unknown> | undefined;
+}, query: Query) => Promise<T>;
+
+export { AsyncStorage, PERSISTER_KEY_PREFIX, PersistedQuery, StoragePersisterOptions, experimental_createPersister };

package/build/legacy/createPersister.d.ts

@@ -0,0 +1,78 @@
+import { QueryKey, QueryState, QueryFilters, Query } from '@tanstack/query-core';
+
+interface PersistedQuery {
+    buster: string;
+    queryHash: string;
+    queryKey: QueryKey;
+    state: QueryState;
+}
+interface AsyncStorage {
+    getItem: (key: string) => Promise<string | undefined | null>;
+    setItem: (key: string, value: string) => Promise<unknown>;
+    removeItem: (key: string) => Promise<void>;
+}
+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`.
+     * @default 'tanstack-query'
+     */
+    prefix?: string;
+    /**
+     * Filters to narrow down which Queries should be persisted.
+     */
+    filters?: QueryFilters;
+}
+declare const PERSISTER_KEY_PREFIX = "tanstack-query";
+/**
+ * Warning: experimental feature.
+ * This utility function enables fine-grained query persistance.
+ * Simple add it as a `persister` parameter to `useQuery` or `defaultOptions` on `queryClient`.
+ *
+ * ```
+ * useQuery({
+     queryKey: ['myKey'],
+     queryFn: fetcher,
+     persister: createPersister({
+       storage: localStorage,
+     }),
+   })
+   ```
+ */
+declare function experimental_createPersister({ storage, buster, maxAge, serialize, deserialize, prefix, filters, }: StoragePersisterOptions): <T, TQueryKey extends QueryKey>(queryFn: (context: {
+    queryKey: TQueryKey;
+    signal: AbortSignal;
+    meta: Record<string, unknown> | undefined;
+}) => T | Promise<T>, context: {
+    queryKey: TQueryKey;
+    signal: AbortSignal;
+    meta: Record<string, unknown> | undefined;
+}, query: Query) => Promise<T>;
+
+export { AsyncStorage, PERSISTER_KEY_PREFIX, PersistedQuery, StoragePersisterOptions, experimental_createPersister };

package/build/legacy/createPersister.js

@@ -0,0 +1,74 @@
+// src/createPersister.ts
+import { matchQuery } from "@tanstack/query-core";
+var PERSISTER_KEY_PREFIX = "tanstack-query";
+function experimental_createPersister({
+  storage,
+  buster = "",
+  maxAge = 1e3 * 60 * 60 * 24,
+  serialize = JSON.stringify,
+  deserialize = JSON.parse,
+  prefix = PERSISTER_KEY_PREFIX,
+  filters
+}) {
+  return async function persisterFn(queryFn, context, query) {
+    const storageKey = `${prefix}-${query.queryHash}`;
+    const matchesFilter = filters ? matchQuery(filters, query) : true;
+    if (matchesFilter && query.state.data === void 0 && storage != null) {
+      try {
+        const storedData = await storage.getItem(storageKey);
+        if (storedData) {
+          const persistedQuery = deserialize(storedData);
+          if (persistedQuery.state.dataUpdatedAt) {
+            const queryAge = Date.now() - persistedQuery.state.dataUpdatedAt;
+            const expired = queryAge > maxAge;
+            const busted = persistedQuery.buster !== buster;
+            if (expired || busted) {
+              await storage.removeItem(storageKey);
+            } else {
+              setTimeout(() => {
+                query.setState({
+                  dataUpdatedAt: persistedQuery.state.dataUpdatedAt,
+                  errorUpdatedAt: persistedQuery.state.errorUpdatedAt
+                });
+                if (query.isStale()) {
+                  query.fetch();
+                }
+              }, 0);
+              return Promise.resolve(persistedQuery.state.data);
+            }
+          } else {
+            await storage.removeItem(storageKey);
+          }
+        }
+      } catch (err) {
+        if (process.env.NODE_ENV === "development") {
+          console.error(err);
+          console.warn(
+            "Encountered an error attempting to restore query cache from persisted location."
+          );
+        }
+        await storage.removeItem(storageKey);
+      }
+    }
+    const queryFnResult = await queryFn(context);
+    if (matchesFilter && storage != null) {
+      setTimeout(() => {
+        storage.setItem(
+          storageKey,
+          serialize({
+            state: query.state,
+            queryKey: query.queryKey,
+            queryHash: query.queryHash,
+            buster
+          })
+        );
+      }, 0);
+    }
+    return Promise.resolve(queryFnResult);
+  };
+}
+export {
+  PERSISTER_KEY_PREFIX,
+  experimental_createPersister
+};
+//# sourceMappingURL=createPersister.js.map

package/build/legacy/createPersister.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/createPersister.ts"],"sourcesContent":["import { matchQuery } from '@tanstack/query-core'\nimport type { QueryFilters } from '@tanstack/query-core'\nimport type {\n  Query,\n  QueryFunctionContext,\n  QueryKey,\n  QueryState,\n} from '@tanstack/query-core'\n\nexport interface PersistedQuery {\n  buster: string\n  queryHash: string\n  queryKey: QueryKey\n  state: QueryState\n}\n\nexport interface AsyncStorage {\n  getItem: (key: string) => Promise<string | undefined | null>\n  setItem: (key: string, value: string) => Promise<unknown>\n  removeItem: (key: string) => Promise<void>\n}\n\nexport interface StoragePersisterOptions {\n  /** The storage client used for setting and retrieving items from cache.\n   * For SSR pass in `undefined`.\n   */\n  storage: AsyncStorage | Storage | undefined | null\n  /**\n   * How to serialize the data to storage.\n   * @default `JSON.stringify`\n   */\n  serialize?: (persistedQuery: PersistedQuery) => string\n  /**\n   * How to deserialize the data from storage.\n   * @default `JSON.parse`\n   */\n  deserialize?: (cachedString: string) => PersistedQuery\n  /**\n   * A unique string that can be used to forcefully invalidate existing caches,\n   * if they do not share the same buster string\n   */\n  buster?: string\n  /**\n   * The max-allowed age of the cache in milliseconds.\n   * If a persisted cache is found that is older than this\n   * time, it will be discarded\n   * @default 24 hours\n   */\n  maxAge?: number\n  /**\n   * Prefix to be used for storage key.\n   * Storage key is a combination of prefix and query hash in a form of `prefix-queryHash`.\n   * @default 'tanstack-query'\n   */\n  prefix?: string\n  /**\n   * Filters to narrow down which Queries should be persisted.\n   */\n  filters?: QueryFilters\n}\n\nexport const PERSISTER_KEY_PREFIX = 'tanstack-query'\n\n/**\n * Warning: experimental feature.\n * This utility function enables fine-grained query persistance.\n * Simple add it as a `persister` parameter to `useQuery` or `defaultOptions` on `queryClient`.\n *\n * ```\n * useQuery({\n     queryKey: ['myKey'],\n     queryFn: fetcher,\n     persister: createPersister({\n       storage: localStorage,\n     }),\n   })\n   ```\n */\nexport function experimental_createPersister({\n  storage,\n  buster = '',\n  maxAge = 1000 * 60 * 60 * 24,\n  serialize = JSON.stringify,\n  deserialize = JSON.parse,\n  prefix = PERSISTER_KEY_PREFIX,\n  filters,\n}: StoragePersisterOptions) {\n  return async function persisterFn<T, TQueryKey extends QueryKey>(\n    queryFn: (context: QueryFunctionContext<TQueryKey>) => T | Promise<T>,\n    context: QueryFunctionContext<TQueryKey>,\n    query: Query,\n  ) {\n    const storageKey = `${prefix}-${query.queryHash}`\n    const matchesFilter = filters ? matchQuery(filters, query) : true\n\n    // Try to restore only if we do not have any data in the cache and we have persister defined\n    if (matchesFilter && query.state.data === undefined && storage != null) {\n      try {\n        const storedData = await storage.getItem(storageKey)\n        if (storedData) {\n          const persistedQuery = deserialize(storedData)\n\n          if (persistedQuery.state.dataUpdatedAt) {\n            const queryAge = Date.now() - persistedQuery.state.dataUpdatedAt\n            const expired = queryAge > maxAge\n            const busted = persistedQuery.buster !== buster\n            if (expired || busted) {\n              await storage.removeItem(storageKey)\n            } else {\n              // Just after restoring we want to get fresh data from the server if it's stale\n              setTimeout(() => {\n                // Set proper updatedAt, since resolving in the first pass overrides those values\n                query.setState({\n                  dataUpdatedAt: persistedQuery.state.dataUpdatedAt,\n                  errorUpdatedAt: persistedQuery.state.errorUpdatedAt,\n                })\n\n                if (query.isStale()) {\n                  query.fetch()\n                }\n              }, 0)\n              // We must resolve the promise here, as otherwise we will have `loading` state in the app until `queryFn` resolves\n              return Promise.resolve(persistedQuery.state.data as T)\n            }\n          } else {\n            await storage.removeItem(storageKey)\n          }\n        }\n      } catch (err) {\n        if (process.env.NODE_ENV === 'development') {\n          console.error(err)\n          console.warn(\n            'Encountered an error attempting to restore query cache from persisted location.',\n          )\n        }\n        await storage.removeItem(storageKey)\n      }\n    }\n\n    // If we did not restore, or restoration failed - fetch\n    const queryFnResult = await queryFn(context)\n\n    if (matchesFilter && storage != null) {\n      // Persist if we have storage defined, we use timeout to get proper state to be persisted\n      setTimeout(() => {\n        storage.setItem(\n          storageKey,\n          serialize({\n            state: query.state,\n            queryKey: query.queryKey,\n            queryHash: query.queryHash,\n            buster: buster,\n          }),\n        )\n      }, 0)\n    }\n\n    return Promise.resolve(queryFnResult)\n  }\n}\n"],"mappings":";AAAA,SAAS,kBAAkB;AA6DpB,IAAM,uBAAuB;AAiB7B,SAAS,6BAA6B;AAAA,EAC3C;AAAA,EACA,SAAS;AAAA,EACT,SAAS,MAAO,KAAK,KAAK;AAAA,EAC1B,YAAY,KAAK;AAAA,EACjB,cAAc,KAAK;AAAA,EACnB,SAAS;AAAA,EACT;AACF,GAA4B;AAC1B,SAAO,eAAe,YACpB,SACA,SACA,OACA;AACA,UAAM,aAAa,GAAG,MAAM,IAAI,MAAM,SAAS;AAC/C,UAAM,gBAAgB,UAAU,WAAW,SAAS,KAAK,IAAI;AAG7D,QAAI,iBAAiB,MAAM,MAAM,SAAS,UAAa,WAAW,MAAM;AACtE,UAAI;AACF,cAAM,aAAa,MAAM,QAAQ,QAAQ,UAAU;AACnD,YAAI,YAAY;AACd,gBAAM,iBAAiB,YAAY,UAAU;AAE7C,cAAI,eAAe,MAAM,eAAe;AACtC,kBAAM,WAAW,KAAK,IAAI,IAAI,eAAe,MAAM;AACnD,kBAAM,UAAU,WAAW;AAC3B,kBAAM,SAAS,eAAe,WAAW;AACzC,gBAAI,WAAW,QAAQ;AACrB,oBAAM,QAAQ,WAAW,UAAU;AAAA,YACrC,OAAO;AAEL,yBAAW,MAAM;AAEf,sBAAM,SAAS;AAAA,kBACb,eAAe,eAAe,MAAM;AAAA,kBACpC,gBAAgB,eAAe,MAAM;AAAA,gBACvC,CAAC;AAED,oBAAI,MAAM,QAAQ,GAAG;AACnB,wBAAM,MAAM;AAAA,gBACd;AAAA,cACF,GAAG,CAAC;AAEJ,qBAAO,QAAQ,QAAQ,eAAe,MAAM,IAAS;AAAA,YACvD;AAAA,UACF,OAAO;AACL,kBAAM,QAAQ,WAAW,UAAU;AAAA,UACrC;AAAA,QACF;AAAA,MACF,SAAS,KAAK;AACZ,YAAI,QAAQ,IAAI,aAAa,eAAe;AAC1C,kBAAQ,MAAM,GAAG;AACjB,kBAAQ;AAAA,YACN;AAAA,UACF;AAAA,QACF;AACA,cAAM,QAAQ,WAAW,UAAU;AAAA,MACrC;AAAA,IACF;AAGA,UAAM,gBAAgB,MAAM,QAAQ,OAAO;AAE3C,QAAI,iBAAiB,WAAW,MAAM;AAEpC,iBAAW,MAAM;AACf,gBAAQ;AAAA,UACN;AAAA,UACA,UAAU;AAAA,YACR,OAAO,MAAM;AAAA,YACb,UAAU,MAAM;AAAA,YAChB,WAAW,MAAM;AAAA,YACjB;AAAA,UACF,CAAC;AAAA,QACH;AAAA,MACF,GAAG,CAAC;AAAA,IACN;AAEA,WAAO,QAAQ,QAAQ,aAAa;AAAA,EACtC;AACF;","names":[]}

package/build/legacy/index.cjs

@@ -19,9 +19,11 @@ var src_exports = {};
 module.exports = __toCommonJS(src_exports);
 __reExport(src_exports, require("./persist.cjs"), module.exports);
 __reExport(src_exports, require("./retryStrategies.cjs"), module.exports);
+__reExport(src_exports, require("./createPersister.cjs"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ...require("./persist.cjs"),
-  ...require("./retryStrategies.cjs")
+  ...require("./retryStrategies.cjs"),
+  ...require("./createPersister.cjs")
 });
 //# sourceMappingURL=index.cjs.map

package/build/legacy/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["/* istanbul ignore file */\n\nexport * from './persist'\nexport * from './retryStrategies'\n"],"mappings":";;;;;;;;;;;;;;;;;AAAA;AAAA;AAEA,wBAAc,0BAFd;AAGA,wBAAc,kCAHd;","names":[]}
+{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["/* istanbul ignore file */\n\nexport * from './persist'\nexport * from './retryStrategies'\nexport * from './createPersister'\n"],"mappings":";;;;;;;;;;;;;;;;;AAAA;AAAA;AAEA,wBAAc,0BAFd;AAGA,wBAAc,kCAHd;AAIA,wBAAc,kCAJd;","names":[]}

package/build/legacy/index.d.cts

@@ -1,3 +1,4 @@
 export { PersistQueryClienRootOptions, PersistQueryClientOptions, PersistedClient, PersistedQueryClientRestoreOptions, PersistedQueryClientSaveOptions, Persister, Promisable, persistQueryClient, persistQueryClientRestore, persistQueryClientSave, persistQueryClientSubscribe } from './persist.cjs';
 export { PersistRetryer, removeOldestQuery } from './retryStrategies.cjs';
+export { AsyncStorage, PERSISTER_KEY_PREFIX, PersistedQuery, StoragePersisterOptions, experimental_createPersister } from './createPersister.cjs';
 import '@tanstack/query-core';

package/build/legacy/index.d.ts

@@ -1,3 +1,4 @@
 export { PersistQueryClienRootOptions, PersistQueryClientOptions, PersistedClient, PersistedQueryClientRestoreOptions, PersistedQueryClientSaveOptions, Persister, Promisable, persistQueryClient, persistQueryClientRestore, persistQueryClientSave, persistQueryClientSubscribe } from './persist.js';
 export { PersistRetryer, removeOldestQuery } from './retryStrategies.js';
+export { AsyncStorage, PERSISTER_KEY_PREFIX, PersistedQuery, StoragePersisterOptions, experimental_createPersister } from './createPersister.js';
 import '@tanstack/query-core';

package/build/legacy/index.js

@@ -1,4 +1,5 @@
 // src/index.ts
 export * from "./persist.js";
 export * from "./retryStrategies.js";
+export * from "./createPersister.js";
 //# sourceMappingURL=index.js.map

package/build/legacy/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["/* istanbul ignore file */\n\nexport * from './persist'\nexport * from './retryStrategies'\n"],"mappings":";AAEA,cAAc;AACd,cAAc;","names":[]}
+{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["/* istanbul ignore file */\n\nexport * from './persist'\nexport * from './retryStrategies'\nexport * from './createPersister'\n"],"mappings":";AAEA,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}

package/build/modern/createPersister.cjs

@@ -0,0 +1,100 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/createPersister.ts
+var createPersister_exports = {};
+__export(createPersister_exports, {
+  PERSISTER_KEY_PREFIX: () => PERSISTER_KEY_PREFIX,
+  experimental_createPersister: () => experimental_createPersister
+});
+module.exports = __toCommonJS(createPersister_exports);
+var import_query_core = require("@tanstack/query-core");
+var PERSISTER_KEY_PREFIX = "tanstack-query";
+function experimental_createPersister({
+  storage,
+  buster = "",
+  maxAge = 1e3 * 60 * 60 * 24,
+  serialize = JSON.stringify,
+  deserialize = JSON.parse,
+  prefix = PERSISTER_KEY_PREFIX,
+  filters
+}) {
+  return async function persisterFn(queryFn, context, query) {
+    const storageKey = `${prefix}-${query.queryHash}`;
+    const matchesFilter = filters ? (0, import_query_core.matchQuery)(filters, query) : true;
+    if (matchesFilter && query.state.data === void 0 && storage != null) {
+      try {
+        const storedData = await storage.getItem(storageKey);
+        if (storedData) {
+          const persistedQuery = deserialize(storedData);
+          if (persistedQuery.state.dataUpdatedAt) {
+            const queryAge = Date.now() - persistedQuery.state.dataUpdatedAt;
+            const expired = queryAge > maxAge;
+            const busted = persistedQuery.buster !== buster;
+            if (expired || busted) {
+              await storage.removeItem(storageKey);
+            } else {
+              setTimeout(() => {
+                query.setState({
+                  dataUpdatedAt: persistedQuery.state.dataUpdatedAt,
+                  errorUpdatedAt: persistedQuery.state.errorUpdatedAt
+                });
+                if (query.isStale()) {
+                  query.fetch();
+                }
+              }, 0);
+              return Promise.resolve(persistedQuery.state.data);
+            }
+          } else {
+            await storage.removeItem(storageKey);
+          }
+        }
+      } catch (err) {
+        if (process.env.NODE_ENV === "development") {
+          console.error(err);
+          console.warn(
+            "Encountered an error attempting to restore query cache from persisted location."
+          );
+        }
+        await storage.removeItem(storageKey);
+      }
+    }
+    const queryFnResult = await queryFn(context);
+    if (matchesFilter && storage != null) {
+      setTimeout(() => {
+        storage.setItem(
+          storageKey,
+          serialize({
+            state: query.state,
+            queryKey: query.queryKey,
+            queryHash: query.queryHash,
+            buster
+          })
+        );
+      }, 0);
+    }
+    return Promise.resolve(queryFnResult);
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PERSISTER_KEY_PREFIX,
+  experimental_createPersister
+});
+//# sourceMappingURL=createPersister.cjs.map

package/build/modern/createPersister.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/createPersister.ts"],"sourcesContent":["import { matchQuery } from '@tanstack/query-core'\nimport type { QueryFilters } from '@tanstack/query-core'\nimport type {\n  Query,\n  QueryFunctionContext,\n  QueryKey,\n  QueryState,\n} from '@tanstack/query-core'\n\nexport interface PersistedQuery {\n  buster: string\n  queryHash: string\n  queryKey: QueryKey\n  state: QueryState\n}\n\nexport interface AsyncStorage {\n  getItem: (key: string) => Promise<string | undefined | null>\n  setItem: (key: string, value: string) => Promise<unknown>\n  removeItem: (key: string) => Promise<void>\n}\n\nexport interface StoragePersisterOptions {\n  /** The storage client used for setting and retrieving items from cache.\n   * For SSR pass in `undefined`.\n   */\n  storage: AsyncStorage | Storage | undefined | null\n  /**\n   * How to serialize the data to storage.\n   * @default `JSON.stringify`\n   */\n  serialize?: (persistedQuery: PersistedQuery) => string\n  /**\n   * How to deserialize the data from storage.\n   * @default `JSON.parse`\n   */\n  deserialize?: (cachedString: string) => PersistedQuery\n  /**\n   * A unique string that can be used to forcefully invalidate existing caches,\n   * if they do not share the same buster string\n   */\n  buster?: string\n  /**\n   * The max-allowed age of the cache in milliseconds.\n   * If a persisted cache is found that is older than this\n   * time, it will be discarded\n   * @default 24 hours\n   */\n  maxAge?: number\n  /**\n   * Prefix to be used for storage key.\n   * Storage key is a combination of prefix and query hash in a form of `prefix-queryHash`.\n   * @default 'tanstack-query'\n   */\n  prefix?: string\n  /**\n   * Filters to narrow down which Queries should be persisted.\n   */\n  filters?: QueryFilters\n}\n\nexport const PERSISTER_KEY_PREFIX = 'tanstack-query'\n\n/**\n * Warning: experimental feature.\n * This utility function enables fine-grained query persistance.\n * Simple add it as a `persister` parameter to `useQuery` or `defaultOptions` on `queryClient`.\n *\n * ```\n * useQuery({\n     queryKey: ['myKey'],\n     queryFn: fetcher,\n     persister: createPersister({\n       storage: localStorage,\n     }),\n   })\n   ```\n */\nexport function experimental_createPersister({\n  storage,\n  buster = '',\n  maxAge = 1000 * 60 * 60 * 24,\n  serialize = JSON.stringify,\n  deserialize = JSON.parse,\n  prefix = PERSISTER_KEY_PREFIX,\n  filters,\n}: StoragePersisterOptions) {\n  return async function persisterFn<T, TQueryKey extends QueryKey>(\n    queryFn: (context: QueryFunctionContext<TQueryKey>) => T | Promise<T>,\n    context: QueryFunctionContext<TQueryKey>,\n    query: Query,\n  ) {\n    const storageKey = `${prefix}-${query.queryHash}`\n    const matchesFilter = filters ? matchQuery(filters, query) : true\n\n    // Try to restore only if we do not have any data in the cache and we have persister defined\n    if (matchesFilter && query.state.data === undefined && storage != null) {\n      try {\n        const storedData = await storage.getItem(storageKey)\n        if (storedData) {\n          const persistedQuery = deserialize(storedData)\n\n          if (persistedQuery.state.dataUpdatedAt) {\n            const queryAge = Date.now() - persistedQuery.state.dataUpdatedAt\n            const expired = queryAge > maxAge\n            const busted = persistedQuery.buster !== buster\n            if (expired || busted) {\n              await storage.removeItem(storageKey)\n            } else {\n              // Just after restoring we want to get fresh data from the server if it's stale\n              setTimeout(() => {\n                // Set proper updatedAt, since resolving in the first pass overrides those values\n                query.setState({\n                  dataUpdatedAt: persistedQuery.state.dataUpdatedAt,\n                  errorUpdatedAt: persistedQuery.state.errorUpdatedAt,\n                })\n\n                if (query.isStale()) {\n                  query.fetch()\n                }\n              }, 0)\n              // We must resolve the promise here, as otherwise we will have `loading` state in the app until `queryFn` resolves\n              return Promise.resolve(persistedQuery.state.data as T)\n            }\n          } else {\n            await storage.removeItem(storageKey)\n          }\n        }\n      } catch (err) {\n        if (process.env.NODE_ENV === 'development') {\n          console.error(err)\n          console.warn(\n            'Encountered an error attempting to restore query cache from persisted location.',\n          )\n        }\n        await storage.removeItem(storageKey)\n      }\n    }\n\n    // If we did not restore, or restoration failed - fetch\n    const queryFnResult = await queryFn(context)\n\n    if (matchesFilter && storage != null) {\n      // Persist if we have storage defined, we use timeout to get proper state to be persisted\n      setTimeout(() => {\n        storage.setItem(\n          storageKey,\n          serialize({\n            state: query.state,\n            queryKey: query.queryKey,\n            queryHash: query.queryHash,\n            buster: buster,\n          }),\n        )\n      }, 0)\n    }\n\n    return Promise.resolve(queryFnResult)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,wBAA2B;AA6DpB,IAAM,uBAAuB;AAiB7B,SAAS,6BAA6B;AAAA,EAC3C;AAAA,EACA,SAAS;AAAA,EACT,SAAS,MAAO,KAAK,KAAK;AAAA,EAC1B,YAAY,KAAK;AAAA,EACjB,cAAc,KAAK;AAAA,EACnB,SAAS;AAAA,EACT;AACF,GAA4B;AAC1B,SAAO,eAAe,YACpB,SACA,SACA,OACA;AACA,UAAM,aAAa,GAAG,MAAM,IAAI,MAAM,SAAS;AAC/C,UAAM,gBAAgB,cAAU,8BAAW,SAAS,KAAK,IAAI;AAG7D,QAAI,iBAAiB,MAAM,MAAM,SAAS,UAAa,WAAW,MAAM;AACtE,UAAI;AACF,cAAM,aAAa,MAAM,QAAQ,QAAQ,UAAU;AACnD,YAAI,YAAY;AACd,gBAAM,iBAAiB,YAAY,UAAU;AAE7C,cAAI,eAAe,MAAM,eAAe;AACtC,kBAAM,WAAW,KAAK,IAAI,IAAI,eAAe,MAAM;AACnD,kBAAM,UAAU,WAAW;AAC3B,kBAAM,SAAS,eAAe,WAAW;AACzC,gBAAI,WAAW,QAAQ;AACrB,oBAAM,QAAQ,WAAW,UAAU;AAAA,YACrC,OAAO;AAEL,yBAAW,MAAM;AAEf,sBAAM,SAAS;AAAA,kBACb,eAAe,eAAe,MAAM;AAAA,kBACpC,gBAAgB,eAAe,MAAM;AAAA,gBACvC,CAAC;AAED,oBAAI,MAAM,QAAQ,GAAG;AACnB,wBAAM,MAAM;AAAA,gBACd;AAAA,cACF,GAAG,CAAC;AAEJ,qBAAO,QAAQ,QAAQ,eAAe,MAAM,IAAS;AAAA,YACvD;AAAA,UACF,OAAO;AACL,kBAAM,QAAQ,WAAW,UAAU;AAAA,UACrC;AAAA,QACF;AAAA,MACF,SAAS,KAAK;AACZ,YAAI,QAAQ,IAAI,aAAa,eAAe;AAC1C,kBAAQ,MAAM,GAAG;AACjB,kBAAQ;AAAA,YACN;AAAA,UACF;AAAA,QACF;AACA,cAAM,QAAQ,WAAW,UAAU;AAAA,MACrC;AAAA,IACF;AAGA,UAAM,gBAAgB,MAAM,QAAQ,OAAO;AAE3C,QAAI,iBAAiB,WAAW,MAAM;AAEpC,iBAAW,MAAM;AACf,gBAAQ;AAAA,UACN;AAAA,UACA,UAAU;AAAA,YACR,OAAO,MAAM;AAAA,YACb,UAAU,MAAM;AAAA,YAChB,WAAW,MAAM;AAAA,YACjB;AAAA,UACF,CAAC;AAAA,QACH;AAAA,MACF,GAAG,CAAC;AAAA,IACN;AAEA,WAAO,QAAQ,QAAQ,aAAa;AAAA,EACtC;AACF;","names":[]}

package/build/modern/createPersister.d.cts

@@ -0,0 +1,78 @@
+import { QueryKey, QueryState, QueryFilters, Query } from '@tanstack/query-core';
+
+interface PersistedQuery {
+    buster: string;
+    queryHash: string;
+    queryKey: QueryKey;
+    state: QueryState;
+}
+interface AsyncStorage {
+    getItem: (key: string) => Promise<string | undefined | null>;
+    setItem: (key: string, value: string) => Promise<unknown>;
+    removeItem: (key: string) => Promise<void>;
+}
+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`.
+     * @default 'tanstack-query'
+     */
+    prefix?: string;
+    /**
+     * Filters to narrow down which Queries should be persisted.
+     */
+    filters?: QueryFilters;
+}
+declare const PERSISTER_KEY_PREFIX = "tanstack-query";
+/**
+ * Warning: experimental feature.
+ * This utility function enables fine-grained query persistance.
+ * Simple add it as a `persister` parameter to `useQuery` or `defaultOptions` on `queryClient`.
+ *
+ * ```
+ * useQuery({
+     queryKey: ['myKey'],
+     queryFn: fetcher,
+     persister: createPersister({
+       storage: localStorage,
+     }),
+   })
+   ```
+ */
+declare function experimental_createPersister({ storage, buster, maxAge, serialize, deserialize, prefix, filters, }: StoragePersisterOptions): <T, TQueryKey extends QueryKey>(queryFn: (context: {
+    queryKey: TQueryKey;
+    signal: AbortSignal;
+    meta: Record<string, unknown> | undefined;
+}) => T | Promise<T>, context: {
+    queryKey: TQueryKey;
+    signal: AbortSignal;
+    meta: Record<string, unknown> | undefined;
+}, query: Query) => Promise<T>;
+
+export { AsyncStorage, PERSISTER_KEY_PREFIX, PersistedQuery, StoragePersisterOptions, experimental_createPersister };

package/build/modern/createPersister.d.ts

@@ -0,0 +1,78 @@
+import { QueryKey, QueryState, QueryFilters, Query } from '@tanstack/query-core';
+
+interface PersistedQuery {
+    buster: string;
+    queryHash: string;
+    queryKey: QueryKey;
+    state: QueryState;
+}
+interface AsyncStorage {
+    getItem: (key: string) => Promise<string | undefined | null>;
+    setItem: (key: string, value: string) => Promise<unknown>;
+    removeItem: (key: string) => Promise<void>;
+}
+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`.
+     * @default 'tanstack-query'
+     */
+    prefix?: string;
+    /**
+     * Filters to narrow down which Queries should be persisted.
+     */
+    filters?: QueryFilters;
+}
+declare const PERSISTER_KEY_PREFIX = "tanstack-query";
+/**
+ * Warning: experimental feature.
+ * This utility function enables fine-grained query persistance.
+ * Simple add it as a `persister` parameter to `useQuery` or `defaultOptions` on `queryClient`.
+ *
+ * ```
+ * useQuery({
+     queryKey: ['myKey'],
+     queryFn: fetcher,
+     persister: createPersister({
+       storage: localStorage,
+     }),
+   })
+   ```
+ */
+declare function experimental_createPersister({ storage, buster, maxAge, serialize, deserialize, prefix, filters, }: StoragePersisterOptions): <T, TQueryKey extends QueryKey>(queryFn: (context: {
+    queryKey: TQueryKey;
+    signal: AbortSignal;
+    meta: Record<string, unknown> | undefined;
+}) => T | Promise<T>, context: {
+    queryKey: TQueryKey;
+    signal: AbortSignal;
+    meta: Record<string, unknown> | undefined;
+}, query: Query) => Promise<T>;
+
+export { AsyncStorage, PERSISTER_KEY_PREFIX, PersistedQuery, StoragePersisterOptions, experimental_createPersister };

package/build/modern/createPersister.js

@@ -0,0 +1,74 @@
+// src/createPersister.ts
+import { matchQuery } from "@tanstack/query-core";
+var PERSISTER_KEY_PREFIX = "tanstack-query";
+function experimental_createPersister({
+  storage,
+  buster = "",
+  maxAge = 1e3 * 60 * 60 * 24,
+  serialize = JSON.stringify,
+  deserialize = JSON.parse,
+  prefix = PERSISTER_KEY_PREFIX,
+  filters
+}) {
+  return async function persisterFn(queryFn, context, query) {
+    const storageKey = `${prefix}-${query.queryHash}`;
+    const matchesFilter = filters ? matchQuery(filters, query) : true;
+    if (matchesFilter && query.state.data === void 0 && storage != null) {
+      try {
+        const storedData = await storage.getItem(storageKey);
+        if (storedData) {
+          const persistedQuery = deserialize(storedData);
+          if (persistedQuery.state.dataUpdatedAt) {
+            const queryAge = Date.now() - persistedQuery.state.dataUpdatedAt;
+            const expired = queryAge > maxAge;
+            const busted = persistedQuery.buster !== buster;
+            if (expired || busted) {
+              await storage.removeItem(storageKey);
+            } else {
+              setTimeout(() => {
+                query.setState({
+                  dataUpdatedAt: persistedQuery.state.dataUpdatedAt,
+                  errorUpdatedAt: persistedQuery.state.errorUpdatedAt
+                });
+                if (query.isStale()) {
+                  query.fetch();
+                }
+              }, 0);
+              return Promise.resolve(persistedQuery.state.data);
+            }
+          } else {
+            await storage.removeItem(storageKey);
+          }
+        }
+      } catch (err) {
+        if (process.env.NODE_ENV === "development") {
+          console.error(err);
+          console.warn(
+            "Encountered an error attempting to restore query cache from persisted location."
+          );
+        }
+        await storage.removeItem(storageKey);
+      }
+    }
+    const queryFnResult = await queryFn(context);
+    if (matchesFilter && storage != null) {
+      setTimeout(() => {
+        storage.setItem(
+          storageKey,
+          serialize({
+            state: query.state,
+            queryKey: query.queryKey,
+            queryHash: query.queryHash,
+            buster
+          })
+        );
+      }, 0);
+    }
+    return Promise.resolve(queryFnResult);
+  };
+}
+export {
+  PERSISTER_KEY_PREFIX,
+  experimental_createPersister
+};
+//# sourceMappingURL=createPersister.js.map

package/build/modern/createPersister.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/createPersister.ts"],"sourcesContent":["import { matchQuery } from '@tanstack/query-core'\nimport type { QueryFilters } from '@tanstack/query-core'\nimport type {\n  Query,\n  QueryFunctionContext,\n  QueryKey,\n  QueryState,\n} from '@tanstack/query-core'\n\nexport interface PersistedQuery {\n  buster: string\n  queryHash: string\n  queryKey: QueryKey\n  state: QueryState\n}\n\nexport interface AsyncStorage {\n  getItem: (key: string) => Promise<string | undefined | null>\n  setItem: (key: string, value: string) => Promise<unknown>\n  removeItem: (key: string) => Promise<void>\n}\n\nexport interface StoragePersisterOptions {\n  /** The storage client used for setting and retrieving items from cache.\n   * For SSR pass in `undefined`.\n   */\n  storage: AsyncStorage | Storage | undefined | null\n  /**\n   * How to serialize the data to storage.\n   * @default `JSON.stringify`\n   */\n  serialize?: (persistedQuery: PersistedQuery) => string\n  /**\n   * How to deserialize the data from storage.\n   * @default `JSON.parse`\n   */\n  deserialize?: (cachedString: string) => PersistedQuery\n  /**\n   * A unique string that can be used to forcefully invalidate existing caches,\n   * if they do not share the same buster string\n   */\n  buster?: string\n  /**\n   * The max-allowed age of the cache in milliseconds.\n   * If a persisted cache is found that is older than this\n   * time, it will be discarded\n   * @default 24 hours\n   */\n  maxAge?: number\n  /**\n   * Prefix to be used for storage key.\n   * Storage key is a combination of prefix and query hash in a form of `prefix-queryHash`.\n   * @default 'tanstack-query'\n   */\n  prefix?: string\n  /**\n   * Filters to narrow down which Queries should be persisted.\n   */\n  filters?: QueryFilters\n}\n\nexport const PERSISTER_KEY_PREFIX = 'tanstack-query'\n\n/**\n * Warning: experimental feature.\n * This utility function enables fine-grained query persistance.\n * Simple add it as a `persister` parameter to `useQuery` or `defaultOptions` on `queryClient`.\n *\n * ```\n * useQuery({\n     queryKey: ['myKey'],\n     queryFn: fetcher,\n     persister: createPersister({\n       storage: localStorage,\n     }),\n   })\n   ```\n */\nexport function experimental_createPersister({\n  storage,\n  buster = '',\n  maxAge = 1000 * 60 * 60 * 24,\n  serialize = JSON.stringify,\n  deserialize = JSON.parse,\n  prefix = PERSISTER_KEY_PREFIX,\n  filters,\n}: StoragePersisterOptions) {\n  return async function persisterFn<T, TQueryKey extends QueryKey>(\n    queryFn: (context: QueryFunctionContext<TQueryKey>) => T | Promise<T>,\n    context: QueryFunctionContext<TQueryKey>,\n    query: Query,\n  ) {\n    const storageKey = `${prefix}-${query.queryHash}`\n    const matchesFilter = filters ? matchQuery(filters, query) : true\n\n    // Try to restore only if we do not have any data in the cache and we have persister defined\n    if (matchesFilter && query.state.data === undefined && storage != null) {\n      try {\n        const storedData = await storage.getItem(storageKey)\n        if (storedData) {\n          const persistedQuery = deserialize(storedData)\n\n          if (persistedQuery.state.dataUpdatedAt) {\n            const queryAge = Date.now() - persistedQuery.state.dataUpdatedAt\n            const expired = queryAge > maxAge\n            const busted = persistedQuery.buster !== buster\n            if (expired || busted) {\n              await storage.removeItem(storageKey)\n            } else {\n              // Just after restoring we want to get fresh data from the server if it's stale\n              setTimeout(() => {\n                // Set proper updatedAt, since resolving in the first pass overrides those values\n                query.setState({\n                  dataUpdatedAt: persistedQuery.state.dataUpdatedAt,\n                  errorUpdatedAt: persistedQuery.state.errorUpdatedAt,\n                })\n\n                if (query.isStale()) {\n                  query.fetch()\n                }\n              }, 0)\n              // We must resolve the promise here, as otherwise we will have `loading` state in the app until `queryFn` resolves\n              return Promise.resolve(persistedQuery.state.data as T)\n            }\n          } else {\n            await storage.removeItem(storageKey)\n          }\n        }\n      } catch (err) {\n        if (process.env.NODE_ENV === 'development') {\n          console.error(err)\n          console.warn(\n            'Encountered an error attempting to restore query cache from persisted location.',\n          )\n        }\n        await storage.removeItem(storageKey)\n      }\n    }\n\n    // If we did not restore, or restoration failed - fetch\n    const queryFnResult = await queryFn(context)\n\n    if (matchesFilter && storage != null) {\n      // Persist if we have storage defined, we use timeout to get proper state to be persisted\n      setTimeout(() => {\n        storage.setItem(\n          storageKey,\n          serialize({\n            state: query.state,\n            queryKey: query.queryKey,\n            queryHash: query.queryHash,\n            buster: buster,\n          }),\n        )\n      }, 0)\n    }\n\n    return Promise.resolve(queryFnResult)\n  }\n}\n"],"mappings":";AAAA,SAAS,kBAAkB;AA6DpB,IAAM,uBAAuB;AAiB7B,SAAS,6BAA6B;AAAA,EAC3C;AAAA,EACA,SAAS;AAAA,EACT,SAAS,MAAO,KAAK,KAAK;AAAA,EAC1B,YAAY,KAAK;AAAA,EACjB,cAAc,KAAK;AAAA,EACnB,SAAS;AAAA,EACT;AACF,GAA4B;AAC1B,SAAO,eAAe,YACpB,SACA,SACA,OACA;AACA,UAAM,aAAa,GAAG,MAAM,IAAI,MAAM,SAAS;AAC/C,UAAM,gBAAgB,UAAU,WAAW,SAAS,KAAK,IAAI;AAG7D,QAAI,iBAAiB,MAAM,MAAM,SAAS,UAAa,WAAW,MAAM;AACtE,UAAI;AACF,cAAM,aAAa,MAAM,QAAQ,QAAQ,UAAU;AACnD,YAAI,YAAY;AACd,gBAAM,iBAAiB,YAAY,UAAU;AAE7C,cAAI,eAAe,MAAM,eAAe;AACtC,kBAAM,WAAW,KAAK,IAAI,IAAI,eAAe,MAAM;AACnD,kBAAM,UAAU,WAAW;AAC3B,kBAAM,SAAS,eAAe,WAAW;AACzC,gBAAI,WAAW,QAAQ;AACrB,oBAAM,QAAQ,WAAW,UAAU;AAAA,YACrC,OAAO;AAEL,yBAAW,MAAM;AAEf,sBAAM,SAAS;AAAA,kBACb,eAAe,eAAe,MAAM;AAAA,kBACpC,gBAAgB,eAAe,MAAM;AAAA,gBACvC,CAAC;AAED,oBAAI,MAAM,QAAQ,GAAG;AACnB,wBAAM,MAAM;AAAA,gBACd;AAAA,cACF,GAAG,CAAC;AAEJ,qBAAO,QAAQ,QAAQ,eAAe,MAAM,IAAS;AAAA,YACvD;AAAA,UACF,OAAO;AACL,kBAAM,QAAQ,WAAW,UAAU;AAAA,UACrC;AAAA,QACF;AAAA,MACF,SAAS,KAAK;AACZ,YAAI,QAAQ,IAAI,aAAa,eAAe;AAC1C,kBAAQ,MAAM,GAAG;AACjB,kBAAQ;AAAA,YACN;AAAA,UACF;AAAA,QACF;AACA,cAAM,QAAQ,WAAW,UAAU;AAAA,MACrC;AAAA,IACF;AAGA,UAAM,gBAAgB,MAAM,QAAQ,OAAO;AAE3C,QAAI,iBAAiB,WAAW,MAAM;AAEpC,iBAAW,MAAM;AACf,gBAAQ;AAAA,UACN;AAAA,UACA,UAAU;AAAA,YACR,OAAO,MAAM;AAAA,YACb,UAAU,MAAM;AAAA,YAChB,WAAW,MAAM;AAAA,YACjB;AAAA,UACF,CAAC;AAAA,QACH;AAAA,MACF,GAAG,CAAC;AAAA,IACN;AAEA,WAAO,QAAQ,QAAQ,aAAa;AAAA,EACtC;AACF;","names":[]}

package/build/modern/index.cjs

@@ -19,9 +19,11 @@ var src_exports = {};
 module.exports = __toCommonJS(src_exports);
 __reExport(src_exports, require("./persist.cjs"), module.exports);
 __reExport(src_exports, require("./retryStrategies.cjs"), module.exports);
+__reExport(src_exports, require("./createPersister.cjs"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ...require("./persist.cjs"),
-  ...require("./retryStrategies.cjs")
+  ...require("./retryStrategies.cjs"),
+  ...require("./createPersister.cjs")
 });
 //# sourceMappingURL=index.cjs.map

package/build/modern/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["/* istanbul ignore file */\n\nexport * from './persist'\nexport * from './retryStrategies'\n"],"mappings":";;;;;;;;;;;;;;;;;AAAA;AAAA;AAEA,wBAAc,0BAFd;AAGA,wBAAc,kCAHd;","names":[]}
+{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["/* istanbul ignore file */\n\nexport * from './persist'\nexport * from './retryStrategies'\nexport * from './createPersister'\n"],"mappings":";;;;;;;;;;;;;;;;;AAAA;AAAA;AAEA,wBAAc,0BAFd;AAGA,wBAAc,kCAHd;AAIA,wBAAc,kCAJd;","names":[]}

package/build/modern/index.d.cts

@@ -1,3 +1,4 @@
 export { PersistQueryClienRootOptions, PersistQueryClientOptions, PersistedClient, PersistedQueryClientRestoreOptions, PersistedQueryClientSaveOptions, Persister, Promisable, persistQueryClient, persistQueryClientRestore, persistQueryClientSave, persistQueryClientSubscribe } from './persist.cjs';
 export { PersistRetryer, removeOldestQuery } from './retryStrategies.cjs';
+export { AsyncStorage, PERSISTER_KEY_PREFIX, PersistedQuery, StoragePersisterOptions, experimental_createPersister } from './createPersister.cjs';
 import '@tanstack/query-core';

package/build/modern/index.d.ts

@@ -1,3 +1,4 @@
 export { PersistQueryClienRootOptions, PersistQueryClientOptions, PersistedClient, PersistedQueryClientRestoreOptions, PersistedQueryClientSaveOptions, Persister, Promisable, persistQueryClient, persistQueryClientRestore, persistQueryClientSave, persistQueryClientSubscribe } from './persist.js';
 export { PersistRetryer, removeOldestQuery } from './retryStrategies.js';
+export { AsyncStorage, PERSISTER_KEY_PREFIX, PersistedQuery, StoragePersisterOptions, experimental_createPersister } from './createPersister.js';
 import '@tanstack/query-core';

package/build/modern/index.js

@@ -1,4 +1,5 @@
 // src/index.ts
 export * from "./persist.js";
 export * from "./retryStrategies.js";
+export * from "./createPersister.js";
 //# sourceMappingURL=index.js.map

package/build/modern/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["/* istanbul ignore file */\n\nexport * from './persist'\nexport * from './retryStrategies'\n"],"mappings":";AAEA,cAAc;AACd,cAAc;","names":[]}
+{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["/* istanbul ignore file */\n\nexport * from './persist'\nexport * from './retryStrategies'\nexport * from './createPersister'\n"],"mappings":";AAEA,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/query-persist-client-core",
-  "version": "5.0.0-beta.23",
+  "version": "5.0.0-beta.28",
   "description": "Set of utilities for interacting with persisters, which can save your queryClient for later use",
   "author": "tannerlinsley",
   "license": "MIT",
@@ -37,7 +37,7 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/query-core": "5.0.0-beta.23"
+    "@tanstack/query-core": "5.0.0-beta.28"
   },
   "scripts": {
     "clean": "rimraf ./build && rimraf ./coverage",

package/src/__tests__/createPersister.test.ts

@@ -0,0 +1,312 @@
+import { Query, QueryCache, hashKey } from '@tanstack/query-core'
+import { vi } from 'vitest'
+import {
+  PERSISTER_KEY_PREFIX,
+  experimental_createPersister,
+} from '../createPersister'
+import { sleep } from './utils'
+import type { StoragePersisterOptions } from '../createPersister'
+import type { QueryKey } from '@tanstack/query-core'
+
+function getFreshStorage() {
+  const storage = new Map()
+  return {
+    getItem: (key: string) => Promise.resolve(storage.get(key)),
+    setItem: async (key: string, value: unknown) => {
+      storage.set(key, value)
+    },
+    removeItem: async (key: string) => {
+      storage.delete(key)
+    },
+  }
+}
+
+function setupPersister(
+  queryKey: QueryKey,
+  persisterOptions: StoragePersisterOptions,
+) {
+  const context = {
+    meta: { foo: 'bar' },
+    queryKey,
+    // @ts-ignore
+    signal: undefined as AbortSignal,
+  }
+  const queryHash = hashKey(queryKey)
+  const storageKey = `${PERSISTER_KEY_PREFIX}-${queryHash}`
+
+  const queryFn = vi.fn()
+
+  const persisterFn = experimental_createPersister(persisterOptions)
+
+  const query = new Query({
+    cache: new QueryCache(),
+    queryHash,
+    queryKey,
+  })
+
+  return {
+    context,
+    persisterFn,
+    query,
+    queryFn,
+    queryHash,
+    queryKey,
+    storageKey,
+  }
+}
+
+describe('createPersister', () => {
+  test('should fetch if storage is not provided', async () => {
+    const { context, persisterFn, query, queryFn } = setupPersister(['foo'], {
+      storage: undefined,
+    })
+
+    await persisterFn(queryFn, context, query)
+
+    expect(queryFn).toHaveBeenCalledOnce()
+    expect(queryFn).toHaveBeenCalledWith(context)
+  })
+
+  test('should fetch if there is no stored data', async () => {
+    const storage = getFreshStorage()
+    const { context, persisterFn, query, queryFn } = setupPersister(['foo'], {
+      storage,
+    })
+
+    await persisterFn(queryFn, context, query)
+
+    expect(queryFn).toHaveBeenCalledOnce()
+    expect(queryFn).toHaveBeenCalledWith(context)
+  })
+
+  test('should fetch if query already has data', async () => {
+    const storage = getFreshStorage()
+    const { context, persisterFn, query, queryFn } = setupPersister(['foo'], {
+      storage,
+    })
+    query.state.data = 'baz'
+
+    await persisterFn(queryFn, context, query)
+
+    expect(queryFn).toHaveBeenCalledOnce()
+    expect(queryFn).toHaveBeenCalledWith(context)
+  })
+
+  test('should fetch if deserialization fails', async () => {
+    const storage = getFreshStorage()
+    const { context, persisterFn, query, queryFn, storageKey } = setupPersister(
+      ['foo'],
+      {
+        storage,
+      },
+    )
+
+    await storage.setItem(storageKey, '{invalid[item')
+
+    await persisterFn(queryFn, context, query)
+
+    expect(await storage.getItem(storageKey)).toBeUndefined()
+
+    expect(queryFn).toHaveBeenCalledOnce()
+    expect(queryFn).toHaveBeenCalledWith(context)
+  })
+
+  test('should remove stored item if `dataUpdatedAt` is empty', async () => {
+    const storage = getFreshStorage()
+    const { context, persisterFn, query, queryFn, storageKey } = setupPersister(
+      ['foo'],
+      {
+        storage,
+      },
+    )
+
+    await storage.setItem(
+      storageKey,
+      JSON.stringify({
+        buster: '',
+        state: { dataUpdatedAt: undefined },
+      }),
+    )
+
+    await persisterFn(queryFn, context, query)
+
+    expect(await storage.getItem(storageKey)).toBeUndefined()
+
+    expect(queryFn).toHaveBeenCalledOnce()
+    expect(queryFn).toHaveBeenCalledWith(context)
+  })
+
+  test('should remove stored item if its expired', async () => {
+    const storage = getFreshStorage()
+    const { context, persisterFn, query, queryFn, storageKey } = setupPersister(
+      ['foo'],
+      {
+        storage,
+        maxAge: 100,
+      },
+    )
+
+    await storage.setItem(
+      storageKey,
+      JSON.stringify({
+        buster: '',
+        state: { dataUpdatedAt: Date.now() - 200 },
+      }),
+    )
+
+    await persisterFn(queryFn, context, query)
+
+    expect(await storage.getItem(storageKey)).toBeUndefined()
+
+    expect(queryFn).toHaveBeenCalledOnce()
+    expect(queryFn).toHaveBeenCalledWith(context)
+  })
+
+  test('should remove stored item if its busted', async () => {
+    const storage = getFreshStorage()
+    const { context, persisterFn, query, queryFn, storageKey } = setupPersister(
+      ['foo'],
+      {
+        storage,
+      },
+    )
+
+    await storage.setItem(
+      storageKey,
+      JSON.stringify({
+        buster: 'bust',
+        state: { dataUpdatedAt: Date.now() },
+      }),
+    )
+
+    await persisterFn(queryFn, context, query)
+
+    expect(await storage.getItem(storageKey)).toBeUndefined()
+
+    expect(queryFn).toHaveBeenCalledOnce()
+    expect(queryFn).toHaveBeenCalledWith(context)
+  })
+
+  test('should restore item from the storage and set proper `updatedAt` values', async () => {
+    const storage = getFreshStorage()
+    const { context, persisterFn, query, queryFn, storageKey } = setupPersister(
+      ['foo'],
+      {
+        storage,
+      },
+    )
+
+    const dataUpdatedAt = Date.now()
+
+    await storage.setItem(
+      storageKey,
+      JSON.stringify({
+        buster: '',
+        state: { dataUpdatedAt },
+      }),
+    )
+
+    await persisterFn(queryFn, context, query)
+    query.state.dataUpdatedAt = 0
+    query.fetch = vi.fn()
+    expect(query.state.dataUpdatedAt).toEqual(0)
+
+    await sleep(0)
+
+    expect(queryFn).toHaveBeenCalledTimes(0)
+    expect(query.fetch).toHaveBeenCalledTimes(0)
+    expect(query.state.dataUpdatedAt).toEqual(dataUpdatedAt)
+  })
+
+  test('should restore item from the storage and refetch when `stale`', async () => {
+    const storage = getFreshStorage()
+    const { context, persisterFn, query, queryFn, storageKey } = setupPersister(
+      ['foo'],
+      {
+        storage,
+      },
+    )
+
+    await storage.setItem(
+      storageKey,
+      JSON.stringify({
+        buster: '',
+        state: { dataUpdatedAt: Date.now() },
+      }),
+    )
+
+    await persisterFn(queryFn, context, query)
+    query.state.isInvalidated = true
+    query.fetch = vi.fn()
+
+    await sleep(0)
+
+    expect(queryFn).toHaveBeenCalledTimes(0)
+    expect(query.fetch).toHaveBeenCalledTimes(1)
+  })
+
+  test('should store item after successfull fetch', async () => {
+    const storage = getFreshStorage()
+    const {
+      context,
+      persisterFn,
+      query,
+      queryFn,
+      queryHash,
+      queryKey,
+      storageKey,
+    } = setupPersister(['foo'], {
+      storage,
+    })
+
+    await persisterFn(queryFn, context, query)
+    query.setData('baz')
+
+    await sleep(0)
+
+    expect(queryFn).toHaveBeenCalledOnce()
+    expect(queryFn).toHaveBeenCalledWith(context)
+
+    expect(JSON.parse(await storage.getItem(storageKey))).toMatchObject({
+      buster: '',
+      queryHash,
+      queryKey,
+      state: {
+        data: 'baz',
+      },
+    })
+  })
+
+  test('should skip stored item if not matched by filters', async () => {
+    const storage = getFreshStorage()
+    const { context, persisterFn, query, queryFn, storageKey } = setupPersister(
+      ['foo'],
+      {
+        storage,
+        filters: {
+          predicate: () => {
+            return false
+          },
+        },
+      },
+    )
+
+    const dataUpdatedAt = Date.now()
+
+    await storage.setItem(
+      storageKey,
+      JSON.stringify({
+        buster: '',
+        state: { dataUpdatedAt },
+      }),
+    )
+
+    await persisterFn(queryFn, context, query)
+    query.fetch = vi.fn()
+
+    await sleep(0)
+
+    expect(queryFn).toHaveBeenCalledTimes(1)
+    expect(query.fetch).toHaveBeenCalledTimes(0)
+  })
+})

package/src/createPersister.ts

@@ -0,0 +1,160 @@
+import { matchQuery } from '@tanstack/query-core'
+import type { QueryFilters } from '@tanstack/query-core'
+import type {
+  Query,
+  QueryFunctionContext,
+  QueryKey,
+  QueryState,
+} from '@tanstack/query-core'
+
+export interface PersistedQuery {
+  buster: string
+  queryHash: string
+  queryKey: QueryKey
+  state: QueryState
+}
+
+export interface AsyncStorage {
+  getItem: (key: string) => Promise<string | undefined | null>
+  setItem: (key: string, value: string) => Promise<unknown>
+  removeItem: (key: string) => Promise<void>
+}
+
+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`.
+   * @default 'tanstack-query'
+   */
+  prefix?: string
+  /**
+   * Filters to narrow down which Queries should be persisted.
+   */
+  filters?: QueryFilters
+}
+
+export const PERSISTER_KEY_PREFIX = 'tanstack-query'
+
+/**
+ * Warning: experimental feature.
+ * This utility function enables fine-grained query persistance.
+ * Simple add it as a `persister` parameter to `useQuery` or `defaultOptions` on `queryClient`.
+ *
+ * ```
+ * useQuery({
+     queryKey: ['myKey'],
+     queryFn: fetcher,
+     persister: createPersister({
+       storage: localStorage,
+     }),
+   })
+   ```
+ */
+export function experimental_createPersister({
+  storage,
+  buster = '',
+  maxAge = 1000 * 60 * 60 * 24,
+  serialize = JSON.stringify,
+  deserialize = JSON.parse,
+  prefix = PERSISTER_KEY_PREFIX,
+  filters,
+}: StoragePersisterOptions) {
+  return async function persisterFn<T, TQueryKey extends QueryKey>(
+    queryFn: (context: QueryFunctionContext<TQueryKey>) => T | Promise<T>,
+    context: QueryFunctionContext<TQueryKey>,
+    query: Query,
+  ) {
+    const storageKey = `${prefix}-${query.queryHash}`
+    const matchesFilter = filters ? matchQuery(filters, query) : true
+
+    // Try to restore only if we do not have any data in the cache and we have persister defined
+    if (matchesFilter && query.state.data === undefined && storage != null) {
+      try {
+        const storedData = await storage.getItem(storageKey)
+        if (storedData) {
+          const persistedQuery = deserialize(storedData)
+
+          if (persistedQuery.state.dataUpdatedAt) {
+            const queryAge = Date.now() - persistedQuery.state.dataUpdatedAt
+            const expired = queryAge > maxAge
+            const busted = persistedQuery.buster !== buster
+            if (expired || busted) {
+              await storage.removeItem(storageKey)
+            } else {
+              // Just after restoring we want to get fresh data from the server if it's stale
+              setTimeout(() => {
+                // Set proper updatedAt, since resolving in the first pass overrides those values
+                query.setState({
+                  dataUpdatedAt: persistedQuery.state.dataUpdatedAt,
+                  errorUpdatedAt: persistedQuery.state.errorUpdatedAt,
+                })
+
+                if (query.isStale()) {
+                  query.fetch()
+                }
+              }, 0)
+              // We must resolve the promise here, as otherwise we will have `loading` state in the app until `queryFn` resolves
+              return Promise.resolve(persistedQuery.state.data as T)
+            }
+          } else {
+            await storage.removeItem(storageKey)
+          }
+        }
+      } catch (err) {
+        if (process.env.NODE_ENV === 'development') {
+          console.error(err)
+          console.warn(
+            'Encountered an error attempting to restore query cache from persisted location.',
+          )
+        }
+        await storage.removeItem(storageKey)
+      }
+    }
+
+    // If we did not restore, or restoration failed - fetch
+    const queryFnResult = await queryFn(context)
+
+    if (matchesFilter && storage != null) {
+      // Persist if we have storage defined, we use timeout to get proper state to be persisted
+      setTimeout(() => {
+        storage.setItem(
+          storageKey,
+          serialize({
+            state: query.state,
+            queryKey: query.queryKey,
+            queryHash: query.queryHash,
+            buster: buster,
+          }),
+        )
+      }, 0)
+    }
+
+    return Promise.resolve(queryFnResult)
+  }
+}

package/src/index.ts

@@ -2,3 +2,4 @@
 
 export * from './persist'
 export * from './retryStrategies'
+export * from './createPersister'