@krymskyimaksym/react-api-client 2.0.0-beta.3 → 2.1.0

package/dist/index.d.ts

@@ -1,6 +1,92 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 
+/**
+ * Унифицированная ошибка 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>);
+}
+/**
+ * Конвертация произвольного throw'нутого значения в `ApiError`.
+ * Покрывает 4 кейса:
+ * - `ApiError` → passthrough
+ * - axios-like `{ response: { status, data } }` → ApiError с полями из data
+ * - `Error` (сетевая ошибка, таймаут) → ApiError(isNetworkError, status: 0)
+ * - неизвестный объект → ApiError(message: 'Unknown error', status: 0)
+ */
+declare function toApiError(thrown: unknown): ApiError;
+/**
+ * Для 2xx ответа, в теле которого Laravel-style `{ status: false }`.
+ * Возвращает ApiError(status: 200, ...). Вызывается из executeRequest
+ * только при `throwOnError: true`.
+ */
+declare function businessErrorToApiError(response: unknown): ApiError;
+
+/**
+ * Описывает «как мы общаемся с бекендом»: как распаковывать успешный
+ * ответ, как детектить бизнес-ошибку в 2xx-ответе и как конвертировать
+ * сырое тело в `ApiError`.
+ *
+ * Передаётся один раз в `configureApiClient({ responseAdapter })`.
+ * Все три поля опциональны: дефолты дают Laravel-поведение (обратная
+ * совместимость с 1.x / 2.0).
+ */
+type ResponseAdapter<TRaw = unknown, TUnwrapped = unknown> = {
+    /**
+     * Распаковать 2xx-ответ в данные для caller'а. Вызывается ровно один
+     * раз сразу после получения тела, ДО записи в кэш и ДО `select`.
+     * По умолчанию — identity.
+     */
+    unwrap?: (raw: TRaw) => TUnwrapped;
+    /**
+     * Является ли 2xx-ответ бизнес-ошибкой (Laravel `{status: false}`,
+     * GraphQL `{ errors: [...] }`, и т.п.). Если true — пакет вызовет
+     * `toError` и кинет `ApiError` вместо resolve.
+     * По умолчанию — `(r) => r?.status === false` (Laravel).
+     */
+    isBusinessError?: (raw: TRaw) => boolean;
+    /**
+     * Сконвертировать сырое тело в `ApiError`. Вызывается для:
+     * - HTTP ≥ 400
+     * - 2xx + `isBusinessError === true`
+     * - сетевая ошибка / таймаут (`httpStatus = 0`)
+     *
+     * По умолчанию — текущий маппинг (`message`/`code`/`errors`).
+     */
+    toError?: (raw: unknown, httpStatus: number) => ApiError;
+};
+/** Laravel-стиль: `{ status: false, message, errors }`. Default. */
+declare const laravelAdapter: ResponseAdapter;
+/** JSON:API. `unwrap` отдаёт `r.data`, ошибки — массив в `r.errors`. */
+declare const jsonApiAdapter: ResponseAdapter;
+/** GraphQL. `unwrap` отдаёт `r.data`, ошибки в `r.errors`. */
+declare const graphqlAdapter: ResponseAdapter;
+/** RFC 7807 problem+json. Бизнес-ошибок в 2xx не бывает — только HTTP. */
+declare const problemJsonAdapter: ResponseAdapter;
+/** Plain REST: никаких бизнес-ошибок в 2xx, identity unwrap. */
+declare const plainAdapter: ResponseAdapter;
+
 type QueryKey = readonly unknown[];
 /**
  * Стабильная сериализация ключа кэша.
@@ -80,7 +166,7 @@ declare class QueryCache {
     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;
+    setData<T>(key: QueryKey, updater: T | ((prev: T | undefined) => T)): T;
     /**
      * Подписка на изменения ключа. Возвращает unsubscribe.
      * Подписка останавливает GC таймер; отписка — запускает его обратно.
@@ -106,10 +192,16 @@ declare class QueryCache {
      */
     refetchQueries(predicate: QueryKey | ((key: QueryKey) => boolean)): Promise<void>;
     /**
-     * Отменяет «привязку» inflight-промиса к ключу. Сам HTTP-запрос
-     * продолжит исполняться (executeRequest не использует AbortSignal),
-     * но его результат больше не попадёт в кэш и не уведомит подписчиков.
-     * Полезно при размонтировании / при переключении страниц.
+     * Отменяет inflight-запрос: пробрасывает abort через `AbortSignal`
+     * в `queryFn` (т.е. в `executeRequest` → `httpClient`) и отвязывает
+     * результат от ключа.
+     *
+     * Если `httpClient` уважает `signal` (`fetch` нативный, axios v1+
+     * с `signal`, и т.п.) — HTTP-запрос реально прерывается. Если
+     * игнорирует — поведение деградирует: запрос продолжит исполняться,
+     * но его ответ уже не попадёт в кэш и подписчиков не уведомит.
+     *
+     * Полезно при размонтировании / переключении страниц / logout'е.
      */
     cancelQueries(predicate: QueryKey | ((key: QueryKey) => boolean)): void;
     /**
@@ -155,15 +247,42 @@ 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;
+    /**
+     * Точечно патчит данные под ключом. Возвращает новое значение —
+     * удобно для «пропатчил → передал дальше».
+     */
+    setQueryData<T>(key: QueryKey, updater: T | ((prev: T | undefined) => T)): T;
     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;
+    /**
+     * Отменяет inflight-мутации через `AbortSignal`. Без аргумента — все.
+     * С префиксом QueryKey или функцией-предикатом — только матчинг
+     * (scope мутации = первый ключ из её `invalidateKeys`, если задан массив).
+     *
+     * Если `httpClient` уважает `signal` — HTTP-запрос реально прерывается;
+     * иначе результат отменённой мутации просто не повлияет на UI
+     * (`useMutation` останется в текущем состоянии).
+     *
+     * Типичный кейс — logout: `client.cancelMutations()` перед очисткой
+     * сессии, чтобы поздние ответы не сработали.
+     */
+    cancelMutations(predicate?: QueryKey | ((scope: QueryKey | undefined) => boolean)): void;
     refetchQueries(predicate: QueryKey | ((key: QueryKey) => boolean)): Promise<void>;
     /**
-     * Кладёт запрос в кэш, не пробрасывая ошибки. Подходит для оптимистичной
-     * подгрузки следующего экрана при наведении / долгом тапе.
+     * Кладёт запрос в кэш, не пробрасывая ошибки. Подходит для
+     * оптимистичной подгрузки следующего экрана при наведении / долгом тапе.
+     *
+     * Поведение:
+     * - **`staleTime`**: учитывается. Если данные ещё свежие — запрос не
+     *   отправляется, promise резолвится сразу.
+     * - **`inflight`**: если по ключу уже идёт запрос, prefetch присоединяется
+     *   к нему (dedupe). Не создаёт второй HTTP-вызов.
+     * - **Подписчики**: если на ключ подписан `useFetch`, успешный prefetch
+     *   обновит его `data` (через notify подписчиков). При ошибке — статус
+     *   подписчика тоже обновится (`error`).
+     * - **Возвращаемый promise**: всегда успешный — ошибки не пробрасываются.
      */
     prefetchQuery<T>(key: QueryKey, queryFn: QueryFn<T>, options?: FetchOptions): Promise<void>;
 }
@@ -180,6 +299,32 @@ type ResponseWrapper<DataType, ErrorsType = unknown> = {
     message?: string;
     errors?: ErrorsType;
 } & DataType;
+/**
+ * Module augmentation для отвязки публичных типов от Laravel-обёртки.
+ *
+ * Пользователь дополняет этот интерфейс в своём проекте:
+ *
+ * ```ts
+ * declare module '@krymskyimaksym/react-api-client' {
+ *   interface Register {
+ *     responseShape: 'plain'; // 'laravel' | 'jsonapi' | 'graphql' | 'plain'
+ *   }
+ * }
+ * ```
+ *
+ * По умолчанию (Register пустой) — `DataOf<T> = ResponseWrapper<T>`,
+ * совместимо с 1.x / 2.0.
+ */
+interface Register {
+}
+/**
+ * Условный тип «форма данных», возвращаемая `fetch` / `useFetch` /
+ * `useMutation`. Зависит от `Register['responseShape']`. По умолчанию
+ * — `ResponseWrapper<T>` (back-compat).
+ */
+type DataOf<T, E = unknown> = Register extends {
+    responseShape: infer S;
+} ? S extends 'plain' ? T : S extends 'laravel' ? ResponseWrapper<T, E> : S extends 'jsonapi' ? T : S extends 'graphql' ? T : ResponseWrapper<T, E> : ResponseWrapper<T, E>;
 type UseFetchOptions<T, TSelected = T> = {
     /**
      * При `false`:
@@ -212,8 +357,19 @@ type UseFetchOptions<T, TSelected = T> = {
      * `['__endpoint__', endpointString, params]`.
      */
     queryKey?: readonly unknown[];
-    /** Селектор результата — пересчитывается мемоизированно. */
+    /**
+     * Селектор результата — пересчитывается мемоизированно.
+     * Изменение исходных `data` запускает `select` заново; чтобы избежать
+     * лишних ререндеров при равных, но новых по ссылке объектах — задай
+     * `selectIsEqual`.
+     */
     select?: (data: T) => TSelected;
+    /**
+     * Сравнение результатов `select` для предотвращения ререндеров.
+     * По умолчанию — `Object.is` (референсное равенство).
+     * Передавай `shallowEqual`/`deepEqual` для structural-сравнения.
+     */
+    selectIsEqual?: (a: TSelected, b: TSelected) => boolean;
     onSuccess?: (data: T) => void;
     onError?: (error: Error) => void;
 };
@@ -224,7 +380,7 @@ type UseFetchResult<T> = {
     error: Error | null;
     refetch: () => Promise<void>;
 };
-type UsePaginateOptions<T> = {
+type UsePaginateOptions<T, TData = unknown[], TSelected = TData> = {
     enabled?: boolean;
     initialPage?: number;
     initialLimit?: number;
@@ -238,10 +394,17 @@ type UsePaginateOptions<T> = {
     keepPreviousData?: boolean;
     /** Кастомный префикс ключа кэша. По умолчанию — endpoint + serialized params. */
     queryKey?: readonly unknown[];
+    /**
+     * Селектор поверх массива страницы. По умолчанию — identity.
+     * Применяется к уже извлечённому массиву `TData`.
+     */
+    select?: (data: TData) => TSelected;
+    /** Сравнение результатов `select` для предотвращения ререндеров. По умолчанию `Object.is`. */
+    selectIsEqual?: (a: TSelected, b: TSelected) => boolean;
     onSuccess?: (data: T) => void;
     onError?: (error: Error) => void;
 };
-type UsePaginateResult<TData extends unknown[]> = {
+type UsePaginateResult<TData> = {
     data: TData;
     currentPage: number;
     totalPages: number | null;
@@ -338,17 +501,32 @@ type ApiClientConfig = {
     throwOnError?: boolean;
     /** Опциональный логгер для отладки. */
     logger?: ApiClientLogger;
+    /**
+     * Описывает форму ответа бекенда: как unwrap'ить успех, как
+     * детектить бизнес-ошибку в 2xx, как конвертировать в ApiError.
+     * Если не задан — встроенный laravel-fallback (`{ status: false }`
+     * как признак бизнес-ошибки). См. `adapters.ts`.
+     */
+    responseAdapter?: ResponseAdapter;
+    /**
+     * Дефолтный `staleTime` для всех хуков `useFetch` / `usePaginate`.
+     * Если хук задал свой `staleTime` — он перекрывает этот дефолт.
+     * Значение по умолчанию `0` (старое поведение — данные сразу stale,
+     * каждый mount = новый запрос). Поднимай до `5_000`–`30_000`, чтобы
+     * избежать лишних refetch'ей при mount в среднем SPA-сценарии.
+     */
+    defaultStaleTime?: number;
 };
 type ApiClientReturn<ResponseType, RequestParamsType, ErrorResponseType = unknown> = {
-    fetch: (params?: RequestParamsType) => Promise<ResponseWrapper<ResponseType, ErrorResponseType>>;
-    useFetch: <TSelected = ResponseWrapper<ResponseType, ErrorResponseType>>(params?: RequestParamsType, options?: UseFetchOptions<ResponseWrapper<ResponseType, ErrorResponseType>, TSelected>) => UseFetchResult<TSelected>;
+    fetch: (params?: RequestParamsType) => Promise<DataOf<ResponseType, ErrorResponseType>>;
+    useFetch: <TSelected = DataOf<ResponseType, ErrorResponseType>>(params?: RequestParamsType, options?: UseFetchOptions<DataOf<ResponseType, ErrorResponseType>, TSelected>) => UseFetchResult<TSelected>;
 };
 type ApiMutationReturn<ResponseType, RequestParamsType, ErrorResponseType = unknown> = {
-    mutate: (params?: RequestParamsType) => Promise<ResponseWrapper<ResponseType, ErrorResponseType>>;
-    useMutation: <TContext = unknown>(options?: UseMutationOptions<ResponseWrapper<ResponseType, ErrorResponseType>, RequestParamsType, TContext>) => UseMutationResult<ResponseWrapper<ResponseType, ErrorResponseType>, RequestParamsType>;
+    mutate: (params?: RequestParamsType) => Promise<DataOf<ResponseType, ErrorResponseType>>;
+    useMutation: <TContext = unknown>(options?: UseMutationOptions<DataOf<ResponseType, ErrorResponseType>, RequestParamsType, TContext>) => UseMutationResult<DataOf<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>;
+    usePaginate: <TSelected = DataArrayType>(params?: Omit<RequestParamsType, 'page' | 'limit'>, options?: UsePaginateOptions<DataOf<ResponseType, ErrorResponseType>, DataArrayType, TSelected>) => UsePaginateResult<TSelected>;
 };
 
 /**
@@ -375,48 +553,6 @@ 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>);
-}
-/**
- * Конвертация произвольного throw'нутого значения в `ApiError`.
- * Покрывает 4 кейса:
- * - `ApiError` → passthrough
- * - axios-like `{ response: { status, data } }` → ApiError с полями из data
- * - `Error` (сетевая ошибка, таймаут) → ApiError(isNetworkError, status: 0)
- * - неизвестный объект → ApiError(message: 'Unknown error', status: 0)
- */
-declare function toApiError(thrown: unknown): ApiError;
-/**
- * Для 2xx ответа, в теле которого Laravel-style `{ status: false }`.
- * Возвращает ApiError(status: 200, ...). Вызывается из executeRequest
- * только при `throwOnError: true`.
- */
-declare function businessErrorToApiError(response: unknown): ApiError;
-
 /**
  * Возвращает число активных (inflight) запросов в кэше.
  * Полезно для глобального индикатора загрузки в шапке.
@@ -432,6 +568,63 @@ declare function useIsFetching(predicate?: QueryKey | ((key: QueryKey) => boolea
  */
 declare function useIsMutating(predicate?: QueryKey | ((scope: QueryKey | undefined) => boolean)): number;
 
+/** Опции для низкоуровневого `useQuery`. */
+type UseQueryOptions<T, TSelected = T> = {
+    enabled?: boolean;
+    refetchOnMount?: boolean;
+    refetchOnFocus?: boolean;
+    refetchOnAppActive?: boolean;
+    refetchOnReconnect?: boolean;
+    staleTime?: number;
+    gcTime?: number;
+    pollingInterval?: number;
+    select?: (data: T) => TSelected;
+    selectIsEqual?: (a: TSelected, b: TSelected) => boolean;
+};
+type UseQueryResult<T> = {
+    data: T | null;
+    isLoading: boolean;
+    isRefetching: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+};
+/**
+ * Низкоуровневый аналог `useFetch` поверх произвольного `queryFn`.
+ * Имя совпадает с TanStack Query для discoverability — поведение
+ * аналогично `useFetch`, но без обёртки `apiClient(endpoint, ...)`.
+ *
+ * @example
+ * const { data } = useQuery(
+ *   ['orders', orderId],
+ *   ({ signal }) => fetchOrder(orderId, signal),
+ *   { staleTime: 30_000 },
+ * );
+ */
+declare function useQuery<T, TSelected = T>(queryKey: QueryKey, queryFn: QueryFn<T>, options?: UseQueryOptions<T, TSelected>): UseQueryResult<TSelected>;
+
+/**
+ * Пакетное чтение нескольких ключей из кэша. Хук подписан на каждый
+ * ключ и перерендерится, когда любое из значений изменится.
+ *
+ * Возвращает массив значений того же порядка, что и `keys`. Если ключа
+ * нет в кэше — соответствующий элемент `undefined`.
+ *
+ * Не делает запросов — только читает. Если данных нужно «загрузить» —
+ * используй `useFetch`/`useQuery` отдельно.
+ *
+ * @example
+ * const [orders, chats, tasks] = useQueriesData<
+ *   [Board, ChatsUnread, TasksNew]
+ * >([
+ *   ['orders', 'board'],
+ *   ['chats', 'unread'],
+ *   ['tasks', 'new'],
+ * ]);
+ */
+declare function useQueriesData<T extends readonly unknown[]>(keys: readonly QueryKey[]): {
+    [K in keyof T]: T[K] | undefined;
+};
+
 /**
  * Storage-адаптер. Совместим с AsyncStorage и expo-secure-store:
  *   { getItem(key): Promise<string|null>, setItem(key, value): Promise<void>,
@@ -622,4 +815,4 @@ declare function apiPaginate<ResponseType extends {
     totalExtractor?: (response: ResponseType) => number;
 }): ApiPaginateReturn<ResponseType, RequestParamsType, TData, ErrorResponseType>;
 
-export { type ApiClientConfig, type ApiClientLogger, 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, businessErrorToApiError, configureApiClient, apiClient as default, focusManager, getConfig, getQueryClient, hashQueryKey, inspectCache, invalidateAll, isConfigured, matchQueryKey, onlineManager, persistQueryClient, setQueryClient, summarizeCache, toApiError, useIsFetching, useIsMutating, useQueryClient };
+export { type ApiClientConfig, type ApiClientLogger, ApiClientProvider, type ApiClientProviderProps, ApiError, type ApiErrorInit, type CacheEntrySnapshot, type DataOf, type DehydratedQuery, type DehydratedState, type FetchOptions, type IHttpClient, type PersistOptions, type PersistStorage, QueryCache, QueryClient, type QueryFn, type QueryKey, type QueryState, type QueryStatus, type Register, type ResponseAdapter, type ResponseWrapper, type UseFetchOptions, type UseFetchResult, type UseMutationOptions, type UseMutationResult, type UsePaginateOptions, type UsePaginateResult, type UseQueryOptions, type UseQueryResult, apiMutation, apiPaginate, businessErrorToApiError, configureApiClient, apiClient as default, focusManager, getConfig, getQueryClient, graphqlAdapter, hashQueryKey, inspectCache, invalidateAll, isConfigured, jsonApiAdapter, laravelAdapter, matchQueryKey, onlineManager, persistQueryClient, plainAdapter, problemJsonAdapter, setQueryClient, summarizeCache, toApiError, useIsFetching, useIsMutating, useQueriesData, useQuery, useQueryClient };