@tanstack/query-persist-client-core 5.0.0-beta.6 → 5.0.0-rc.0

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 };