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

package/dist/index.d.ts

@@ -1,3 +1,131 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+type QueryKey = readonly unknown[];
+/**
+ * Стабильная сериализация ключа кэша.
+ * - Объекты сериализуются с сортировкой ключей.
+ * - Массивы сохраняют порядок.
+ * - Функции и symbol — недопустимы (как в TanStack Query), кидаем.
+ * - undefined в массиве становится null, в объекте — поле пропускается.
+ *
+ * Пример: ['orders', { sort: 'date', dir: 'asc' }] и
+ * ['orders', { dir: 'asc', sort: 'date' }] дают одинаковый hash.
+ */
+declare function hashQueryKey(key: QueryKey): string;
+/**
+ * Проверяет, начинается ли `key` с `prefix`.
+ * Используется для invalidateQueries по префиксу: ['orders'] матчит
+ * и ['orders', 'manager'], и ['orders', 960].
+ */
+declare function matchQueryKey(prefix: QueryKey, key: QueryKey): boolean;
+
+type QueryStatus = 'idle' | 'loading' | 'success' | 'error';
+type QueryState<T> = {
+    data: T | undefined;
+    error: Error | null;
+    status: QueryStatus;
+    updatedAt: number;
+    isStale: boolean;
+};
+type Listener$2 = () => void;
+type QueryEntry<T> = {
+    key: QueryKey;
+    state: QueryState<T>;
+    subscribers: Set<Listener$2>;
+    inflight: Promise<T> | null;
+    gcTimer: ReturnType<typeof setTimeout> | null;
+    staleTime: number;
+    gcTime: number;
+};
+type QueryFn<T> = () => Promise<T>;
+type FetchOptions = {
+    staleTime?: number;
+    gcTime?: number;
+    /** Если true — игнорируем staleTime и форсим запрос */
+    force?: boolean;
+};
+/**
+ * In-memory кэш запросов с подпиской по ключу, dedupe inflight-промисов
+ * и сборкой мусора через gcTime.
+ */
+declare class QueryCache {
+    private entries;
+    private ensureEntry;
+    getState<T>(key: QueryKey): QueryState<T> | undefined;
+    getData<T>(key: QueryKey): T | undefined;
+    setData<T>(key: QueryKey, updater: T | ((prev: T | undefined) => T)): void;
+    /**
+     * Подписка на изменения ключа. Возвращает unsubscribe.
+     * Подписка останавливает GC таймер; отписка — запускает его обратно.
+     */
+    subscribe(key: QueryKey, listener: Listener$2): () => void;
+    private notify;
+    private scheduleGc;
+    /**
+     * Запускает или присоединяется к inflight-запросу.
+     * Если данные свежие (не stale) и не force — отдаёт кэш без запроса.
+     */
+    fetch<T>(key: QueryKey, queryFn: QueryFn<T>, options?: FetchOptions): Promise<T>;
+    /**
+     * Помечает запись как stale. Сами по себе данные не удаляются.
+     * Если есть подписчики — они получат уведомление, чтобы инициировать refetch.
+     */
+    invalidate(predicate: QueryKey | ((key: QueryKey) => boolean)): string[];
+    /**
+     * Отменяет «привязку» inflight-промиса к ключу. Сам HTTP-запрос
+     * продолжит исполняться (executeRequest не использует AbortSignal),
+     * но его результат больше не попадёт в кэш и не уведомит подписчиков.
+     * Полезно при размонтировании / при переключении страниц.
+     */
+    cancelQueries(predicate: QueryKey | ((key: QueryKey) => boolean)): void;
+    /**
+     * Полностью удаляет записи (даже с активными подписчиками).
+     * Используется редко — обычно достаточно invalidate.
+     */
+    remove(predicate: QueryKey | ((key: QueryKey) => boolean)): void;
+    /** Только для тестов / DevTools. */
+    _debugEntries(): ReadonlyMap<string, QueryEntry<unknown>>;
+    /**
+     * Сериализует записи со статусом success — для persistence.
+     * inflight / loading / error не сохраняются, чтобы не гидратировать
+     * приложение в полу-загруженном состоянии.
+     */
+    dehydrate(filter?: (key: QueryKey) => boolean): DehydratedState;
+    hydrate(state: DehydratedState): void;
+}
+type DehydratedQuery = {
+    key: unknown[];
+    data: unknown;
+    updatedAt: number;
+};
+type DehydratedState = {
+    queries: DehydratedQuery[];
+};
+
+/**
+ * Высокоуровневый фасад над QueryCache: единый объект, который удобно
+ * прокидывать через Provider и дергать из push-handler'ов / эффектов.
+ *
+ * Сами queryFn-ы здесь не регистрируются — refetchQueries требует, чтобы
+ * либо подписчик сам перезапустил запрос (через subscribe), либо чтобы
+ * вызвали fetchQuery с queryFn вручную. Это намеренно: хук React сам
+ * знает, как собрать свой queryFn из endpoint/params.
+ */
+declare class QueryClient {
+    readonly cache: QueryCache;
+    constructor(cache?: QueryCache);
+    getQueryData<T>(key: QueryKey): T | undefined;
+    setQueryData<T>(key: QueryKey, updater: T | ((prev: T | undefined) => T)): void;
+    fetchQuery<T>(key: QueryKey, queryFn: QueryFn<T>, options?: FetchOptions): Promise<T>;
+    invalidateQueries(predicate: QueryKey | ((key: QueryKey) => boolean)): void;
+    removeQueries(predicate: QueryKey | ((key: QueryKey) => boolean)): void;
+    cancelQueries(predicate: QueryKey | ((key: QueryKey) => boolean)): void;
+}
+/** Singleton-доступ для тех мест, где Provider недоступен (push-handler и т.п.). */
+declare function getQueryClient(): QueryClient;
+declare function setQueryClient(client: QueryClient): void;
+
 type RequestConfig = {
     method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     requestParams?: Record<string, string>;
@@ -7,9 +135,28 @@ type ResponseWrapper<DataType, ErrorsType = unknown> = {
     message?: string;
     errors?: ErrorsType;
 } & DataType;
-type UseFetchOptions<T> = {
+type UseFetchOptions<T, TSelected = T> = {
     enabled?: boolean;
     refetchOnMount?: boolean;
+    /** Refetch при возврате на экран / в браузерное окно. */
+    refetchOnFocus?: boolean;
+    /** Refetch при возврате приложения в активное состояние (RN AppState). */
+    refetchOnAppActive?: boolean;
+    /** Refetch при восстановлении сетевого соединения (offline → online). */
+    refetchOnReconnect?: boolean;
+    /** Время свежести данных в ms. Пока не истечёт — повторный mount берёт из кэша без сети. */
+    staleTime?: number;
+    /** Сколько держать запись в кэше после ухода последнего подписчика. По умолчанию 5 мин. */
+    gcTime?: number;
+    /** Интервал поллинга в ms. Поллинг автоматически останавливается, если экран не виден. */
+    pollingInterval?: number;
+    /**
+     * Кастомный queryKey. По умолчанию собирается как
+     * `['__endpoint__', endpointString, params]`.
+     */
+    queryKey?: readonly unknown[];
+    /** Селектор результата — пересчитывается мемоизированно. */
+    select?: (data: T) => TSelected;
     onSuccess?: (data: T) => void;
     onError?: (error: Error) => void;
 };
@@ -24,6 +171,16 @@ type UsePaginateOptions<T> = {
     enabled?: boolean;
     initialPage?: number;
     initialLimit?: number;
+    /** ms — пока страница свежая, повторный mount берёт её из кэша. */
+    staleTime?: number;
+    gcTime?: number;
+    /**
+     * Если true — при смене страницы (или params) предыдущие данные остаются
+     * на экране до прихода новых. Полезно для плавной пагинации.
+     */
+    keepPreviousData?: boolean;
+    /** Кастомный префикс ключа кэша. По умолчанию — endpoint + serialized params. */
+    queryKey?: readonly unknown[];
     onSuccess?: (data: T) => void;
     onError?: (error: Error) => void;
 };
@@ -36,17 +193,39 @@ type UsePaginateResult<TData extends unknown[]> = {
     hasPreviousPage: boolean;
     isLoading: boolean;
     isFetchingNextPage: boolean;
+    /** true если данные показываются из предыдущей страницы (keepPreviousData). */
+    isPlaceholderData: boolean;
     error: Error | null;
     fetchNextPage: () => Promise<void>;
     fetchPreviousPage: () => Promise<void>;
+    /** Префетчит следующую страницу в кэш, не меняя UI. */
+    prefetchNextPage: () => Promise<void>;
     refetch: () => Promise<void>;
     reset: () => void;
 };
-type UseMutationOptions<TData, TVariables> = {
-    onMutate?: (variables: TVariables) => void | Promise<void>;
-    onSuccess?: (data: TData, variables: TVariables) => void | Promise<void>;
-    onError?: (error: Error, variables: TVariables) => void | Promise<void>;
-    onSettled?: (data: TData | null, error: Error | null, variables: TVariables) => void | Promise<void>;
+
+type UseMutationOptions<TData, TVariables, TContext = unknown> = {
+    /**
+     * Вызывается ДО запроса. Может вернуть context — он попадёт в onError
+     * (для rollback) и в onSettled. Используется для optimistic updates:
+     * сохранить снепшот → применить оптимистичный setQueryData → в onError
+     * вернуть снепшот обратно.
+     */
+    onMutate?: (variables: TVariables) => void | TContext | Promise<void | TContext>;
+    onSuccess?: (data: TData, variables: TVariables, context: TContext | undefined) => void | Promise<void>;
+    onError?: (error: Error, variables: TVariables, context: TContext | undefined) => void | Promise<void>;
+    onSettled?: (data: TData | null, error: Error | null, variables: TVariables, context: TContext | undefined) => void | Promise<void>;
+    /**
+     * Ключи кэша, которые надо инвалидировать после успеха.
+     * Может быть массивом ключей или функцией, считающей их по vars/data.
+     * Каждый ключ матчится по префиксу (см. matchQueryKey).
+     */
+    invalidateKeys?: QueryKey[] | ((vars: TVariables, data: TData) => QueryKey[]);
+    /**
+     * Точечно патчит кэш после успеха — до invalidate. Удобно для
+     * «сервер вернул свежий объект, положим его прямо в ['orders', id]».
+     */
+    setQueryData?: (client: QueryClient, variables: TVariables, data: TData) => void;
 };
 type UseMutationResult<TData, TVariables> = {
     data: TData | null;
@@ -70,6 +249,14 @@ interface IHttpClient {
 type ApiClientConfig = {
     httpClient: IHttpClient;
     onUnauthorized?: () => void | Promise<void>;
+    /**
+     * Когда true — любая ошибка (HTTP >= 400, сеть, тело с `{ status: false }`)
+     * приводит к `throw new ApiError(...)`. По умолчанию false — пакет
+     * сохраняет старое поведение (ошибки приходят как `{ status: false }`).
+     * Включать только после того, как все вызовы `await *.mutate()` /
+     * `await *.fetch()` обёрнуты в try/catch.
+     */
+    throwOnError?: boolean;
 };
 type ApiClientReturn<ResponseType, RequestParamsType, ErrorResponseType = unknown> = {
     fetch: (params?: RequestParamsType) => Promise<ResponseWrapper<ResponseType, ErrorResponseType>>;
@@ -77,7 +264,7 @@ type ApiClientReturn<ResponseType, RequestParamsType, ErrorResponseType = unknow
 };
 type ApiMutationReturn<ResponseType, RequestParamsType, ErrorResponseType = unknown> = {
     mutate: (params?: RequestParamsType) => Promise<ResponseWrapper<ResponseType, ErrorResponseType>>;
-    useMutation: (options?: UseMutationOptions<ResponseWrapper<ResponseType, ErrorResponseType>, RequestParamsType>) => UseMutationResult<ResponseWrapper<ResponseType, ErrorResponseType>, RequestParamsType>;
+    useMutation: <TContext = unknown>(options?: UseMutationOptions<ResponseWrapper<ResponseType, ErrorResponseType>, RequestParamsType, TContext>) => UseMutationResult<ResponseWrapper<ResponseType, ErrorResponseType>, RequestParamsType>;
 };
 type ApiPaginateReturn<ResponseType, RequestParamsType, DataArrayType extends unknown[], ErrorResponseType = unknown> = {
     usePaginate: (params?: Omit<RequestParamsType, 'page' | 'limit'>, options?: UsePaginateOptions<ResponseWrapper<ResponseType, ErrorResponseType>>) => UsePaginateResult<DataArrayType>;
@@ -107,6 +294,164 @@ declare function getConfig(): ApiClientConfig;
  */
 declare function isConfigured(): boolean;
 
+/**
+ * Унифицированная ошибка API. Кидается из `executeRequest` (а значит,
+ * из `fetch`/`mutate`/хуков) только когда в `configureApiClient` включён
+ * `throwOnError: true`. По умолчанию поведение пакета не меняется —
+ * ошибки приходят как `{ status: false }` (см. CHANGELOG, Фаза 3.5).
+ */
+type ApiErrorInit<E = unknown> = {
+    message: string;
+    status: number;
+    code?: string;
+    errors?: E;
+    isNetworkError?: boolean;
+    isUnauthorized?: boolean;
+    isValidationError?: boolean;
+    raw?: unknown;
+};
+declare class ApiError<E = unknown> extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly errors?: E;
+    readonly isNetworkError: boolean;
+    readonly isUnauthorized: boolean;
+    readonly isValidationError: boolean;
+    readonly raw: unknown;
+    constructor(init: ApiErrorInit<E>);
+}
+
+/**
+ * Storage-адаптер. Совместим с AsyncStorage и expo-secure-store:
+ *   { getItem(key): Promise<string|null>, setItem(key, value): Promise<void>,
+ *     removeItem(key): Promise<void> }.
+ */
+interface PersistStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+type PersistOptions = {
+    client: QueryClient;
+    storage: PersistStorage;
+    /** Ключ в storage. По умолчанию 'react-api-client:cache'. */
+    storageKey?: string;
+    /** Дросселирование записи (ms). По умолчанию 1000. */
+    throttleMs?: number;
+    /** Фильтр ключей: что вообще сохранять. По умолчанию — всё. */
+    allowList?: (key: QueryKey) => boolean;
+    /** Максимальный возраст сохранённого снэпшота (ms). Старее — выбрасываем. */
+    maxAge?: number;
+    /**
+     * Версия снэпшота. При несовпадении — снэпшот игнорируется и удаляется.
+     * Поднимай при изменении формата данных в кэше.
+     */
+    version?: string | number;
+};
+/**
+ * Подключает QueryClient к persistent storage.
+ * Возвращает { restore, persist, unsubscribe }:
+ * - `restore()` — гидратирует кэш из storage (вызывать на старте приложения).
+ * - `persist()` — форс-запись текущего состояния.
+ * - `unsubscribe()` — отключить авто-сохранение.
+ *
+ * Простая модель: на каждое изменение через client.cache._debugEntries
+ * нет подписки, поэтому persist вызываем вручную из мутаций / по таймеру.
+ * Здесь — таймер по throttleMs. Этого хватает для чатов/архива.
+ */
+declare function persistQueryClient(options: PersistOptions): {
+    restore: () => Promise<void>;
+    persist: () => Promise<void>;
+    unsubscribe: () => void;
+};
+
+type CacheEntrySnapshot = {
+    key: QueryKey;
+    hash: string;
+    status: QueryStatus;
+    isStale: boolean;
+    updatedAt: number;
+    hasData: boolean;
+    subscribers: number;
+    hasInflight: boolean;
+    errorMessage: string | null;
+};
+/**
+ * Снимок состояния всего кэша — без приватных полей и без данных.
+ * Удобно выводить в debug-экране или логировать.
+ */
+declare function inspectCache(cache: QueryCache): CacheEntrySnapshot[];
+/** «invalidate all» — пометить весь кэш как stale. */
+declare function invalidateAll(client: QueryClient): void;
+/** Краткая сводка для логов: сколько записей, активных подписчиков, inflight. */
+declare function summarizeCache(cache: QueryCache): {
+    total: number;
+    withSubscribers: number;
+    inflight: number;
+    stale: number;
+    byStatus: Record<QueryStatus, number>;
+};
+
+/**
+ * Глобальный менеджер «фокуса» приложения.
+ * - В вебе автоматически подключается к window focus/visibilitychange.
+ * - В React Native интеграцию ставит сам потребитель через
+ *   `focusManager.setFocused(state === 'active')` из AppState.
+ *
+ * Подписчики (useFetch с refetchOnFocus / refetchOnAppActive) получают
+ * уведомление при переходе в focused == true.
+ */
+type Listener$1 = (focused: boolean) => void;
+declare class FocusManager {
+    private focused;
+    private listeners;
+    private cleanup;
+    subscribe(listener: Listener$1): () => void;
+    isFocused(): boolean;
+    setFocused(focused: boolean): void;
+    private setupBrowserListeners;
+    private teardownBrowserListeners;
+}
+declare const focusManager: FocusManager;
+
+/**
+ * Глобальный менеджер сетевого статуса.
+ * - В браузере подключается к window online/offline.
+ * - В React Native интеграция — через NetInfo (опционально):
+ *   `NetInfo.addEventListener(s => onlineManager.setOnline(!!s.isConnected))`.
+ *   Жёсткой зависимости от NetInfo нет — без него по умолчанию online: true.
+ *
+ * Подписчики (useFetch с refetchOnReconnect) получают уведомление при
+ * переходе offline → online.
+ */
+type Listener = (online: boolean) => void;
+declare class OnlineManager {
+    private online;
+    private listeners;
+    private cleanup;
+    subscribe(listener: Listener): () => void;
+    isOnline(): boolean;
+    setOnline(online: boolean): void;
+    private setupBrowserListeners;
+    private teardownBrowserListeners;
+}
+declare const onlineManager: OnlineManager;
+
+type ApiClientProviderProps = {
+    client?: QueryClient;
+    children: ReactNode;
+};
+/**
+ * Корневой Provider пакета. Создаёт (или принимает) QueryClient и кладёт
+ * его в React Context. Хуки достают клиент через useQueryClient().
+ *
+ * Также синхронизирует переданный client с singleton'ом
+ * getQueryClient() — чтобы push-handler'ы вне React-дерева могли дергать
+ * `getQueryClient().invalidateQueries(...)`.
+ */
+declare function ApiClientProvider({ client, children, }: ApiClientProviderProps): react.FunctionComponentElement<react.ProviderProps<QueryClient | null>>;
+declare function useQueryClient(): QueryClient;
+
 /**
  * Creates an API client for GET requests
  * @param endpoint - URL string or function that generates URL from params
@@ -149,4 +494,4 @@ declare function apiPaginate<ResponseType extends {
     totalExtractor?: (response: ResponseType) => number;
 }): ApiPaginateReturn<ResponseType, RequestParamsType, TData, ErrorResponseType>;
 
-export { type ApiClientConfig, type IHttpClient, type ResponseWrapper, type UseFetchOptions, type UseFetchResult, type UseMutationOptions, type UseMutationResult, type UsePaginateOptions, type UsePaginateResult, apiMutation, apiPaginate, configureApiClient, apiClient as default, getConfig, isConfigured };
+export { type ApiClientConfig, ApiClientProvider, type ApiClientProviderProps, ApiError, type ApiErrorInit, type CacheEntrySnapshot, type DehydratedQuery, type DehydratedState, type FetchOptions, type IHttpClient, type PersistOptions, type PersistStorage, QueryCache, QueryClient, type QueryFn, type QueryKey, type QueryState, type QueryStatus, type ResponseWrapper, type UseFetchOptions, type UseFetchResult, type UseMutationOptions, type UseMutationResult, type UsePaginateOptions, type UsePaginateResult, apiMutation, apiPaginate, configureApiClient, apiClient as default, focusManager, getConfig, getQueryClient, hashQueryKey, inspectCache, invalidateAll, isConfigured, matchQueryKey, onlineManager, persistQueryClient, setQueryClient, summarizeCache, useQueryClient };