@dxtmisha/functional 1.11.13 → 1.12.0

package/dist/library.js

@@ -804,50 +804,71 @@ function ze(t, n, r = !0, i, a, o, s, c = !0, l = e.getItem()) {
 }
 //#endregion
 //#region src/composables/ref/useApiRequest.ts
-function Q(r, i = n.post, a, o, s, c = !0, l, u = e.getItem()) {
-	let d = R(!1), f = K(Ie(l));
-	return s && t.add(s, U(r), i), {
-		loading: d,
+function Q({ path: r, method: i = n.post, action: a, transformation: o, validateRequestContract: s, validateResponseContract: c, errorContract: l, toData: u = !0, options: d, apiInstance: f = e.getItem() }) {
+	let p = R(!1), m = K(Ie(d));
+	return l && t.add(l, U(r), i), {
+		loading: p,
 		async send(e) {
-			d.value = !0;
 			let t;
 			try {
-				if (t = await u.request({
+				if (e && s) {
+					let t = s(e);
+					if (t && !D(t)) return t;
+				}
+				if (p.value = !0, t = await f.request({
 					path: U(r),
 					method: i,
 					request: e,
-					toData: c,
-					...f.value
-				}), t && (o && (t = o(t)), a)) {
-					let e = a(t);
-					e instanceof Promise && await e;
+					toData: u,
+					...m.value
+				}), t) {
+					if (c && D(t)) {
+						let e = c(t);
+						e && !D(e) && (t = e);
+					}
+					if (o && D(t) && (t = o(t)), a) {
+						let e = a(t);
+						e instanceof Promise && await e;
+					}
 				}
 			} catch (e) {
 				t = void 0;
 			}
-			return d.value = !1, t;
+			return p.value = !1, t;
 		}
 	};
 }
 //#endregion
 //#region src/composables/ref/useApiDelete.ts
-function Be(e, t, r, i, a = !0, o, s) {
-	return Q(e, n.delete, t, r, i, a, o, s);
+function Be(e) {
+	return Q({
+		...e,
+		method: n.delete
+	});
 }
 //#endregion
 //#region src/composables/ref/useApiGet.ts
-function Ve(e, t, r, i, a = !0, o, s) {
-	return Q(e, n.get, t, r, i, a, o, s);
+function Ve(e) {
+	return Q({
+		...e,
+		method: n.get
+	});
 }
 //#endregion
 //#region src/composables/ref/useApiPost.ts
-function He(e, t, r, i, a = !0, o, s) {
-	return Q(e, n.post, t, r, i, a, o, s);
+function He(e) {
+	return Q({
+		...e,
+		method: n.post
+	});
 }
 //#endregion
 //#region src/composables/ref/useApiPut.ts
-function Ue(e, t, r, i, a = !0, o, s) {
-	return Q(e, n.put, t, r, i, a, o, s);
+function Ue(e) {
+	return Q({
+		...e,
+		method: n.put
+	});
 }
 //#endregion
 //#region src/composables/ref/useFormattersRef.ts
@@ -901,7 +922,19 @@ function qe(e, t, n, r, i, a, o, s) {
 		}, t = (t) => async (n) => {
 			A(t) && await S(t(n)), e(n);
 		};
-		r && (b = He(r.path, t(r.action), r.transformation, r.errorContract, r.toData, r.options, s)), i && (x = Ue(i.path, t(i.action), i.transformation, i.errorContract, i.toData, i.options, s)), a && (C = Be(a.path, t(a.action), a.transformation, a.errorContract, a.toData, a.options, s));
+		r && (b = He({
+			...r,
+			action: t(r.action),
+			apiInstance: s
+		})), i && (x = Ue({
+			...i,
+			action: t(i.action),
+			apiInstance: s
+		})), a && (C = Be({
+			...a,
+			action: t(a.action),
+			apiInstance: s
+		}));
 	}
 	let O = I(() => {
 		if (T.value) {

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

@@ -1,28 +1,23 @@
-import { ApiInstance, ApiData, ApiFetch, ApiErrorStorageList } from '@dxtmisha/functional-basic';
-import { ApiOptions } from '../../types/apiTypes';
-import { RefOrNormal } from '../../types/refTypes';
+import { ApiData, ApiFetch } from '@dxtmisha/functional-basic';
+import { UseApiRequestSetup } from './useApiRequest';
 import { Ref } from 'vue';
+/**
+ * Setup interface for API DELETE request.
+ *
+ * Интерфейс настроек для DELETE запроса API.
+ */
+export interface UseApiDeleteSetup<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>> extends Omit<UseApiRequestSetup<T, Request, Return>, 'method'> {
+}
 /**
  * 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
+ * @param setup Configured parameters as a single object / Настроенные параметры в виде единого объекта
  * @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, errorContract?: ApiErrorStorageList, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
+export declare function useApiDelete<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(setup: UseApiDeleteSetup<T, Request, Return>): {
     loading: Ref<boolean, boolean>;
     send(request?: Request | undefined): Promise<Return | undefined>;
 };

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

@@ -1,28 +1,23 @@
-import { ApiInstance, ApiData, ApiFetch, ApiErrorStorageList } from '@dxtmisha/functional-basic';
-import { ApiOptions } from '../../types/apiTypes';
-import { RefOrNormal } from '../../types/refTypes';
+import { ApiData, ApiFetch } from '@dxtmisha/functional-basic';
+import { UseApiRequestSetup } from './useApiRequest';
 import { Ref } from 'vue';
+/**
+ * Setup interface for API GET request.
+ *
+ * Интерфейс настроек для GET запроса API.
+ */
+export interface UseApiGetSetup<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>> extends Omit<UseApiRequestSetup<T, Request, Return>, 'method'> {
+}
 /**
  * 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
+ * @param setup Configured parameters as a single object / Настроенные параметры в виде единого объекта
  * @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, errorContract?: ApiErrorStorageList, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
+export declare function useApiGet<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(setup: UseApiGetSetup<T, Request, Return>): {
     loading: Ref<boolean, boolean>;
     send(request?: Request | undefined): Promise<Return | undefined>;
 };

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

@@ -1,28 +1,23 @@
-import { ApiInstance, ApiData, ApiFetch, ApiErrorStorageList } from '@dxtmisha/functional-basic';
-import { ApiOptions } from '../../types/apiTypes';
-import { RefOrNormal } from '../../types/refTypes';
+import { ApiData, ApiFetch } from '@dxtmisha/functional-basic';
+import { UseApiRequestSetup } from './useApiRequest';
 import { Ref } from 'vue';
+/**
+ * Setup interface for API POST request.
+ *
+ * Интерфейс настроек для POST запроса API.
+ */
+export interface UseApiPostSetup<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>> extends Omit<UseApiRequestSetup<T, Request, Return>, 'method'> {
+}
 /**
  * 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
+ * @param setup Configured parameters as a single object / Настроенные параметры в виде единого объекта
  * @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, errorContract?: ApiErrorStorageList, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
+export declare function useApiPost<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(setup: UseApiPostSetup<T, Request, Return>): {
     loading: Ref<boolean, boolean>;
     send(request?: Request | undefined): Promise<Return | undefined>;
 };

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

@@ -1,28 +1,23 @@
-import { ApiInstance, ApiData, ApiFetch, ApiErrorStorageList } from '@dxtmisha/functional-basic';
-import { ApiOptions } from '../../types/apiTypes';
-import { RefOrNormal } from '../../types/refTypes';
+import { ApiData, ApiFetch } from '@dxtmisha/functional-basic';
+import { UseApiRequestSetup } from './useApiRequest';
 import { Ref } from 'vue';
+/**
+ * Setup interface for API PUT request.
+ *
+ * Интерфейс настроек для PUT запроса API.
+ */
+export interface UseApiPutSetup<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>> extends Omit<UseApiRequestSetup<T, Request, Return>, 'method'> {
+}
 /**
  * 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
+ * @param setup Configured parameters as a single object / Настроенные параметры в виде единого объекта
  * @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, errorContract?: ApiErrorStorageList, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
+export declare function useApiPut<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>(setup: UseApiPutSetup<T, Request, Return>): {
     loading: Ref<boolean, boolean>;
     send(request?: Request | undefined): Promise<Return | undefined>;
 };

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

@@ -1,27 +1,97 @@
-import { ApiInstance, ApiMethodItem, ApiData, ApiFetch, ApiErrorStorageList } from '@dxtmisha/functional-basic';
+import { ApiInstance, ApiMethodItem, ApiData, ApiFetch, ApiErrorStorageList, ApiDataValidation } from '@dxtmisha/functional-basic';
 import { ApiOptions } from '../../types/apiTypes';
 import { RefOrNormal } from '../../types/refTypes';
 import { Ref } from 'vue';
+/**
+ * Setup interface for API request.
+ *
+ * Интерфейс настроек для запроса API.
+ */
+export interface UseApiRequestSetup<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>> {
+    /**
+     * Path to the API endpoint. Can be a reactive Ref or a normal string.
+     *
+     * Путь к endpoint API. Может быть реактивным Ref или обычной строкой.
+     */
+    path?: RefOrNormal<string | undefined>;
+    /**
+     * HTTP method used for the request (e.g., GET, POST, PUT, DELETE). Defaults to POST.
+     *
+     * HTTP метод, используемый для запроса (например, GET, POST, PUT, DELETE). По умолчанию POST.
+     */
+    method?: ApiMethodItem;
+    /**
+     * Action/callback to perform after the request has successfully completed.
+     * Can return a Promise for asynchronous operations.
+     *
+     * Действие/колбэк, выполняемое после успешного завершения запроса.
+     * Может возвращать Promise для асинхронных операций.
+     */
+    action?: (data: Return | undefined) => Promise<void> | void;
+    /**
+     * Transformation function that modifies the raw response data before returning it.
+     *
+     * Функция трансформации, которая преобразует исходные данные ответа перед их возвратом.
+     */
+    transformation?: (data: T) => Return;
+    /**
+     * Function to validate the request payload contract. Used to ensure that the API
+     * request payload matches the expected structure.
+     *
+     * Функция для проверки контракта данных запроса. Используется для гарантии того,
+     * что отправляемая полезная нагрузка запроса API соответствует ожидаемой структуре.
+     */
+    validateRequestContract?: (data: Request) => ApiDataValidation & Return;
+    /**
+     * 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') и распарсенные данные или ошибки.
+     */
+    validateResponseContract?: (data: T) => ApiDataValidation & Return;
+    /**
+     * 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`). Желательно добавлять, если есть
+     * информация о возможных ошибках запроса. Позволяет заранее описать возможные ошибки (по коду, статусу или
+     * кастомной валидации) для централизованной обработки в приложении.
+     */
+    errorContract?: ApiErrorStorageList;
+    /**
+     * If true, extracts the nested 'data' field from the response object instead of returning the raw envelope.
+     * Defaults to true.
+     *
+     * Если true, извлекает вложенное поле 'data' из объекта ответа вместо возврата исходного конверта.
+     * По умолчанию true.
+     */
+    toData?: boolean;
+    /**
+     * Additional request options (headers, query params, etc.).
+     *
+     * Дополнительные опции запроса (заголовки, параметры запроса и т.д.).
+     */
+    options?: ApiOptions;
+    /**
+     * Custom Api instance to execute the request on. Defaults to global Api singleton instance.
+     *
+     * Кастомный экземпляр класса Api для выполнения запроса. По умолчанию используется глобальный синглтон Api.
+     */
+    apiInstance?: ApiInstance;
+}
 /**
  * Use api request.
  *
  * Использование запроса api.
- * @param path Path to the API endpoint / Путь к endpoint API
- * @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
+ * @param setup Configured parameters as a single object / Настроенные параметры в виде единого объекта
  * @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, errorContract?: ApiErrorStorageList, toData?: boolean, options?: ApiOptions, apiInstance?: ApiInstance): {
+export declare function useApiRequest<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>>({ path, method, action, transformation, validateRequestContract, validateResponseContract, errorContract, toData, options, apiInstance }: UseApiRequestSetup<T, Request, Return>): {
     /** Loading state / Состояние загрузки */
     loading: Ref<boolean, boolean>;
     /**

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

@@ -54,13 +54,17 @@ export type ApiManagementSearch<T extends SearchItem, K extends SearchColumns<T>
  *
  * Конфигурация для запросов мутации (POST, PUT, DELETE).
  */
-export type ApiManagementRequest<T, Return extends ApiData<T> = ApiData<T>> = {
+export type ApiManagementRequest<T, Request extends ApiFetch['request'] = ApiFetch['request'], Return extends ApiData<T> = ApiData<T>> = {
     /** Target API endpoint path / Целевой путь к API */
     path?: RefOrNormal<string | undefined>;
     /** Action to perform after a successful request / Действие после успешного выполнения запроса */
     action?: (data: Return | undefined) => Promise<void> | void;
     /** Transformation before sending data / Трансформация перед отправкой данных */
     transformation?: (data: T) => Return;
+    /** Request contract validation function / Функция валидации контракта запроса */
+    validateRequestContract?: (data: Request) => ApiDataValidation & Return;
+    /** Response contract validation function / Функция валидации контракта ответа */
+    validateResponseContract?: (data: T) => ApiDataValidation & Return;
     /** Storage of response error contracts / Хранилище контрактов ошибок ответа */
     errorContract?: ApiErrorStorageList;
     /** Whether to wrap the payload in a 'data' property / Обертывать ли полезную нагрузку в свойство 'data' */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dxtmisha/functional",
   "private": false,
-  "version": "1.11.13",
+  "version": "1.12.0",
   "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": [