@krymskyimaksym/react-api-client 1.0.0 → 2.0.0-beta.1

package/dist/index.js

@@ -21,6 +21,68 @@ function isConfigured() {
   return globalConfig !== null;
 }
 
+// src/errors.ts
+var ApiError = class _ApiError extends Error {
+  constructor(init) {
+    super(init.message);
+    this.name = "ApiError";
+    this.status = init.status;
+    this.code = init.code;
+    this.errors = init.errors;
+    this.isNetworkError = init.isNetworkError ?? false;
+    this.isUnauthorized = init.isUnauthorized ?? init.status === 401;
+    this.isValidationError = init.isValidationError ?? (init.status === 422 || init.errors !== void 0 && init.errors !== null);
+    this.raw = init.raw;
+    Object.setPrototypeOf(this, _ApiError.prototype);
+  }
+};
+var isObject = (v) => typeof v === "object" && v !== null;
+function toApiError(thrown) {
+  if (thrown instanceof ApiError) return thrown;
+  if (isObject(thrown) && "response" in thrown && isObject(thrown.response)) {
+    const r = thrown.response;
+    const status = typeof r.status === "number" ? r.status : 0;
+    const data = isObject(r.data) ? r.data : void 0;
+    const message = (data && typeof data.message === "string" ? data.message : void 0) ?? (thrown instanceof Error ? thrown.message : void 0) ?? `HTTP ${status}`;
+    return new ApiError({
+      message,
+      status,
+      code: data && typeof data.code === "string" ? data.code : void 0,
+      errors: data?.errors,
+      isNetworkError: status === 0,
+      isUnauthorized: status === 401,
+      isValidationError: status === 422 || data?.errors !== void 0,
+      raw: r.data ?? thrown
+    });
+  }
+  if (thrown instanceof Error) {
+    return new ApiError({
+      message: thrown.message,
+      status: 0,
+      isNetworkError: true,
+      raw: thrown
+    });
+  }
+  return new ApiError({
+    message: "Unknown error",
+    status: 0,
+    raw: thrown
+  });
+}
+function businessErrorToApiError(response) {
+  if (!isObject(response)) {
+    return new ApiError({ message: "Request failed", status: 200, raw: response });
+  }
+  return new ApiError({
+    message: typeof response.message === "string" ? response.message : "Request failed",
+    status: 200,
+    code: typeof response.code === "string" ? response.code : void 0,
+    errors: response.errors,
+    isValidationError: response.errors !== void 0,
+    raw: response
+  });
+}
+
 // src/utils.ts
 function buildEndpoint(endpoint, params) {
   if (typeof endpoint === "function" && typeof params !== "undefined") {
@@ -28,7 +90,7 @@ function buildEndpoint(endpoint, params) {
   }
   return endpoint;
 }
-async function executeRequest(endpoint, fetchConfig, params) {
+async function executeRequest(endpoint, fetchConfig, params, signal) {
   const url = buildEndpoint(endpoint, params);
   const config = getConfig();
   try {
@@ -39,7 +101,8 @@ async function executeRequest(endpoint, fetchConfig, params) {
         params: {
           ...requestConfig.requestParams,
           ...params
-        }
+        },
+        signal
       });
     } else {
       response = await config.httpClient.request(url, {
@@ -47,15 +110,30 @@ async function executeRequest(endpoint, fetchConfig, params) {
         data: {
           ...requestConfig.requestParams,
           ...params
-        }
+        },
+        signal
       });
     }
+    const hasExplicitStatus = response && typeof response === "object" && "status" in response && typeof response.status === "boolean";
+    if (config.throwOnError && hasExplicitStatus && response.status === false) {
+      throw businessErrorToApiError(response);
+    }
     return { ...response, status: true };
   } catch (e) {
+    if (e instanceof ApiError) {
+      if (e.status === 401 && config.onUnauthorized) {
+        await config.onUnauthorized();
+      }
+      throw e;
+    }
     const error = e;
-    if (error.response?.status === 401 && config.onUnauthorized) {
+    const httpStatus = error.response?.status;
+    if (httpStatus === 401 && config.onUnauthorized) {
       await config.onUnauthorized();
     }
+    if (config.throwOnError) {
+      throw toApiError(e);
+    }
     if (error.response?.data) {
       return {
         ...error.response.data,
@@ -64,7 +142,7 @@ async function executeRequest(endpoint, fetchConfig, params) {
     }
     return {
       status: false,
-      message: error instanceof Error ? error.message : "Request error"
+      message: e instanceof Error ? e.message : "Request error"
     };
   }
 }
@@ -76,78 +154,562 @@ function handleResponse(result, onSuccess, onError) {
     onError(err);
   }
 }
+
+// src/query/focus-manager.ts
+var FocusManager = class {
+  constructor() {
+    this.focused = true;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.cleanup = null;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    this.setupBrowserListeners();
+    return () => {
+      this.listeners.delete(listener);
+      if (this.listeners.size === 0) this.teardownBrowserListeners();
+    };
+  }
+  isFocused() {
+    return this.focused;
+  }
+  setFocused(focused) {
+    if (this.focused === focused) return;
+    this.focused = focused;
+    for (const l of this.listeners) l(focused);
+  }
+  setupBrowserListeners() {
+    if (this.cleanup) return;
+    if (typeof window === "undefined" || typeof window.addEventListener !== "function") {
+      return;
+    }
+    const onFocus = () => this.setFocused(true);
+    const onVisibility = () => {
+      if (typeof document !== "undefined") {
+        this.setFocused(document.visibilityState !== "hidden");
+      }
+    };
+    window.addEventListener("focus", onFocus);
+    if (typeof document !== "undefined") {
+      document.addEventListener("visibilitychange", onVisibility);
+    }
+    this.cleanup = () => {
+      window.removeEventListener("focus", onFocus);
+      if (typeof document !== "undefined") {
+        document.removeEventListener("visibilitychange", onVisibility);
+      }
+    };
+  }
+  teardownBrowserListeners() {
+    this.cleanup?.();
+    this.cleanup = null;
+  }
+};
+var focusManager = new FocusManager();
+
+// src/query/online-manager.ts
+var OnlineManager = class {
+  constructor() {
+    this.online = true;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.cleanup = null;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    this.setupBrowserListeners();
+    return () => {
+      this.listeners.delete(listener);
+      if (this.listeners.size === 0) this.teardownBrowserListeners();
+    };
+  }
+  isOnline() {
+    return this.online;
+  }
+  setOnline(online) {
+    if (this.online === online) return;
+    this.online = online;
+    for (const l of this.listeners) l(online);
+  }
+  setupBrowserListeners() {
+    if (this.cleanup) return;
+    if (typeof window === "undefined" || typeof window.addEventListener !== "function") {
+      return;
+    }
+    if (typeof navigator !== "undefined" && "onLine" in navigator) {
+      this.online = navigator.onLine;
+    }
+    const onOnline = () => this.setOnline(true);
+    const onOffline = () => this.setOnline(false);
+    window.addEventListener("online", onOnline);
+    window.addEventListener("offline", onOffline);
+    this.cleanup = () => {
+      window.removeEventListener("online", onOnline);
+      window.removeEventListener("offline", onOffline);
+    };
+  }
+  teardownBrowserListeners() {
+    this.cleanup?.();
+    this.cleanup = null;
+  }
+};
+var onlineManager = new OnlineManager();
+
+// src/query/key.ts
+function hashQueryKey(key) {
+  return JSON.stringify(key, (_, value) => {
+    if (typeof value === "function") {
+      throw new Error(
+        "react-api-client: \u0444\u0443\u043D\u043A\u0446\u0438\u0438 \u0437\u0430\u043F\u0440\u0435\u0449\u0435\u043D\u044B \u0432 queryKey \u2014 \u043A\u043B\u044E\u0447 \u0434\u043E\u043B\u0436\u0435\u043D \u0431\u044B\u0442\u044C \u0441\u0435\u0440\u0438\u0430\u043B\u0438\u0437\u0443\u0435\u043C"
+      );
+    }
+    if (typeof value === "symbol") {
+      throw new Error(
+        "react-api-client: symbol \u0437\u0430\u043F\u0440\u0435\u0449\u0435\u043D\u044B \u0432 queryKey \u2014 \u043A\u043B\u044E\u0447 \u0434\u043E\u043B\u0436\u0435\u043D \u0431\u044B\u0442\u044C \u0441\u0435\u0440\u0438\u0430\u043B\u0438\u0437\u0443\u0435\u043C"
+      );
+    }
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const sortedKeys = Object.keys(value).sort();
+      const result = {};
+      for (const k of sortedKeys) {
+        const v = value[k];
+        if (v !== void 0) result[k] = v;
+      }
+      return result;
+    }
+    return value;
+  });
+}
+function matchQueryKey(prefix, key) {
+  if (prefix.length > key.length) return false;
+  for (let i = 0; i < prefix.length; i++) {
+    if (hashQueryKey([prefix[i]]) !== hashQueryKey([key[i]])) return false;
+  }
+  return true;
+}
+
+// src/query/cache.ts
+var DEFAULT_GC_TIME = 5 * 60 * 1e3;
+var DEFAULT_STALE_TIME = 0;
+var QueryCache = class {
+  constructor() {
+    this.entries = /* @__PURE__ */ new Map();
+    this.globalListeners = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Подписка на любое изменение кэша: setData, invalidate, remove,
+   * успешный/ошибочный fetch. Используется persistQueryClient и
+   * devtools-подобными адаптерами. Не дублирует `subscribe(key, ...)`.
+   */
+  subscribeAll(listener) {
+    this.globalListeners.add(listener);
+    return () => {
+      this.globalListeners.delete(listener);
+    };
+  }
+  notifyGlobal() {
+    for (const listener of this.globalListeners) listener();
+  }
+  ensureEntry(key, staleTime, gcTime) {
+    const hash = hashQueryKey(key);
+    let entry = this.entries.get(hash);
+    if (!entry) {
+      entry = {
+        key,
+        state: {
+          data: void 0,
+          error: null,
+          status: "idle",
+          updatedAt: 0,
+          isStale: true
+        },
+        subscribers: /* @__PURE__ */ new Set(),
+        inflight: null,
+        inflightController: null,
+        gcTimer: null,
+        staleTime: staleTime ?? DEFAULT_STALE_TIME,
+        gcTime: gcTime ?? DEFAULT_GC_TIME
+      };
+      this.entries.set(hash, entry);
+    } else {
+      if (staleTime !== void 0) entry.staleTime = staleTime;
+      if (gcTime !== void 0) entry.gcTime = gcTime;
+    }
+    return entry;
+  }
+  getState(key) {
+    const entry = this.entries.get(hashQueryKey(key));
+    return entry?.state;
+  }
+  getData(key) {
+    return this.getState(key)?.data;
+  }
+  setData(key, updater) {
+    const entry = this.ensureEntry(key);
+    const next = typeof updater === "function" ? updater(entry.state.data) : updater;
+    entry.state = {
+      data: next,
+      error: null,
+      status: "success",
+      updatedAt: Date.now(),
+      isStale: false
+    };
+    this.notify(entry);
+  }
+  /**
+   * Подписка на изменения ключа. Возвращает unsubscribe.
+   * Подписка останавливает GC таймер; отписка — запускает его обратно.
+   */
+  subscribe(key, listener) {
+    const entry = this.ensureEntry(key);
+    entry.subscribers.add(listener);
+    if (entry.gcTimer) {
+      clearTimeout(entry.gcTimer);
+      entry.gcTimer = null;
+    }
+    return () => {
+      entry.subscribers.delete(listener);
+      if (entry.subscribers.size === 0) this.scheduleGc(entry);
+    };
+  }
+  notify(entry) {
+    for (const listener of entry.subscribers) listener();
+    this.notifyGlobal();
+  }
+  scheduleGc(entry) {
+    if (entry.gcTimer) clearTimeout(entry.gcTimer);
+    if (entry.gcTime <= 0) {
+      this.entries.delete(hashQueryKey(entry.key));
+      return;
+    }
+    entry.gcTimer = setTimeout(() => {
+      if (entry.subscribers.size === 0 && !entry.inflight) {
+        this.entries.delete(hashQueryKey(entry.key));
+      }
+    }, entry.gcTime);
+  }
+  /**
+   * Запускает или присоединяется к inflight-запросу.
+   * Если данные свежие (не stale) и не force — отдаёт кэш без запроса.
+   */
+  async fetch(key, queryFn, options = {}) {
+    const staleTime = options.staleTime ?? DEFAULT_STALE_TIME;
+    const gcTime = options.gcTime ?? DEFAULT_GC_TIME;
+    const entry = this.ensureEntry(key, staleTime, gcTime);
+    const isFresh = entry.state.status === "success" && !entry.state.isStale && Date.now() - entry.state.updatedAt < staleTime;
+    if (!options.force && isFresh && entry.state.data !== void 0) {
+      return entry.state.data;
+    }
+    if (entry.inflight) return entry.inflight;
+    entry.state = { ...entry.state, status: "loading", error: null };
+    this.notify(entry);
+    const controller = new AbortController();
+    const token = Symbol("inflight");
+    entry.inflightToken = token;
+    entry.inflightController = controller;
+    const isCurrent = () => entry.inflightToken === token;
+    const myPromise = (async () => {
+      try {
+        const data = await queryFn({ signal: controller.signal });
+        if (!isCurrent()) return data;
+        entry.state = {
+          data,
+          error: null,
+          status: "success",
+          updatedAt: Date.now(),
+          isStale: false
+        };
+        this.notify(entry);
+        return data;
+      } catch (err) {
+        if (!isCurrent()) throw err;
+        entry.state = {
+          ...entry.state,
+          status: "error",
+          error: err
+        };
+        this.notify(entry);
+        throw err;
+      } finally {
+        if (isCurrent()) {
+          entry.inflight = null;
+          entry.inflightController = null;
+        }
+      }
+    })();
+    entry.inflight = myPromise;
+    return myPromise;
+  }
+  /**
+   * Помечает запись как stale. Сами по себе данные не удаляются.
+   * Если есть подписчики — они получат уведомление, чтобы инициировать refetch.
+   */
+  invalidate(predicate) {
+    const invalidated = [];
+    const match = typeof predicate === "function" ? predicate : (k) => matchQueryKey(predicate, k);
+    for (const [hash, entry] of this.entries) {
+      if (match(entry.key)) {
+        entry.state = { ...entry.state, isStale: true };
+        this.notify(entry);
+        invalidated.push(hash);
+      }
+    }
+    return invalidated;
+  }
+  /**
+   * Отменяет «привязку» inflight-промиса к ключу. Сам HTTP-запрос
+   * продолжит исполняться (executeRequest не использует AbortSignal),
+   * но его результат больше не попадёт в кэш и не уведомит подписчиков.
+   * Полезно при размонтировании / при переключении страниц.
+   */
+  cancelQueries(predicate) {
+    const match = typeof predicate === "function" ? predicate : (k) => matchQueryKey(predicate, k);
+    for (const entry of this.entries.values()) {
+      if (match(entry.key) && entry.inflight) {
+        entry.inflightController?.abort();
+        entry.inflightController = null;
+        entry.inflight = null;
+        entry.inflightToken = void 0;
+        if (entry.state.status === "loading") {
+          entry.state = { ...entry.state, status: "idle" };
+          this.notify(entry);
+        }
+      }
+    }
+  }
+  /**
+   * Полностью удаляет записи (даже с активными подписчиками).
+   * Используется редко — обычно достаточно invalidate.
+   */
+  remove(predicate) {
+    const match = typeof predicate === "function" ? predicate : (k) => matchQueryKey(predicate, k);
+    let removed = false;
+    for (const [hash, entry] of [...this.entries]) {
+      if (match(entry.key)) {
+        if (entry.gcTimer) clearTimeout(entry.gcTimer);
+        this.entries.delete(hash);
+        removed = true;
+      }
+    }
+    if (removed) this.notifyGlobal();
+  }
+  /** Только для тестов / DevTools. */
+  _debugEntries() {
+    return this.entries;
+  }
+  /**
+   * Сериализует записи со статусом success — для persistence.
+   * inflight / loading / error не сохраняются, чтобы не гидратировать
+   * приложение в полу-загруженном состоянии.
+   */
+  dehydrate(filter) {
+    const queries = [];
+    for (const entry of this.entries.values()) {
+      if (entry.state.status !== "success") continue;
+      if (entry.state.data === void 0) continue;
+      if (filter && !filter(entry.key)) continue;
+      queries.push({
+        key: entry.key,
+        data: entry.state.data,
+        updatedAt: entry.state.updatedAt
+      });
+    }
+    return { queries };
+  }
+  hydrate(state) {
+    for (const q of state.queries) {
+      const entry = this.ensureEntry(q.key);
+      if (entry.state.updatedAt >= q.updatedAt && entry.state.data !== void 0) {
+        continue;
+      }
+      entry.state = {
+        data: q.data,
+        error: null,
+        status: "success",
+        updatedAt: q.updatedAt,
+        isStale: true
+        // гидратированные данные сразу stale → фоновый refetch
+      };
+      this.notify(entry);
+    }
+  }
+};
+
+// src/query/client.ts
+var QueryClient = class {
+  constructor(cache) {
+    this.cache = cache ?? new QueryCache();
+  }
+  getQueryData(key) {
+    return this.cache.getData(key);
+  }
+  setQueryData(key, updater) {
+    this.cache.setData(key, updater);
+  }
+  fetchQuery(key, queryFn, options) {
+    return this.cache.fetch(key, queryFn, options);
+  }
+  invalidateQueries(predicate) {
+    this.cache.invalidate(predicate);
+  }
+  removeQueries(predicate) {
+    this.cache.remove(predicate);
+  }
+  cancelQueries(predicate) {
+    this.cache.cancelQueries(predicate);
+  }
+};
+var globalClient = null;
+function getQueryClient() {
+  if (!globalClient) globalClient = new QueryClient();
+  return globalClient;
+}
+function setQueryClient(client) {
+  globalClient = client;
+}
+
+// src/hooks/use-fetch.ts
 function createUseFetch(endpoint, fetchConfig) {
   return (params, options = {}) => {
     const {
       enabled = true,
       refetchOnMount = true,
+      refetchOnFocus = false,
+      refetchOnAppActive = false,
+      refetchOnReconnect = false,
+      staleTime = 0,
+      gcTime,
+      pollingInterval,
+      queryKey: customKey,
+      select,
       onSuccess,
       onError
     } = options;
-    const [data, setData] = react.useState(null);
-    const [isLoading, setIsLoading] = react.useState(enabled && refetchOnMount);
-    const [isRefetching, setIsRefetching] = react.useState(false);
-    const [error, setError] = react.useState(null);
-    const isMountedRef = react.useRef(true);
     const serializedParams = react.useMemo(
-      () => params ? JSON.stringify(params) : null,
+      () => params === void 0 ? null : JSON.stringify(params),
       [params]
     );
-    const fetchData = react.useCallback(
-      async (isRefetch = false) => {
-        if (!enabled) return;
+    const queryKey = react.useMemo(() => {
+      if (customKey) return customKey;
+      const endpointId = typeof endpoint === "function" ? buildEndpoint(endpoint, params) : endpoint;
+      return ["__endpoint__", endpointId, params ?? null];
+    }, [customKey ? hashQueryKey(customKey) : null, serializedParams]);
+    const client = getQueryClient();
+    const cache = client.cache;
+    const queryFn = react.useCallback(
+      ({ signal }) => {
+        const parsedParams = serializedParams ? JSON.parse(serializedParams) : void 0;
+        return executeRequest(endpoint, fetchConfig, parsedParams, signal);
+      },
+      [serializedParams]
+    );
+    const initialState = cache.getState(queryKey);
+    const [, forceRender] = react.useState(0);
+    const rerender = react.useCallback(() => forceRender((v) => v + 1), []);
+    react.useEffect(() => {
+      const unsub = cache.subscribe(queryKey, rerender);
+      return () => {
+        unsub();
+        const state2 = cache._debugEntries().get(hashQueryKey(queryKey));
+        if (state2 && state2.subscribers.size === 0 && state2.inflight) {
+          cache.cancelQueries(queryKey);
+        }
+      };
+    }, [cache, hashQueryKey(queryKey), rerender]);
+    const lastNotifiedRef = react.useRef({});
+    const runFetch = react.useCallback(
+      async (force) => {
         try {
-          if (isRefetch) {
-            setIsRefetching(true);
-          } else {
-            setIsLoading(true);
-          }
-          setError(null);
-          const parsedParams = serializedParams ? JSON.parse(serializedParams) : void 0;
-          const result = await executeRequest(endpoint, fetchConfig, parsedParams);
-          if (isMountedRef.current) {
-            setData(result);
+          const data = await cache.fetch(queryKey, queryFn, {
+            staleTime,
+            gcTime,
+            force
+          });
+          if (lastNotifiedRef.current.success !== data) {
+            lastNotifiedRef.current.success = data;
             handleResponse(
-              result,
+              data,
               onSuccess,
               onError
             );
           }
         } catch (err) {
-          const error2 = err;
-          if (isMountedRef.current) {
-            setError(error2);
-            if (onError) {
-              onError(error2);
-            }
-          }
-        } finally {
-          if (isMountedRef.current) {
-            if (isRefetch) {
-              setIsRefetching(false);
-            } else {
-              setIsLoading(false);
-            }
+          const e = err;
+          const hash = `${e.name}:${e.message}`;
+          if (lastNotifiedRef.current.errorHash !== hash) {
+            lastNotifiedRef.current.errorHash = hash;
+            onError?.(e);
           }
         }
       },
-      [enabled, serializedParams, onSuccess, onError]
+      [cache, hashQueryKey(queryKey), queryFn, staleTime, gcTime, onSuccess, onError]
     );
-    const refetch = react.useCallback(async () => {
-      await fetchData(true);
-    }, [fetchData]);
     react.useEffect(() => {
-      isMountedRef.current = true;
-      if (enabled && refetchOnMount) {
-        void fetchData(false);
-      }
+      if (!enabled || !refetchOnMount) return;
+      void runFetch(false);
+    }, [enabled, refetchOnMount, runFetch]);
+    const stateForEffect = cache.getState(queryKey);
+    const isStale = stateForEffect?.isStale ?? false;
+    const hasFetchedData = stateForEffect?.data !== void 0;
+    react.useEffect(() => {
+      if (!enabled) return;
+      if (isStale && hasFetchedData) void runFetch(true);
+    }, [enabled, isStale, hasFetchedData, runFetch]);
+    react.useEffect(() => {
+      if (!enabled) return;
+      if (!refetchOnFocus && !refetchOnAppActive) return;
+      const unsub = focusManager.subscribe((focused) => {
+        if (focused) void runFetch(false);
+      });
+      return unsub;
+    }, [enabled, refetchOnFocus, refetchOnAppActive, runFetch]);
+    react.useEffect(() => {
+      if (!enabled || !refetchOnReconnect) return;
+      const unsub = onlineManager.subscribe((online) => {
+        if (online) void runFetch(false);
+      });
+      return unsub;
+    }, [enabled, refetchOnReconnect, runFetch]);
+    react.useEffect(() => {
+      if (!enabled || !pollingInterval || pollingInterval <= 0) return;
+      let timer = null;
+      const start = () => {
+        if (timer) return;
+        timer = setInterval(() => {
+          if (focusManager.isFocused()) void runFetch(true);
+        }, pollingInterval);
+      };
+      const stop = () => {
+        if (timer) clearInterval(timer);
+        timer = null;
+      };
+      start();
+      const unsub = focusManager.subscribe((focused) => {
+        if (focused) start();
+        else stop();
+      });
       return () => {
-        isMountedRef.current = false;
+        stop();
+        unsub();
       };
-    }, [enabled, refetchOnMount, fetchData]);
+    }, [enabled, pollingInterval, runFetch]);
+    const state = cache.getState(queryKey) ?? initialState;
+    const rawData = state?.data ?? null;
+    const selectedData = react.useMemo(() => {
+      if (rawData === null) return null;
+      if (!select) return rawData;
+      return select(rawData);
+    }, [rawData, select]);
+    const status = state?.status ?? "idle";
+    const hasData = rawData !== null;
+    const isLoading = status === "loading" && !hasData;
+    const isRefetching = status === "loading" && hasData;
+    const error = state?.error ?? null;
+    const refetch = react.useCallback(async () => {
+      await runFetch(true);
+    }, [runFetch]);
     return {
-      data,
-      isLoading,
+      data: selectedData,
+      isLoading: enabled ? isLoading : false,
       isRefetching,
       error,
       refetch
@@ -156,7 +718,14 @@ function createUseFetch(endpoint, fetchConfig) {
 }
 function createUseMutation(endpoint, fetchConfig) {
   return (options = {}) => {
-    const { onMutate, onSuccess, onError, onSettled } = options;
+    const {
+      onMutate,
+      onSuccess,
+      onError,
+      onSettled,
+      invalidateKeys,
+      setQueryData
+    } = options;
     const [data, setData] = react.useState(null);
     const [error, setError] = react.useState(null);
     const [isLoading, setIsLoading] = react.useState(false);
@@ -169,33 +738,51 @@ function createUseMutation(endpoint, fetchConfig) {
       setIsSuccess(false);
       setIsError(false);
     }, []);
+    const applyInvalidate = react.useCallback(
+      (vars, result) => {
+        if (!invalidateKeys) return;
+        const client = getQueryClient();
+        const keys = typeof invalidateKeys === "function" ? invalidateKeys(vars, result) : invalidateKeys;
+        if (keys.length === 0) return;
+        client.invalidateQueries(
+          (k) => keys.some((prefix) => matchQueryKey(prefix, k))
+        );
+      },
+      [invalidateKeys]
+    );
     const mutateAsync = react.useCallback(
       async (variables) => {
         setIsLoading(true);
         setIsSuccess(false);
         setIsError(false);
         setError(null);
+        let context;
         try {
           if (onMutate) {
-            await onMutate(variables);
+            const ctx = await onMutate(variables);
+            context = ctx;
           }
           const result = await executeRequest(endpoint, fetchConfig, variables);
           setData(result);
           if (result.status) {
             setIsSuccess(true);
+            if (setQueryData) {
+              setQueryData(getQueryClient(), variables, result);
+            }
+            applyInvalidate(variables, result);
             if (onSuccess) {
-              await onSuccess(result, variables);
+              await onSuccess(result, variables, context);
             }
           } else {
             const err = new Error(result.message ?? "Mutation failed");
             setIsError(true);
             setError(err);
             if (onError) {
-              await onError(err, variables);
+              await onError(err, variables, context);
             }
           }
           if (onSettled) {
-            await onSettled(result, null, variables);
+            await onSettled(result, null, variables, context);
           }
           return result;
         } catch (err) {
@@ -204,17 +791,24 @@ function createUseMutation(endpoint, fetchConfig) {
           setIsError(true);
           setIsSuccess(false);
           if (onError) {
-            await onError(error2, variables);
+            await onError(error2, variables, context);
           }
           if (onSettled) {
-            await onSettled(null, error2, variables);
+            await onSettled(null, error2, variables, context);
           }
           throw error2;
         } finally {
           setIsLoading(false);
         }
       },
-      [onMutate, onSuccess, onError, onSettled]
+      [
+        onMutate,
+        onSuccess,
+        onError,
+        onSettled,
+        setQueryData,
+        applyInvalidate
+      ]
     );
     const mutateSync = react.useCallback(
       (variables) => {
@@ -240,127 +834,153 @@ function createUsePaginate(endpoint, fetchConfig, options) {
       enabled = true,
       initialPage = 1,
       initialLimit = 20,
+      staleTime = 0,
+      gcTime,
+      keepPreviousData = false,
+      queryKey: customKey,
       onSuccess,
       onError
     } = hookOptions;
-    const [data, setData] = react.useState([]);
+    const client = getQueryClient();
+    const cache = client.cache;
+    const limit = initialLimit;
     const [currentPage, setCurrentPage] = react.useState(initialPage);
-    const [totalPages, setTotalPages] = react.useState(null);
-    const [total, setTotal] = react.useState(null);
-    const [isLoading, setIsLoading] = react.useState(enabled);
     const [isFetchingNextPage, setIsFetchingNextPage] = react.useState(false);
     const [error, setError] = react.useState(null);
-    const isMountedRef = react.useRef(true);
-    const limit = initialLimit;
     const dataExtractor = react.useMemo(
       () => options?.dataExtractor || ((response) => response.data),
+      // eslint-disable-next-line react-hooks/exhaustive-deps
       []
     );
     const totalExtractor = react.useMemo(
       () => options?.totalExtractor || ((response) => response.total ?? 0),
+      // eslint-disable-next-line react-hooks/exhaustive-deps
       []
     );
     const serializedParams = react.useMemo(
-      () => params ? JSON.stringify(params) : null,
+      () => params === void 0 ? null : JSON.stringify(params),
       [params]
     );
-    const fetchPage = react.useCallback(
-      async (page, append = false) => {
-        if (!enabled) return;
+    const keyPrefix = react.useMemo(() => {
+      if (customKey) return customKey;
+      const endpointId = typeof endpoint === "function" ? buildEndpoint(
+        endpoint,
+        params
+      ) : endpoint;
+      return ["__paginate__", endpointId, params ?? null];
+    }, [customKey ? hashQueryKey(customKey) : null, serializedParams]);
+    const pageKey = react.useCallback(
+      (page) => [...keyPrefix, { page, limit }],
+      [keyPrefix, limit]
+    );
+    const pageQueryFn = react.useCallback(
+      (page) => ({ signal }) => {
+        const parsedParams = serializedParams ? JSON.parse(serializedParams) : {};
+        const requestParams = {
+          ...parsedParams,
+          page,
+          limit
+        };
+        return executeRequest(endpoint, fetchConfig, requestParams, signal);
+      },
+      [serializedParams, limit]
+    );
+    const [, forceRender] = react.useState(0);
+    const rerender = react.useCallback(() => forceRender((v) => v + 1), []);
+    react.useEffect(() => {
+      if (!enabled) return;
+      const unsub = cache.subscribe(pageKey(currentPage), rerender);
+      return unsub;
+    }, [cache, enabled, hashQueryKey(pageKey(currentPage)), rerender]);
+    const previousPageKeyRef = react.useRef(null);
+    const runFetchPage = react.useCallback(
+      async (page, isNextPage) => {
         try {
-          if (append) {
-            setIsFetchingNextPage(true);
-          } else {
-            setIsLoading(true);
-          }
+          if (isNextPage) setIsFetchingNextPage(true);
           setError(null);
-          const parsedParams = serializedParams ? JSON.parse(serializedParams) : {};
-          const requestParams = {
-            ...parsedParams,
-            page,
-            limit
-          };
-          const result = await executeRequest(endpoint, fetchConfig, requestParams);
-          if (isMountedRef.current) {
-            handleResponse(
-              result,
-              onSuccess,
-              onError
-            );
-            if (!result.status) {
-              const err = new Error(result.message ?? "Request failed");
-              setError(err);
-              return;
-            }
-            const newData = dataExtractor(result);
-            const totalCount = totalExtractor(result);
-            if (append) {
-              setData((prevData) => [...prevData, ...newData]);
-            } else {
-              setData(newData);
-            }
-            setCurrentPage(page);
-            setTotal(totalCount);
-            setTotalPages(Math.ceil(totalCount / limit));
+          const result = await cache.fetch(pageKey(page), pageQueryFn(page), {
+            staleTime,
+            gcTime
+          });
+          handleResponse(
+            result,
+            onSuccess,
+            onError
+          );
+          if (!result.status) {
+            setError(new Error(result.message ?? "Request failed"));
+            return;
           }
+          previousPageKeyRef.current = pageKey(page);
+          setCurrentPage(page);
         } catch (err) {
-          const error2 = err;
-          if (isMountedRef.current) {
-            setError(error2);
-            if (onError) {
-              onError(error2);
-            }
-          }
+          const e = err;
+          setError(e);
+          onError?.(e);
         } finally {
-          if (isMountedRef.current) {
-            if (append) {
-              setIsFetchingNextPage(false);
-            } else {
-              setIsLoading(false);
-            }
-          }
+          if (isNextPage) setIsFetchingNextPage(false);
         }
       },
-      [
-        enabled,
-        serializedParams,
-        limit,
-        onSuccess,
-        onError,
-        dataExtractor,
-        totalExtractor
-      ]
+      [cache, pageKey, pageQueryFn, staleTime, gcTime, onSuccess, onError]
     );
+    react.useEffect(() => {
+      if (!enabled) return;
+      void runFetchPage(initialPage, false);
+      setCurrentPage(initialPage);
+    }, [enabled, serializedParams, initialPage]);
+    const currentState = cache.getState(pageKey(currentPage));
+    const isStale = currentState?.isStale ?? false;
+    const hasFetchedData = currentState?.data !== void 0;
+    react.useEffect(() => {
+      if (!enabled) return;
+      if (isStale && hasFetchedData) void runFetchPage(currentPage, false);
+    }, [enabled, isStale, hasFetchedData, currentPage, runFetchPage]);
+    const currentResult = currentState?.data;
+    const usingPlaceholder = keepPreviousData && !currentResult && previousPageKeyRef.current !== null;
+    const effectiveResult = usingPlaceholder ? cache.getData(previousPageKeyRef.current) : currentResult;
+    const data = effectiveResult && effectiveResult.status ? dataExtractor(effectiveResult) : [];
+    const totalCount = effectiveResult && effectiveResult.status ? totalExtractor(effectiveResult) : null;
+    const total = totalCount;
+    const totalPages = totalCount !== null ? Math.ceil(totalCount / limit) : null;
     const hasNextPage = totalPages !== null && currentPage < totalPages;
     const hasPreviousPage = currentPage > 1;
+    const status = currentState?.status ?? "idle";
+    const isLoading = status === "loading" && !hasFetchedData && !usingPlaceholder;
     const fetchNextPage = react.useCallback(async () => {
       if (!hasNextPage) return;
-      await fetchPage(currentPage + 1, true);
-    }, [hasNextPage, currentPage, fetchPage]);
+      await runFetchPage(currentPage + 1, true);
+    }, [hasNextPage, currentPage, runFetchPage]);
     const fetchPreviousPage = react.useCallback(async () => {
       if (!hasPreviousPage) return;
-      await fetchPage(currentPage - 1, false);
-    }, [hasPreviousPage, currentPage, fetchPage]);
+      await runFetchPage(currentPage - 1, false);
+    }, [hasPreviousPage, currentPage, runFetchPage]);
+    const prefetchNextPage = react.useCallback(async () => {
+      if (!hasNextPage) return;
+      await cache.fetch(
+        pageKey(currentPage + 1),
+        pageQueryFn(currentPage + 1),
+        { staleTime, gcTime }
+      );
+    }, [hasNextPage, currentPage, cache, pageKey, pageQueryFn, staleTime, gcTime]);
     const refetch = react.useCallback(async () => {
-      await fetchPage(currentPage, false);
-    }, [currentPage, fetchPage]);
+      await cache.fetch(pageKey(currentPage), pageQueryFn(currentPage), {
+        staleTime: 0,
+        gcTime,
+        force: true
+      });
+    }, [cache, pageKey, pageQueryFn, currentPage, gcTime]);
     const reset = react.useCallback(() => {
-      setData([]);
+      cache.remove((k) => {
+        if (k.length < keyPrefix.length) return false;
+        for (let i = 0; i < keyPrefix.length; i++) {
+          if (hashQueryKey([k[i]]) !== hashQueryKey([keyPrefix[i]])) return false;
+        }
+        return true;
+      });
+      previousPageKeyRef.current = null;
       setCurrentPage(initialPage);
-      setTotalPages(null);
-      setTotal(null);
-      setError(null);
-      void fetchPage(initialPage, false);
-    }, [initialPage, fetchPage]);
-    react.useEffect(() => {
-      isMountedRef.current = true;
-      if (enabled) {
-        void fetchPage(initialPage, false);
-      }
-      return () => {
-        isMountedRef.current = false;
-      };
-    }, [enabled, serializedParams, fetchPage, initialPage]);
+      void runFetchPage(initialPage, false);
+    }, [cache, keyPrefix, initialPage, runFetchPage]);
     return {
       data,
       currentPage,
@@ -368,17 +988,150 @@ function createUsePaginate(endpoint, fetchConfig, options) {
       total,
       hasNextPage,
       hasPreviousPage,
-      isLoading,
+      isLoading: enabled ? isLoading : false,
       isFetchingNextPage,
+      isPlaceholderData: usingPlaceholder,
       error,
       fetchNextPage,
       fetchPreviousPage,
+      prefetchNextPage,
       refetch,
       reset
     };
   };
 }
 
+// src/query/persist.ts
+function persistQueryClient(options) {
+  const {
+    client,
+    storage,
+    storageKey = "react-api-client:cache",
+    throttleMs = 1e3,
+    allowList,
+    maxAge,
+    version
+  } = options;
+  let pendingTimer = null;
+  let lastSerialized = null;
+  let unsubscribed = false;
+  const persist = async () => {
+    const state = client.cache.dehydrate(allowList);
+    if (state.queries.length === 0) return;
+    const snap = { version, savedAt: Date.now(), state };
+    const serialized = JSON.stringify(snap);
+    if (serialized === lastSerialized) return;
+    lastSerialized = serialized;
+    await storage.setItem(storageKey, serialized);
+  };
+  const scheduleWrite = () => {
+    if (unsubscribed) return;
+    if (pendingTimer) return;
+    pendingTimer = setTimeout(() => {
+      pendingTimer = null;
+      void persist();
+    }, throttleMs);
+  };
+  const restore = async () => {
+    const raw = await storage.getItem(storageKey);
+    if (!raw) return;
+    try {
+      const snap = JSON.parse(raw);
+      if (version !== void 0 && snap.version !== version) {
+        await storage.removeItem(storageKey);
+        return;
+      }
+      if (maxAge && Date.now() - snap.savedAt > maxAge) {
+        await storage.removeItem(storageKey);
+        return;
+      }
+      client.cache.hydrate(snap.state);
+    } catch {
+      await storage.removeItem(storageKey);
+    }
+  };
+  const unsubscribeFromCache = client.cache.subscribeAll(scheduleWrite);
+  return {
+    restore,
+    persist,
+    unsubscribe: () => {
+      unsubscribed = true;
+      unsubscribeFromCache();
+      if (pendingTimer) {
+        clearTimeout(pendingTimer);
+        pendingTimer = null;
+      }
+    }
+  };
+}
+
+// src/query/devtools.ts
+function inspectCache(cache) {
+  const entries = cache._debugEntries();
+  const snapshot = [];
+  for (const [hash, entry] of entries) {
+    snapshot.push({
+      key: entry.key,
+      hash,
+      status: entry.state.status,
+      isStale: entry.state.isStale,
+      updatedAt: entry.state.updatedAt,
+      hasData: entry.state.data !== void 0,
+      subscribers: entry.subscribers.size,
+      hasInflight: entry.inflight !== null,
+      errorMessage: entry.state.error?.message ?? null
+    });
+  }
+  return snapshot;
+}
+function invalidateAll(client) {
+  client.invalidateQueries(() => true);
+}
+function summarizeCache(cache) {
+  const byStatus = {
+    idle: 0,
+    loading: 0,
+    success: 0,
+    error: 0
+  };
+  let withSubscribers = 0;
+  let inflight = 0;
+  let stale = 0;
+  const entries = cache._debugEntries();
+  for (const entry of entries.values()) {
+    byStatus[entry.state.status]++;
+    if (entry.subscribers.size > 0) withSubscribers++;
+    if (entry.inflight) inflight++;
+    if (entry.state.isStale) stale++;
+  }
+  return { total: entries.size, withSubscribers, inflight, stale, byStatus };
+}
+var QueryClientContext = react.createContext(null);
+function ApiClientProvider({
+  client,
+  children
+}) {
+  const value = react.useMemo(() => {
+    const instance = client ?? new QueryClient();
+    setQueryClient(instance);
+    return instance;
+  }, [client]);
+  return react.createElement(
+    QueryClientContext.Provider,
+    { value },
+    children
+  );
+}
+function useQueryClient() {
+  const ctx = react.useContext(QueryClientContext);
+  if (!ctx) {
+    throw new Error(
+      "useQueryClient: \u043D\u0435 \u043D\u0430\u0439\u0434\u0435\u043D ApiClientProvider. \u041E\u0431\u0435\u0440\u043D\u0438 \u043A\u043E\u0440\u0435\u043D\u044C \u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u044F \u0432 <ApiClientProvider>."
+    );
+  }
+  return ctx;
+}
+
 // src/index.ts
 function apiClient(endpoint, fetchConfig = {}) {
   const fetch = async (params) => {
@@ -408,11 +1161,28 @@ function apiPaginate(endpoint, fetchConfig = {}, options) {
 }
 var index_default = apiClient;
 
+exports.ApiClientProvider = ApiClientProvider;
+exports.ApiError = ApiError;
+exports.QueryCache = QueryCache;
+exports.QueryClient = QueryClient;
 exports.apiMutation = apiMutation;
 exports.apiPaginate = apiPaginate;
+exports.businessErrorToApiError = businessErrorToApiError;
 exports.configureApiClient = configureApiClient;
 exports.default = index_default;
+exports.focusManager = focusManager;
 exports.getConfig = getConfig;
+exports.getQueryClient = getQueryClient;
+exports.hashQueryKey = hashQueryKey;
+exports.inspectCache = inspectCache;
+exports.invalidateAll = invalidateAll;
 exports.isConfigured = isConfigured;
+exports.matchQueryKey = matchQueryKey;
+exports.onlineManager = onlineManager;
+exports.persistQueryClient = persistQueryClient;
+exports.setQueryClient = setQueryClient;
+exports.summarizeCache = summarizeCache;
+exports.toApiError = toApiError;
+exports.useQueryClient = useQueryClient;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map