@dxtmisha/functional-basic 1.2.3 → 1.2.5

package/dist/src/classes/Api.d.ts

@@ -1,5 +1,5 @@
 import { ApiInstance } from './ApiInstance';
-import { ApiConfig, ApiFetch, ApiMethodItem, ApiPreparationEnd } from '../types/apiTypes';
+import { ApiConfig, ApiDefaultValue, ApiFetch, ApiHeadersValue, ApiMethodItem, ApiPreparationEnd } from '../types/apiTypes';
 import { ApiStatus } from './ApiStatus';
 import { ApiResponse } from './ApiResponse';
 import { ApiHydration } from './ApiHydration';
@@ -93,7 +93,7 @@ export declare class Api {
      * @param headers default headers / заголовки по умолчанию
      * @returns void / ничего не возвращает
      */
-    static setHeaders(headers: Record<string, string> | (() => Record<string, string>)): void;
+    static setHeaders(headers: ApiHeadersValue): void;
     /**
      * Modifies the default request data.
      *
@@ -101,7 +101,7 @@ export declare class Api {
      * @param request default request data / данные запроса по умолчанию
      * @returns void / ничего не возвращает
      */
-    static setRequestDefault(request: Record<string, any>): void;
+    static setRequestDefault(request: ApiDefaultValue): void;
     /**
      * Changes the base path to the script.
      *

package/dist/src/classes/ApiDataReturn.d.ts

@@ -1,4 +1,5 @@
 import { ApiStatus } from './ApiStatus';
+import { ApiErrorItem } from './ApiErrorItem';
 import { ApiData, ApiFetch, ApiPreparationEnd } from '../types/apiTypes';
 /**
  * Class for handling and processing data returned from an API request.
@@ -9,6 +10,7 @@ export declare class ApiDataReturn<T = any> {
     protected readonly apiFetch: ApiFetch;
     protected readonly query: Response;
     protected readonly end: ApiPreparationEnd;
+    protected readonly error?: ApiErrorItem | undefined;
     /**
      * Raw data received from the API/
      * Исходные данные, полученные от API
@@ -26,8 +28,9 @@ export declare class ApiDataReturn<T = any> {
      * @param apiFetch API fetch configuration / конфигурация запроса API
      * @param query response object / объект ответа
      * @param end preparation end data / данные завершения подготовки
+     * @param error error object / объект ошибки
      */
-    constructor(apiFetch: ApiFetch, query: Response, end: ApiPreparationEnd);
+    constructor(apiFetch: ApiFetch, query: Response, end: ApiPreparationEnd, error?: ApiErrorItem | undefined);
     /**
      * Initializes the class by reading data from the response.
      *

package/dist/src/classes/ApiDefault.d.ts

@@ -20,7 +20,7 @@ export declare class ApiDefault {
      * Получает данные запроса по умолчанию.
      * @returns default request data or undefined / данные запроса по умолчанию или undefined
      */
-    get(): ApiDefaultValue | undefined;
+    get(): Record<string, any> | undefined;
     /**
      * Adds default data to the request.
      *

package/dist/src/classes/ApiError.d.ts

@@ -0,0 +1,39 @@
+import { ApiErrorItem } from './ApiErrorItem';
+import { ApiErrorStorage } from './ApiErrorStorage';
+import { ApiErrorStorageItem, ApiMethodItem } from '../types/apiTypes';
+/**
+ * Utility class for managing the API error storage and creating error items.
+ * It provides a centralized way to access the error storage and wrap raw
+ * responses into structured error items.
+ *
+ * Утилитарный класс для управления хранилищем ошибок API и создания элементов ошибок.
+ * Обеспечивает централизованный способ доступа к хранилищу ошибок и оборачивания
+ * сырых ответов в структурированные элементы ошибок.
+ */
+export declare class ApiError {
+    /**
+     * Retrieves the singleton instance of the API error storage.
+     *
+     * Возвращает синглтон-экземпляр хранилища ошибок API.
+     * @returns error storage instance / экземпляр хранилища ошибок
+     */
+    static getStorage(): ApiErrorStorage;
+    /**
+     * Adds an error item or a list of error items to the storage.
+     *
+     * Добавляет элемент ошибки или список элементов ошибок в хранилище.
+     * @param item error item or list of error items / элемент ошибки или список элементов ошибок
+     * @param url URL pattern or RegExp / шаблон URL или регулярное выражение
+     * @param method HTTP method of the request / HTTP-метод запроса
+     */
+    static add(item: Partial<ApiErrorStorageItem> | Partial<ApiErrorStorageItem>[], url?: string | RegExp, method?: ApiMethodItem): void;
+    /**
+     * Creates an ApiErrorItem by matching the response against stored error criteria.
+     *
+     * Создает ApiErrorItem путем сопоставления ответа с сохраненными критериями ошибок.
+     * @param method HTTP method of the request / HTTP-метод запроса
+     * @param response raw Fetch response / сырой ответ Fetch
+     * @returns structured error item / структурированный элемент ошибки
+     */
+    static getItem(method: ApiMethodItem, response: Response): Promise<ApiErrorItem>;
+}

package/dist/src/classes/ApiErrorItem.d.ts

@@ -0,0 +1,70 @@
+import { ApiErrorStorageItem, ApiMethodItem } from '../types/apiTypes';
+/**
+ * Class for managing and extracting data from an API error response.
+ * It encapsulates the request method, raw response, and identified error criteria,
+ * providing unified methods to retrieve error codes, messages, and status.
+ *
+ * Класс для управления и извлечения данных из ответа об ошибке API.
+ * Инкапсулирует метод запроса, сырой ответ и идентифицированные критерии ошибки,
+ * предоставляя единые методы для получения кодов ошибок, сообщений и статуса.
+ */
+export declare class ApiErrorItem {
+    protected readonly method: ApiMethodItem;
+    protected readonly response: Response;
+    protected readonly error: ApiErrorStorageItem;
+    /** Cached JSON response body / Кэшированное тело ответа JSON */
+    protected jsonResponse: any | undefined;
+    /**
+     * Constructor for ApiErrorItem.
+     *
+     * Конструктор для ApiErrorItem.
+     * @param method HTTP method used for the request / HTTP-метод, использованный для запроса
+     * @param response raw Fetch response object / сырой объект ответа Fetch
+     * @param error matched error item from storage (optional) / найденный элемент ошибки из хранилища (опционально)
+     */
+    constructor(method: ApiMethodItem, response: Response, error: ApiErrorStorageItem);
+    /**
+     * Returns the HTTP method used for the request.
+     *
+     * Возвращает HTTP-метод, использованный для запроса.
+     * @returns HTTP method / HTTP-метод
+     */
+    getMethod(): ApiMethodItem;
+    /**
+     * Returns the raw Fetch response object.
+     *
+     * Возвращает сырой объект ответа Fetch.
+     * @returns Fetch response / ответ Fetch
+     */
+    getResponse(): Response;
+    /**
+     * Returns the identified error item from storage if it exists.
+     *
+     * Возвращает идентифицированный элемент ошибки из хранилища, если он существует.
+     * @returns error item or undefined / элемент ошибки или undefined
+     */
+    getError(): ApiErrorStorageItem;
+    /**
+     * Asynchronously retrieves the error code from storage or the response body.
+     *
+     * Асинхронно получает код ошибки из хранилища или тела ответа.
+     * @returns error code or undefined / код ошибки или undefined
+     */
+    getCode(): string | undefined;
+    /**
+     * Asynchronously retrieves the error message.
+     * Checks the identified error item, the response body, or falls back to status text.
+     *
+     * Асинхронно получает сообщение об ошибке.
+     * Проверяет идентифицированный элемент ошибки, тело ответа или использует текст статуса.
+     * @returns error message or undefined / сообщение об ошибке или undefined
+     */
+    getMessage(): string | undefined;
+    /**
+     * Returns the HTTP status code of the response.
+     *
+     * Возвращает код статуса HTTP ответа.
+     * @returns status code / код статуса
+     */
+    getStatus(): number;
+}

package/dist/src/classes/ApiErrorStorage.d.ts

@@ -0,0 +1,84 @@
+import { ApiErrorStorageList, ApiErrorStorageItem, ApiMethodItem } from '../types/apiTypes';
+/**
+ * Manager for handling and identifying API error states.
+ *
+ * This class provides a centralized storage for API error criteria. It allows the system
+ * to identify specific errors by matching the response status, error code from the JSON body,
+ * request method, and URL. It is used to transform raw network errors into structured
+ * application-level error items for consistent processing.
+ *
+ * Менеджер для обработки и идентификации состояний ошибок API.
+ *
+ * Этот класс обеспечивает централизованное хранилище критериев ошибок API. Он позволяет
+ * системе идентифицировать конкретные ошибки путем сопоставления статуса ответа,
+ * кода ошибки из тела JSON, метода запроса и URL. Используется для преобразования
+ * сырых сетевых ошибок в структурированные элементы ошибок прикладного уровня для
+ * единообразной обработки.
+ */
+export declare class ApiErrorStorage {
+    /** Error storage list / Список хранилища ошибок */
+    protected storage: ApiErrorStorageList;
+    /**
+     * Finds a matching error item in the storage by analyzing the response.
+     *
+     * Ищет подходящий элемент ошибки в хранилище путем анализа ответа.
+     * @param method API method / Метод API
+     * @param response fetch response / Ответ fetch
+     * @returns matched error item or undefined / найденный элемент ошибки или undefined
+     */
+    find(method: ApiMethodItem, response: Response): Promise<ApiErrorStorageItem>;
+    /**
+     * Adds one or more error items or lists to the internal storage.
+     *
+     * Добавляет один или несколько элементов или списков ошибок во внутреннее хранилище.
+     * @param item error item or list of items / элемент ошибки или список элементов
+     * @param url URL pattern or RegExp / шаблон URL или регулярное выражение
+     * @param method HTTP method of the request / HTTP-метод запроса
+     * @returns current instance / текущий экземпляр
+     */
+    add(item: Partial<ApiErrorStorageItem> | Partial<ApiErrorStorageItem>[], url?: string | RegExp, method?: ApiMethodItem): this;
+    /**
+     * Checks if the response matches the criteria of any stored error item.
+     *
+     * Проверяет, соответствует ли ответ критериям любого сохраненного элемента ошибки.
+     * @param method API method / Метод API
+     * @param response fetch response / Ответ fetch
+     * @param code error code from response body / код ошибки из тела ответа
+     * @returns matched error item or undefined if no match found / найденный элемент ошибки или undefined, если совпадений не найдено
+     */
+    protected findItem(method: ApiMethodItem, response: Response, code?: string): ApiErrorStorageItem | undefined;
+    /**
+     * Validates if the given URL matches the specified pattern.
+     *
+     * Проверяет, соответствует ли данный URL указанному шаблону.
+     * @param url URL to check / URL для проверки
+     * @param pattern URL pattern or RegExp / шаблон URL или регулярное выражение
+     * @returns true if the URL matches the pattern / true, если URL соответствует шаблону
+     */
+    protected isUrl(url: string, pattern: string | RegExp): boolean;
+    /**
+     * Attempts to extract an error code from the response body in JSON format.
+     *
+     * Пытается извлечь код ошибки из тела ответа в формате JSON.
+     * @param response fetch response / Ответ fetch
+     * @returns extracted error code or undefined / извлеченный код ошибки или undefined
+     */
+    protected getBody(response: Response): Promise<any>;
+    protected getDataByKey<R = string>(body: any, key: string): R | undefined;
+    /**
+     * Attempts to extract an error code from the response body in JSON format.
+     *
+     * Пытается извлечь код ошибки из тела ответа в формате JSON.
+     * @param response fetch response / Ответ fetch
+     * @returns extracted error code or undefined / извлеченный код ошибки или undefined
+     */
+    protected getCode(body: any): string | undefined;
+    /**
+     * Attempts to extract an error message from the response body in JSON format.
+     *
+     * Пытается извлечь сообщение об ошибке из тела ответа в формате JSON.
+     * @param body response body / тело ответа
+     * @returns extracted error message or undefined / извлеченное сообщение об ошибке или undefined
+     */
+    protected getMessage(body: any): string | undefined;
+}

package/dist/src/classes/ApiHeaders.d.ts

@@ -1,4 +1,4 @@
-import { ApiFetch } from '../types/apiTypes';
+import { ApiFetch, ApiHeadersValue } from '../types/apiTypes';
 /**
  * Class for managing HTTP request headers.
  *
@@ -6,7 +6,7 @@ import { ApiFetch } from '../types/apiTypes';
  */
 export declare class ApiHeaders {
     /** Default headers / Заголовки по умолчанию */
-    protected headers: Record<string, string>;
+    protected headers: ApiHeadersValue;
     /**
      * Gets the headers for the request.
      *
@@ -33,5 +33,5 @@ export declare class ApiHeaders {
      * @param headers list of default headers/ список заголовков по умолчанию
      * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
      */
-    set(headers: Record<string, string> | (() => Record<string, string>)): this;
+    set(headers: ApiHeadersValue): this;
 }

package/dist/src/classes/ApiInstance.d.ts

@@ -1,12 +1,13 @@
 import { LoadingInstance } from './LoadingInstance';
 import { ErrorCenterInstance } from './ErrorCenterInstance';
 import { ApiDefault } from './ApiDefault';
+import { ApiErrorItem } from './ApiErrorItem';
 import { ApiHeaders } from './ApiHeaders';
 import { ApiHydration } from './ApiHydration';
 import { ApiPreparation } from './ApiPreparation';
-import { ApiStatus } from './ApiStatus';
 import { ApiResponse } from './ApiResponse';
-import { ApiFetch, ApiMethod, ApiPreparationEnd } from '../types/apiTypes';
+import { ApiStatus } from './ApiStatus';
+import { ApiDefaultValue, ApiFetch, ApiHeadersValue, ApiMethod, ApiPreparationEnd } from '../types/apiTypes';
 /** Options for the API instance / Опции для экземпляра API */
 export type ApiInstanceOptions = {
     /** Class for working with headers / Класс для работы с заголовками */
@@ -134,14 +135,14 @@ export declare class ApiInstance {
      * Изменяет данные заголовка по умолчанию.
      * @param headers default headers / заголовки по умолчанию
      */
-    setHeaders(headers: Record<string, string> | (() => Record<string, string>)): this;
+    setHeaders(headers: ApiHeadersValue): this;
     /**
      * Modifies the default request data.
      *
      * Изменяет данные запроса по умолчанию.
      * @param request default request data / данные запроса по умолчанию
      */
-    setRequestDefault(request: Record<string, any>): this;
+    setRequestDefault(request: ApiDefaultValue): this;
     /**
      * Changes the base path to the script.
      *
@@ -268,9 +269,9 @@ export declare class ApiInstance {
      * Processes an error response.
      *
      * Обрабатывает ошибку ответа.
-     * @param query error response / ответ с ошибкой
+     * @param error error details / данные ошибки
      */
-    protected makeErrorQuery(query: Response): void;
+    protected makeErrorQuery(error: ApiErrorItem | Response): void;
     /**
      * Initialize controller for request with timeout support.
      *

package/dist/src/library.d.ts

@@ -2,6 +2,9 @@ export * from './classes/Api';
 export * from './classes/ApiCache';
 export * from './classes/ApiDataReturn';
 export * from './classes/ApiDefault';
+export * from './classes/ApiError';
+export * from './classes/ApiErrorItem';
+export * from './classes/ApiErrorStorage';
 export * from './classes/ApiHeaders';
 export * from './classes/ApiHydration';
 export * from './classes/ApiInstance';

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

@@ -1,3 +1,4 @@
+import { ApiErrorItem } from '../classes/ApiErrorItem';
 /**
  * Supported HTTP methods for API requests.
  * Поддерживаемые HTTP-методы для API-запросов.
@@ -53,9 +54,9 @@ export type ApiConfig = {
     /** Base origin for API requests (protocol and domain)/ Базовый источник для API-запросов (протокол и домен) */
     origin?: string;
     /** Default headers for API requests/ Заголовки по умолчанию для API-запросов */
-    headers?: Record<string, string>;
+    headers?: ApiHeadersValue;
     /** Default request data for API requests/ Данные запроса по умолчанию для API-запросов */
-    requestDefault?: Record<string, any>;
+    requestDefault?: ApiDefaultValue;
     /** Function to call before request/ Функция для вызова перед запросом */
     preparation?: (apiFetch: ApiFetch) => Promise<void>;
     /** Function to call after request/ Функция для вызова после запроса */
@@ -79,6 +80,13 @@ export type ApiDataValidation = {
     code?: string | number;
     /** Message/ Сообщение */
     message?: string;
+    /** Error/ Ошибка */
+    error?: {
+        /** Code / Код */
+        code?: string | number;
+        /** Message/ Сообщение */
+        message?: string;
+    };
 };
 /**
  * Type of API response data item/ Тип элемента данных ответа API
@@ -90,11 +98,17 @@ export type ApiDataItem<T = any> = T & ApiDataValidation & {
     success?: boolean;
     /** Status object/ Объект статуса */
     statusObject?: ApiStatusItem;
+    /** Error object/ Объект ошибки */
+    errorObject?: ApiErrorItem;
 };
+/**
+ * Type for API request headers / Тип для заголовков запроса API
+ */
+export type ApiHeadersValue = Record<string, string> | (() => Record<string, string>);
 /**
  * Default API request data type/ Тип данных запроса API по умолчанию
  */
-export type ApiDefaultValue = Record<string, any>;
+export type ApiDefaultValue = Record<string, any> | (() => Record<string, any>);
 /**
  * Options for making API requests/ Опции для выполнения API-запросов
  */
@@ -137,6 +151,7 @@ export type ApiFetch = {
     globalEnd?: boolean;
     /** Additional fetch() options/ Дополнительные опции fetch() */
     init?: RequestInit;
+    initError?: boolean;
     /** Timeout for the request in milliseconds/ Таймаут запроса в миллисекундах */
     timeout?: number;
     /** AbortController for canceling the request/ AbortController для отмены запроса */
@@ -166,6 +181,27 @@ export type ApiHydrationItem = {
  * List of API hydration items/ Список элементов гидратации API
  */
 export type ApiHydrationList = ApiHydrationItem[];
+/**
+ * Item for API error storage/ Элемент для хранилища ошибок API
+ */
+export type ApiErrorStorageItem = {
+    /** URL string or RegExp to match request URL/ Строка URL или RegExp для сопоставления URL */
+    url: string | RegExp;
+    /** HTTP method/ HTTP метод */
+    method: ApiMethodItem;
+    /** Error code/ Код ошибки */
+    code?: string;
+    /** HTTP status code/ Код статуса HTTP */
+    status?: number;
+    /** Validation function/ Функция валидации */
+    validation?: (response: Response) => boolean;
+    /** Error message or function that returns message/ Сообщение об ошибке или функция, возвращающая сообщение */
+    message?: string | ((response?: Response) => string);
+};
+/**
+ * List of API error storage items/ Список элементов хранилища ошибок API
+ */
+export type ApiErrorStorageList = ApiErrorStorageItem[];
 /**
  * Supported HTTP methods type/ Тип HTTP-методов
  * (derived from ApiMethodItem enum)/ (получен из перечисления ApiMethodItem)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dxtmisha/functional-basic",
   "private": false,
-  "version": "1.2.3",
+  "version": "1.2.5",
   "type": "module",
   "description": "Foundational utility library for modern web development — HTTP client, geolocation, i18n, SEO meta tags, caching, storage, DOM utilities, and more. Framework-agnostic, zero dependencies, TypeScript-first.",
   "keywords": [