@dxtmisha/functional 1.11.11 → 1.11.12

package/dist/src/composables/ref/useApiAsyncRef.d.ts

@@ -1,18 +1,70 @@
-import { ApiInstance, ApiData, ApiDataValidation } from '@dxtmisha/functional-basic';
+import { ApiInstance, ApiData, ApiDataValidation, ApiErrorStorageList } from '@dxtmisha/functional-basic';
 import { UseApiRef } from './useApiRef';
 import { RefOrNormal, RefType } from '../../types/refTypes';
 import { ApiOptions } from '../../types/apiTypes';
 /**
- * Executes a request and immediately initializes it asynchronously.
+ * Asynchronous reactive composable for API requests with built-in SSR support.
+ * Wraps `useApiRef` and immediately calls `initSsr()` to ensure data is pre-fetched on the server side.
+ * Use this composable ONLY if you need the request to be executed on the server side during SSR.
+ * For all other cases, use `useApiRef`.
  *
- * Выполняет запрос и сразу инициализирует его асинхронно.
- * @param path path to request / путь к запросу
- * @param options data for the request / данные для запроса
- * @param reactivity should reactivity be enabled / включить ли reactivity
- * @param conditions conditions for executing the request / условия выполнения запроса
- * @param transformation transforms the received request / преобразовывает полученный запрос
- * @param validateResponseContract function to validate response data contract / функция для проверки контракта данных ответа
- * @param unmounted delete data from the cache / удалить ли данные из кеша
- * @param apiInstance Api instance / Экземпляр Api
+ * Асинхронный реактивный composable для API запросов со встроенной поддержкой SSR.
+ * Оборачивает `useApiRef` и сразу вызывает `initSsr()`, чтобы гарантировать предзагрузку данных на сервере.
+ * Используйте этот composable ТОЛЬКО если вам необходимо, чтобы запрос был выполнен на стороне сервера
+ * во время SSR. Во всех остальных случаях используйте обычный `useApiRef`.
+ *
+ * @example
+ * ```typescript
+ * import { Schema as S } from '@effect/schema'
+ * import { useApiAsyncRef } from '@dxtmisha/functional'
+ *
+ * const userSchema = S.Struct({ id: S.Number, name: S.String })
+ *
+ * // Data will be pre-fetched on the server during SSR (onServerPrefetch)
+ * const { data, loading, errorItem, isResponseContractValid } = useApiAsyncRef(
+ *   '/users/1',
+ *   { method: 'GET' },
+ *   true, // reactivity
+ *   undefined, // conditions
+ *   undefined, // transformation
+ *   (data) => { // validateResponseContract
+ *     try {
+ *       return { status: 'success', data: S.decodeUnknownSync(userSchema)(data) }
+ *     } catch (e) {
+ *       return { status: 'error', errors: e }
+ *     }
+ *   },
+ *   [ // errorContract
+ *     { status: 404, message: 'User not found' }
+ *   ]
+ * )
+ * ```
+ *
+ * @param path path to request (can be a Ref or Getter) / путь к запросу (может быть Ref или Getter)
+ * @param options data for the request (headers, method, etc.) / данные для запроса (заголовки, метод и т.д.)
+ * @param reactivity should reactivity be enabled (automatically re-fetch on deps change) /
+ * включить ли реактивность (автоматически повторять запрос при изменении зависимостей)
+ * @param conditions conditions for executing the request (request will wait until true) /
+ * условия выполнения запроса (запрос будет ждать пока не станет true)
+ * @param transformation transforms the received response data / преобразовывает полученные данные ответа
+ * @param validateResponseContract function to validate response data contract. Used to ensure that the API
+ * response matches the expected structure. Highly recommended to use with `@effect/schema`.
+ * It should return `ApiDataValidation` containing a `status` ('success' or 'error')
+ * and the parsed data or errors. /
+ * Функция для проверки контракта данных ответа. Используется для гарантии того, что ответ API соответствует
+ * ожидаемой структуре. Настоятельно рекомендуется использовать с `@effect/schema`. Должна возвращать объект
+ * `ApiDataValidation`, содержащий `status` ('success' или 'error') и распарсенные данные или ошибки.
+ * @param errorContract array of expected error contracts for the request (`ApiErrorStorageList`).
+ * Highly recommended to add if there is information about possible request errors. Allows you to predefine
+ * possible errors (by code, status, or custom validation). If an error occurs matching one of these contracts,
+ * it will be automatically processed and made available via the `errorItem` computed property. /
+ * Массив контрактов ожидаемых ошибок для запроса (`ApiErrorStorageList`). Желательно добавлять, если есть
+ * информация о возможных ошибках запроса. Позволяет заранее описать возможные ошибки (по коду, статусу или
+ * кастомной валидации). Если возникает ошибка, совпадающая с одним из контрактов, она автоматически
+ * обрабатывается и становится доступной через вычисляемое свойство `errorItem` для удобного отображения в UI.
+ * @param unmounted whether to stop the request and clear data from cache when component is unmounted /
+ * нужно ли останавливать запрос и удалять данные из кеша при размонтировании компонента
+ * @param apiInstance Api instance (defaults to global Api instance) /
+ * Экземпляр Api (по умолчанию используется глобальный экземпляр Api)
  */
-export declare function useApiAsyncRef<R, T = R>(path?: RefOrNormal<string | undefined>, options?: ApiOptions, reactivity?: boolean, conditions?: RefType<boolean>, transformation?: (data: T, isResponseContractValid?: ApiDataValidation) => ApiData<R>, validateResponseContract?: (data: T) => ApiDataValidation, unmounted?: boolean, apiInstance?: ApiInstance): UseApiRef<R>;
+export declare function useApiAsyncRef<R, T = R>(path?: RefOrNormal<string | undefined>, options?: ApiOptions, reactivity?: boolean, conditions?: RefType<boolean>, transformation?: (data: T, isResponseContractValid?: ApiDataValidation) => ApiData<R>, validateResponseContract?: (data: T) => ApiDataValidation, errorContract?: ApiErrorStorageList, unmounted?: boolean, apiInstance?: ApiInstance): UseApiRef<R>;

package/dist/src/composables/ref/useApiDelete.d.ts

@@ -1,20 +1,28 @@
-import { ApiInstance, ApiData, ApiFetch } from '@dxtmisha/functional-basic';
+import { ApiInstance, ApiData, ApiFetch, ApiErrorStorageList } from '@dxtmisha/functional-basic';
 import { ApiOptions } from '../../types/apiTypes';
 import { RefOrNormal } from '../../types/refTypes';
 import { Ref } from 'vue';
 /**
  * Use API delete request.
+ * This is a convenient wrapper over `useApiRequest` that pre-fills the DELETE method.
  *
  * Использование API delete запроса.
+ * Это удобная обертка над `useApiRequest`, которая предустанавливает метод DELETE.
  * @param path Path to the API endpoint / Путь к endpoint API
  * @param action Action to perform after the request / Действие, выполняемое после запроса
  * @param transformation Transformation function / Функция трансформации
+ * @param errorContract array of expected error contracts for the request (`ApiErrorStorageList`).
+ * Highly recommended to add if there is information about possible request errors. Allows you to predefine
+ * possible errors (by code, status, or custom validation) which will be centrally processed by the application. /
+ * Массив контрактов ожидаемых ошибок для запроса (`ApiErrorStorageList`). Желательно добавлять, если есть
+ * информация о возможных ошибках запроса. Позволяет заранее описать возможные ошибки (по коду, статусу или
+ * кастомной валидации) для централизованной обработки в приложении.
  * @param toData Extract 'data' field from response / Извлечь поле 'data' из ответа
  * @param options Additional request options / Дополнительные опции запроса
  * @param apiInstance Api instance / Экземпляр Api
  * @returns Object with loading state and send method / Объект с состоянием загрузки и методом отправки
  */
-export declare function useApiDelete<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(path?: RefOrNormal<string | undefined>, action?: (data: Return | undefined) => Promise<void> | void, transformation?: (data: T) => Return, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
+export declare function useApiDelete<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(path?: RefOrNormal<string | undefined>, action?: (data: Return | undefined) => Promise<void> | void, transformation?: (data: T) => Return, errorContract?: ApiErrorStorageList, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
     loading: Ref<boolean, boolean>;
     send(request?: Request | undefined): Promise<Return | undefined>;
 };

package/dist/src/composables/ref/useApiGet.d.ts

@@ -1,20 +1,28 @@
-import { ApiInstance, ApiData, ApiFetch } from '@dxtmisha/functional-basic';
+import { ApiInstance, ApiData, ApiFetch, ApiErrorStorageList } from '@dxtmisha/functional-basic';
 import { ApiOptions } from '../../types/apiTypes';
 import { RefOrNormal } from '../../types/refTypes';
 import { Ref } from 'vue';
 /**
  * Use API get request.
+ * This is a convenient wrapper over `useApiRequest` that pre-fills the GET method.
  *
  * Использование API get запроса.
+ * Это удобная обертка над `useApiRequest`, которая предустанавливает метод GET.
  * @param path Path to the API endpoint / Путь к endpoint API
  * @param action Action to perform after the request / Действие, выполняемое после запроса
  * @param transformation Transformation function / Функция трансформации
+ * @param errorContract array of expected error contracts for the request (`ApiErrorStorageList`).
+ * Highly recommended to add if there is information about possible request errors. Allows you to predefine
+ * possible errors (by code, status, or custom validation) which will be centrally processed by the application. /
+ * Массив контрактов ожидаемых ошибок для запроса (`ApiErrorStorageList`). Желательно добавлять, если есть
+ * информация о возможных ошибках запроса. Позволяет заранее описать возможные ошибки (по коду, статусу или
+ * кастомной валидации) для централизованной обработки в приложении.
  * @param toData Extract 'data' field from response / Извлечь поле 'data' из ответа
  * @param options Additional request options / Дополнительные опции запроса
  * @param apiInstance Api instance / Экземпляр Api
  * @returns Object with loading state and send method / Объект с состоянием загрузки и методом отправки
  */
-export declare function useApiGet<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(path?: RefOrNormal<string | undefined>, action?: (data: Return | undefined) => Promise<void> | void, transformation?: (data: T) => Return, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
+export declare function useApiGet<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(path?: RefOrNormal<string | undefined>, action?: (data: Return | undefined) => Promise<void> | void, transformation?: (data: T) => Return, errorContract?: ApiErrorStorageList, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
     loading: Ref<boolean, boolean>;
     send(request?: Request | undefined): Promise<Return | undefined>;
 };

package/dist/src/composables/ref/useApiManagementAsyncRef.d.ts

@@ -1,10 +1,16 @@
-import { ApiInstance, ArrayToItem, FormattersListColumns, FormattersOptionsList, SearchColumns, ApiDataValidation, SearchFormatList, ApiData, ApiFetch } from '@dxtmisha/functional-basic';
+import { ApiInstance, ArrayToItem, FormattersListColumns, FormattersOptionsList, SearchColumns, ApiDataValidation, SearchFormatList, ApiData, ApiErrorItem, ApiFetch } from '@dxtmisha/functional-basic';
 import { ApiManagementGet, ApiManagementRequest, ApiManagementSearch, ApiManagementValue } from '../../types/apiTypes';
 import { ComputedRef, Ref } from 'vue';
 /**
- * Executes an API management request and immediately initializes it asynchronously.
+ * Asynchronous reactive composable for API management requests with built-in SSR support.
+ * Wraps `useApiManagementRef` and immediately calls `initSsr()` to ensure data is pre-fetched on the server side.
+ * Use this composable ONLY if you need the request to be executed on the server side during SSR.
+ * For all other cases, use `useApiManagementRef`.
  *
- * Выполняет запрос управления API и сразу инициализирует его асинхронно.
+ * Асинхронный реактивный composable для запросов управления API со встроенной поддержкой SSR.
+ * Оборачивает `useApiManagementRef` и сразу вызывает `initSsr()`, чтобы гарантировать предзагрузку данных на сервере.
+ * Используйте этот composable ТОЛЬКО если вам необходимо, чтобы запрос был выполнен на стороне сервера
+ * во время SSR. Во всех остальных случаях используйте обычный `useApiManagementRef`.
  * @template Return type of data returned by the API / тип данных, возвращаемых API
  * @template FormattersOptions optional formatting rules / опциональные правила форматирования
  * @template Post data type for POST creation request / тип данных для POST-запроса создания
@@ -30,6 +36,7 @@ export declare function useApiManagementAsyncRef<Return extends ApiManagementVal
     responseValidationResult: ComputedRef< ApiDataValidation | undefined>;
     list: ComputedRef<SearchFormatList<ItemFormatters, Columns>>;
     readonly data: ComputedRef< ApiData<Return> | undefined>;
+    errorItem: ComputedRef< ApiErrorItem | undefined>;
     readonly length: ComputedRef<number>;
     lengthData: ComputedRef<number>;
     starting: ComputedRef<boolean>;
@@ -40,7 +47,7 @@ export declare function useApiManagementAsyncRef<Return extends ApiManagementVal
     loadingPut: Ref<boolean, boolean> | undefined;
     loadingDelete: Ref<boolean, boolean> | undefined;
     isSearch: ComputedRef<boolean> | undefined;
-    search: Ref<string, string> | undefined;
+    search: Ref<string>;
     init: () => void;
     initSsr: () => void;
     reset: () => Promise<void>;

package/dist/src/composables/ref/useApiManagementRef.d.ts

@@ -1,6 +1,6 @@
-import { FormattersOptionsList, ApiData, ApiInstance, ArrayToItem, SearchColumns, SearchFormatList, FormattersListColumns, ApiFetch, ApiDataValidation } from '@dxtmisha/functional-basic';
+import { Ref, ComputedRef } from 'vue';
+import { FormattersOptionsList, ApiData, ApiInstance, ArrayToItem, SearchColumns, SearchFormatList, FormattersListColumns, ApiFetch, ApiDataValidation, ApiErrorItem } from '@dxtmisha/functional-basic';
 import { ApiManagementGet, ApiManagementRequest, ApiManagementSearch, ApiManagementValue } from '../../types/apiTypes';
-import { ComputedRef, Ref } from 'vue';
 /**
  * A powerful composable for comprehensive API request orchestration.
  * It centrally manages data loading (GET), list formatting, client-side searching,
@@ -84,6 +84,8 @@ export declare function useApiManagementRef<Return extends ApiManagementValue, F
     list: ComputedRef<SearchFormatList<ItemFormatters, Columns>>;
     /** Raw reactive data from `useApiRef` / «Сырые» реактивные данные из `useApiRef` */
     readonly data: ComputedRef<ApiData<Return> | undefined>;
+    /** Current error from request / Текущая ошибка ответа */
+    errorItem: ComputedRef< ApiErrorItem | undefined>;
     /** Current number of items in `list` (changes with search) / Текущее количество элементов в `list` (меняется при поиске) */
     readonly length: ComputedRef<number>;
     /** Total number of items in raw `data` / Общее количество элементов в исходном `data` */
@@ -105,7 +107,7 @@ export declare function useApiManagementRef<Return extends ApiManagementValue, F
     /** Whether search is currently active / Активен ли поиск (есть ли поисковый запрос) */
     isSearch: ComputedRef<boolean> | undefined;
     /** Reactive search string (Proxy to `searchOptions.value`) / Реактивная строка поиска (Proxy к переданному `searchOptions.value`) */
-    search: Ref<string, string> | undefined;
+    search: Ref<string>;
     /**
      * Manual initialization
      *

package/dist/src/composables/ref/useApiPost.d.ts

@@ -1,20 +1,28 @@
-import { ApiInstance, ApiData, ApiFetch } from '@dxtmisha/functional-basic';
+import { ApiInstance, ApiData, ApiFetch, ApiErrorStorageList } from '@dxtmisha/functional-basic';
 import { ApiOptions } from '../../types/apiTypes';
 import { RefOrNormal } from '../../types/refTypes';
 import { Ref } from 'vue';
 /**
  * Use API post request.
+ * This is a convenient wrapper over `useApiRequest` that pre-fills the POST method.
  *
  * Использование API post запроса.
+ * Это удобная обертка над `useApiRequest`, которая предустанавливает метод POST.
  * @param path Path to the API endpoint / Путь к endpoint API
  * @param action Action to perform after the request / Действие, выполняемое после запроса
  * @param transformation Transformation function / Функция трансформации
+ * @param errorContract array of expected error contracts for the request (`ApiErrorStorageList`).
+ * Highly recommended to add if there is information about possible request errors. Allows you to predefine
+ * possible errors (by code, status, or custom validation) which will be centrally processed by the application. /
+ * Массив контрактов ожидаемых ошибок для запроса (`ApiErrorStorageList`). Желательно добавлять, если есть
+ * информация о возможных ошибках запроса. Позволяет заранее описать возможные ошибки (по коду, статусу или
+ * кастомной валидации) для централизованной обработки в приложении.
  * @param toData Extract 'data' field from response / Извлечь поле 'data' из ответа
  * @param options Additional request options / Дополнительные опции запроса
  * @param apiInstance Api instance / Экземпляр Api
  * @returns Object with loading state and send method / Объект с состоянием загрузки и методом отправки
  */
-export declare function useApiPost<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(path?: RefOrNormal<string | undefined>, action?: (data: Return | undefined) => Promise<void> | void, transformation?: (data: T) => Return, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
+export declare function useApiPost<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(path?: RefOrNormal<string | undefined>, action?: (data: Return | undefined) => Promise<void> | void, transformation?: (data: T) => Return, errorContract?: ApiErrorStorageList, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
     loading: Ref<boolean, boolean>;
     send(request?: Request | undefined): Promise<Return | undefined>;
 };

package/dist/src/composables/ref/useApiPut.d.ts

@@ -1,20 +1,28 @@
-import { ApiInstance, ApiData, ApiFetch } from '@dxtmisha/functional-basic';
+import { ApiInstance, ApiData, ApiFetch, ApiErrorStorageList } from '@dxtmisha/functional-basic';
 import { ApiOptions } from '../../types/apiTypes';
 import { RefOrNormal } from '../../types/refTypes';
 import { Ref } from 'vue';
 /**
  * Use API put request.
+ * This is a convenient wrapper over `useApiRequest` that pre-fills the PUT method.
  *
  * Использование API put запроса.
+ * Это удобная обертка над `useApiRequest`, которая предустанавливает метод PUT.
  * @param path Path to the API endpoint / Путь к endpoint API
  * @param action Action to perform after the request / Действие, выполняемое после запроса
  * @param transformation Transformation function / Функция трансформации
+ * @param errorContract array of expected error contracts for the request (`ApiErrorStorageList`).
+ * Highly recommended to add if there is information about possible request errors. Allows you to predefine
+ * possible errors (by code, status, or custom validation) which will be centrally processed by the application. /
+ * Массив контрактов ожидаемых ошибок для запроса (`ApiErrorStorageList`). Желательно добавлять, если есть
+ * информация о возможных ошибках запроса. Позволяет заранее описать возможные ошибки (по коду, статусу или
+ * кастомной валидации) для централизованной обработки в приложении.
  * @param toData Extract 'data' field from response / Извлечь поле 'data' из ответа
  * @param options Additional request options / Дополнительные опции запроса
  * @param apiInstance Api instance / Экземпляр Api
  * @returns Object with loading state and send method / Объект с состоянием загрузки и методом отправки
  */
-export declare function useApiPut<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(path?: RefOrNormal<string | undefined>, action?: (data: Return | undefined) => Promise<void> | void, transformation?: (data: T) => Return, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
+export declare function useApiPut<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(path?: RefOrNormal<string | undefined>, action?: (data: Return | undefined) => Promise<void> | void, transformation?: (data: T) => Return, errorContract?: ApiErrorStorageList, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
     loading: Ref<boolean, boolean>;
     send(request?: Request | undefined): Promise<Return | undefined>;
 };

package/dist/src/composables/ref/useApiRef.d.ts

@@ -1,5 +1,5 @@
 import { ComputedRef, Ref } from 'vue';
-import { ApiInstance, ApiData, ApiDataValidation } from '@dxtmisha/functional-basic';
+import { ApiInstance, ApiData, ApiDataValidation, ApiErrorStorageList, ApiErrorItem } from '@dxtmisha/functional-basic';
 import { ApiOptions } from '../../types/apiTypes';
 import { RefOrNormal, RefType } from '../../types/refTypes';
 /**
@@ -12,6 +12,8 @@ export interface UseApiRef<R> {
     data: ComputedRef<ApiData<R> | undefined>;
     /** Item (Ref) / Элемент (Ref) */
     item: Ref<ApiData<R> | undefined>;
+    /** Error item (Computed) / Элемент ошибки (Computed) */
+    errorItem: ComputedRef<ApiErrorItem | undefined>;
     /**
      * Status of response contract validation.
      *
@@ -84,19 +86,70 @@ export interface UseApiRef<R> {
     abort(): void;
 }
 /**
- * Returns data for working with requests.
+ * Main reactive composable for working with API requests in Vue.
+ * Automatically handles SSR, reactivity, caching, error storage, data validation, and transformation.
  *
- * Возвращает данные для работы с запросами.
- * @param path path to request / путь к запросу
- * @param options data for the request / данные для запроса
- * @param reactivity should reactivity be enabled / включить ли реактивность
- * @param conditions conditions for executing the request / условия выполнения запроса
- * @param transformation transforms the received request / преобразовывает полученный запрос
- * @param validateResponseContract function to validate response data contract / функция для проверки контракта данных ответа
- * @param unmounted delete data from the cache / удалить ли данные из кеша
- * @param apiInstance Api instance / Экземпляр Api
+ * Главный реактивный composable для работы с API запросами во Vue.
+ * Автоматически обрабатывает SSR, реактивность, кэширование, хранение ошибок, валидацию данных и трансформацию.
+ *
+ * @example
+ * ```typescript
+ * import { Schema as S } from '@effect/schema'
+ * import { useApiRef } from '@dxtmisha/functional'
+ *
+ * // Define a schema using @effect/schema
+ * const userSchema = S.Struct({ id: S.Number, name: S.String })
+ *
+ * const { data, loading, errorItem, isResponseContractValid } = useApiRef(
+ *   '/users/1',
+ *   { method: 'GET' },
+ *   true, // reactivity
+ *   undefined, // conditions
+ *   (data) => ({ ...data, isTransformed: true }), // transformation
+ *   (data) => { // validateResponseContract
+ *     try {
+ *       return { status: 'success', data: S.decodeUnknownSync(userSchema)(data) }
+ *     } catch (e) {
+ *       return { status: 'error', errors: e }
+ *     }
+ *   },
+ *   [ // errorContract (ApiErrorStorageList)
+ *     {
+ *       status: 404,
+ *       message: 'User not found'
+ *     }
+ *   ]
+ * )
+ * ```
+ *
+ * @param path path to request (can be a Ref or Getter) / путь к запросу (может быть Ref или Getter)
+ * @param options data for the request (headers, method, etc.) / данные для запроса (заголовки, метод и т.д.)
+ * @param reactivity should reactivity be enabled (automatically re-fetch on deps change) /
+ * включить ли реактивность (автоматически повторять запрос при изменении зависимостей)
+ * @param conditions conditions for executing the request (request will wait until true) /
+ * условия выполнения запроса (запрос будет ждать пока не станет true)
+ * @param transformation transforms the received response data / преобразовывает полученные данные ответа
+ * @param validateResponseContract function to validate response data contract. Used to ensure that the API
+ * response matches the expected structure. Highly recommended to use with `@effect/schema`.
+ * It should return `ApiDataValidation` containing a `status` ('success' or 'error')
+ * and the parsed data or errors. /
+ * Функция для проверки контракта данных ответа. Используется для гарантии того, что ответ API соответствует
+ * ожидаемой структуре. Настоятельно рекомендуется использовать с `@effect/schema`. Должна возвращать объект
+ * `ApiDataValidation`, содержащий `status` ('success' или 'error') и распарсенные данные или ошибки.
+ * @param errorContract array of expected error contracts for the request (`ApiErrorStorageList`).
+ * Highly recommended to add if there is information about possible request errors. Allows you to predefine
+ * possible errors (by code, status, or custom validation). If an error occurs matching one of these contracts,
+ * it will be automatically processed and made available via the `errorItem` computed property. /
+ * Массив контрактов ожидаемых ошибок для запроса (`ApiErrorStorageList`). Желательно добавлять, если есть
+ * информация о возможных ошибках запроса. Позволяет заранее описать возможные ошибки (по коду, статусу или
+ * кастомной валидации). Если возникает ошибка, совпадающая с одним из контрактов, она автоматически
+ * обрабатывается и становится доступной через вычисляемое свойство `errorItem` для удобного отображения в UI.
+ * @param unmounted whether to stop the request and clear data from cache when component is unmounted /
+ * нужно ли останавливать запрос и удалять данные из кеша при размонтировании компонента
+ * @param apiInstance Api instance (defaults to global Api instance) /
+ * Экземпляр Api (по умолчанию используется глобальный экземпляр Api)
  */
-export declare function useApiRef<R, T = R>(path?: RefOrNormal<string | undefined>, options?: ApiOptions, reactivity?: boolean, conditions?: RefType<boolean>, transformation?: (data: T, isResponseContractValid?: ApiDataValidation) => ApiData<R>, validateResponseContract?: (data: T) => ApiDataValidation, unmounted?: boolean, apiInstance?: ApiInstance): UseApiRef<R>;
+export declare function useApiRef<R, T = R>(path?: RefOrNormal<string | undefined>, options?: ApiOptions, reactivity?: boolean, conditions?: RefType<boolean>, transformation?: (data: T, isResponseContractValid?: ApiDataValidation) => ApiData<R>, validateResponseContract?: (data: T) => ApiDataValidation, errorContract?: ApiErrorStorageList, unmounted?: boolean, apiInstance?: ApiInstance): UseApiRef<R>;
 /**
  * Defines global conditions for the API request.
  *

package/dist/src/composables/ref/useApiRequest.d.ts

@@ -1,4 +1,4 @@
-import { ApiInstance, ApiMethodItem, ApiData, ApiFetch } from '@dxtmisha/functional-basic';
+import { ApiInstance, ApiMethodItem, ApiData, ApiFetch, ApiErrorStorageList } from '@dxtmisha/functional-basic';
 import { ApiOptions } from '../../types/apiTypes';
 import { RefOrNormal } from '../../types/refTypes';
 import { Ref } from 'vue';
@@ -10,12 +10,19 @@ import { Ref } from 'vue';
  * @param method HTTP method / HTTP метод
  * @param action Action to perform after the request / Действие, выполняемое после запроса
  * @param transformation Transformation function / Функция трансформации
+ * @param errorContract array of expected error contracts for the request (`ApiErrorStorageList`).
+ * Highly recommended to add if there is information about possible request errors. Allows you to predefine
+ * possible errors (by code, status, or custom validation) which will be centrally processed by the application. /
+ * Массив контрактов ожидаемых ошибок для запроса (`ApiErrorStorageList`). Желательно добавлять, если есть
+ * информация о возможных ошибках запроса. Позволяет заранее описать возможные ошибки (по коду, статусу или
+ * кастомной валидации) для централизованной обработки в приложении.
  * @param toData Extract 'data' field from response / Извлечь поле 'data' из ответа
  * @param options Additional request options / Дополнительные опции запроса
  * @param apiInstance Api instance / Экземпляр Api
  * @returns Object with loading state and send method / Объект с состоянием загрузки и методом отправки
  */
-export declare function useApiRequest<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(path?: RefOrNormal<string | undefined>, method?: ApiMethodItem, action?: (data: Return | undefined) => Promise<void> | void, transformation?: (data: T) => Return, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
+export declare function useApiRequest<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(path?: RefOrNormal<string | undefined>, method?: ApiMethodItem, action?: (data: Return | undefined) => Promise<void> | void, transformation?: (data: T) => Return, errorContract?: ApiErrorStorageList, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
+    /** Loading state / Состояние загрузки */
     loading: Ref<boolean, boolean>;
     /**
      * Send request.

package/dist/src/functions/ref/getApiErrorRef.d.ts

@@ -0,0 +1,10 @@
+import { ComputedRef } from 'vue';
+import { ApiData, ApiErrorItem } from '@dxtmisha/functional-basic';
+import { RefType } from '../../types/refTypes';
+/**
+ * Returns the error item for the Api ref.
+ *
+ * Возвращает элемент ошибки для Api ref.
+ * @param data data for the request / данные для запроса
+ */
+export declare function getApiErrorRef<R>(data: RefType<ApiData<R> | undefined>): ComputedRef<ApiErrorItem | undefined>;

package/dist/src/library.d.ts

@@ -45,6 +45,7 @@ export * from './functions/dxtFunctionalPlugin';
 export * from './functions/executeUse';
 export * from './functions/getInject';
 export * from './functions/getOptions';
+export * from './functions/ref/getApiErrorRef';
 export * from './functions/ref/getBindRef';
 export * from './functions/ref/getRef';
 export * from './functions/ref/render';

package/dist/src/types/apiTypes.d.ts

@@ -1,4 +1,4 @@
-import { ApiData, ApiDataValidation, ApiDefaultValue, ApiFetch, ApiMethodItem, SearchColumns, SearchItem, SearchOptions } from '@dxtmisha/functional-basic';
+import { ApiData, ApiDataValidation, ApiDefaultValue, ApiErrorStorageList, ApiFetch, ApiMethodItem, SearchColumns, SearchItem, SearchOptions } from '@dxtmisha/functional-basic';
 import { RefOrNormal, RefType } from './refTypes';
 import { Ref } from 'vue';
 /** Options for api requests/ Опции для запросов api */
@@ -27,6 +27,8 @@ export type ApiManagementGet<Return extends ApiManagementValue, Type extends Api
     transformation?: (data: Type, isResponseContractValid?: ApiDataValidation) => ApiData<Return>;
     /** Function to validate response data contract / Функция для проверки контракта данных ответа */
     validateResponseContract?: (data: Type) => ApiDataValidation;
+    /** Storage of response error contracts / Хранилище контрактов ошибок ответа */
+    errorContract?: ApiErrorStorageList;
     /** Validation function or class constructor for data / Функция валидации или конструктор класса для данных */
     typeData?: ((data: Return) => boolean) | any;
     /** Whether to clear data when the component is unmounted / Удалять ли данные при размонтировании компонента */
@@ -59,6 +61,8 @@ export type ApiManagementRequest<T, Return extends ApiData<T> = ApiData<T>> = {
     action?: (data: Return | undefined) => Promise<void> | void;
     /** Transformation before sending data / Трансформация перед отправкой данных */
     transformation?: (data: T) => Return;
+    /** Storage of response error contracts / Хранилище контрактов ошибок ответа */
+    errorContract?: ApiErrorStorageList;
     /** Whether to wrap the payload in a 'data' property / Обертывать ли полезную нагрузку в свойство 'data' */
     toData?: boolean;
     /** Additional mutation request options / Дополнительные опции запроса мутации */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dxtmisha/functional",
   "private": false,
-  "version": "1.11.11",
+  "version": "1.11.12",
   "type": "module",
   "description": "A comprehensive library of utilities, base classes, and Vue 3 composables for reactive web development. Extends @dxtmisha/functional-basic with Composition API.",
   "keywords": [