@dxtmisha/functional-basic 1.1.5 → 1.1.6

package/dist/classes/ApiInstance.d.ts

@@ -0,0 +1,283 @@
+import { LoadingInstance } from './LoadingInstance';
+import { ErrorCenterInstance } from './ErrorCenterInstance';
+import { ApiDefault } from './ApiDefault';
+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';
+/** Options for the API instance / Опции для экземпляра API */
+export type ApiInstanceOptions = {
+    /** Class for working with headers / Класс для работы с заголовками */
+    headersClass?: typeof ApiHeaders;
+    /** Class for working with default request parameters / Класс для работы с параметрами запроса по умолчанию */
+    requestDefaultClass?: typeof ApiDefault;
+    /** Class for working with status / Класс для работы со статусом */
+    statusClass?: typeof ApiStatus;
+    /** Class for working with response / Класс для работы с ответом */
+    responseClass?: typeof ApiResponse;
+    /** Class for working with preparation / Класс для работы с модификацией запроса */
+    preparationClass?: typeof ApiPreparation;
+    /** Instance of loading handler / Экземпляр обработчика загрузки */
+    loadingClass?: LoadingInstance;
+    /** Instance of error handler / Экземпляр обработчика ошибок */
+    errorCenterClass?: ErrorCenterInstance;
+    /** Class for working with hydration / Класс для работы с гидратацией */
+    hydrationClass?: typeof ApiHydration;
+};
+/**
+ * Core class for managing HTTP requests using the Fetch API.
+ *
+ * Основной класс для управления HTTP-запросами через Fetch API.
+ */
+export declare class ApiInstance {
+    protected url: string;
+    /** Headers / Заголовки */
+    protected headers: ApiHeaders;
+    /** Default request parameters / Параметры запроса по умолчанию */
+    protected requestDefault: ApiDefault;
+    /** Status of the last request / Статус последнего запроса */
+    protected status: ApiStatus;
+    /** Response handler / Обработчик ответа */
+    protected response: ApiResponse;
+    /** Request modification handler / Обработчик модификации запроса */
+    protected preparation: ApiPreparation;
+    /** Loading handler / Обработчик загрузки */
+    protected loading: LoadingInstance;
+    /** Error handler / Обработчик ошибок */
+    protected errorCenter: ErrorCenterInstance;
+    /** Hydration handler / Обработчик гидратации */
+    protected hydration: ApiHydration;
+    /** Timeout for the request in milliseconds / Таймаут запроса в миллисекундах */
+    protected timeout: number;
+    protected origin?: string;
+    /**
+     * Constructor
+     * @param url base path to the script / базовый путь к скрипту
+     * @param options options for the API instance / опции для экземпляра API
+     */
+    constructor(url?: string, options?: ApiInstanceOptions);
+    /**
+     * Checks if the server is running on localhost.
+     *
+     * Проверяет, работает ли сервер на localhost.
+     * @returns true if server is localhost / true, если сервер является локальным
+     */
+    isLocalhost(): boolean;
+    /**
+     * Returns the status of the last request.
+     *
+     * Возвращает статус последнего запроса.
+     * @returns ApiStatus instance / экземпляр ApiStatus
+     */
+    getStatus(): ApiStatus;
+    /**
+     * Gets the response handler.
+     *
+     * Получает обработчик ответа.
+     * @returns ApiResponse instance / экземпляр ApiResponse
+     */
+    getResponse(): ApiResponse;
+    /**
+     * Gets the hydration handler.
+     *
+     * Получает обработчик гидратации.
+     * @returns ApiHydration instance / экземпляр ApiHydration
+     */
+    getHydration(): ApiHydration;
+    /**
+     * Gets the base origin URL combined with the API path.
+     *
+     * Получает базовый URL источника, объединенный с путем API.
+     * @returns final base URL string / итоговая строка базового URL
+     */
+    getOrigin(): string;
+    /**
+     * Gets the full path to the request script.
+     *
+     * Получает полный путь к скрипту запроса.
+     * @param path path to the script / путь к скрипту
+     * @param api whether to prepend base API URL / нужно ли добавить базовый URL API
+     * @returns full URL / полный URL
+     */
+    getUrl(path: string, api?: boolean): string;
+    /**
+     * Gets data for the request body.
+     *
+     * Получает данные для тела запроса.
+     * @param request request data / данные запроса
+     * @param method HTTP method / HTTP метод
+     * @returns body data for non-GET requests or FormData / данные тела для не-GET запросов или FormData
+     */
+    getBody(request?: ApiFetch['request'], method?: ApiMethod): string | FormData | undefined;
+    /**
+     * Gets query string for GET method requests.
+     *
+     * Получает строку запроса для GET-методов.
+     * @param request request data / данные запроса
+     * @param path path to request / путь к запросу
+     * @param method HTTP method / HTTP метод
+     * @returns query string with prefix (? or &) / строка запроса с префиксом (? или &)
+     */
+    getBodyForGet(request: ApiFetch['request'], path?: string, method?: ApiMethod): string;
+    /**
+     * Returns a string representation of the hydration data for the client.
+     *
+     * Возвращает строковое представление данных гидратации для клиента.
+     * @returns HTML script element string / строка HTML элемента script
+     */
+    getHydrationScript(): string;
+    /**
+     * Modifies the default header data.
+     *
+     * Изменяет данные заголовка по умолчанию.
+     * @param headers default headers / заголовки по умолчанию
+     */
+    setHeaders(headers: Record<string, string>): this;
+    /**
+     * Modifies the default request data.
+     *
+     * Изменяет данные запроса по умолчанию.
+     * @param request default request data / данные запроса по умолчанию
+     */
+    setRequestDefault(request: Record<string, any>): this;
+    /**
+     * Changes the base path to the script.
+     *
+     * Изменяет базовый путь к скрипту.
+     * @param url path to the script / путь к скрипту
+     */
+    setUrl(url: string): this;
+    /**
+     * Modifies the function to be called before the request.
+     *
+     * Изменяет функцию для вызова перед запросом.
+     * @param callback function to call before request / функция для вызова перед запросом
+     */
+    setPreparation(callback: (apiFetch: ApiFetch) => Promise<void>): this;
+    /**
+     * Modifies the function to be called after the request.
+     *
+     * Изменяет функцию для вызова после запроса.
+     * @param callback function to call after request / функция для вызова после запроса
+     */
+    setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this;
+    /**
+     * Changes the timeout for the request in milliseconds.
+     *
+     * Изменяет таймаут запроса в миллисекундах.
+     * @param timeout timeout in milliseconds / таймаут в миллисекундах
+     */
+    setTimeout(timeout: number): this;
+    /**
+     * Changes the origin (protocol and domain) for the base URL.
+     *
+     * Изменяет источник (протокол и домен) для базового URL.
+     * @param origin protocol and domain / протокол и домен
+     */
+    setOrigin(origin: string): this;
+    /**
+     * Executes a request with the given path or configuration.
+     *
+     * Выполняет запрос с указанным путем или конфигурацией.
+     * @param pathRequest path or configuration / путь или конфигурация запроса
+     * @returns Promise with response data / Promise с данными ответа
+     */
+    request<T>(pathRequest: string | ApiFetch): Promise<T>;
+    /**
+     * Sends a GET method request.
+     *
+     * Отправляет запрос метода GET.
+     * @param request fetch configuration / конфигурация запроса
+     * @returns Promise with response data / Promise с данными ответа
+     */
+    get<T>(request: ApiFetch): Promise<T>;
+    /**
+     * Sends a POST method request.
+     *
+     * Отправляет запрос метода POST.
+     * @param request fetch configuration / конфигурация запроса
+     * @returns Promise with response data / Promise с данными ответа
+     */
+    post<T>(request: ApiFetch): Promise<T>;
+    /**
+     * Sends a PUT method request.
+     *
+     * Отправляет запрос метода PUT.
+     * @param request fetch configuration / конфигурация запроса
+     * @returns Promise with response data / Promise с данными ответа
+     */
+    put<T>(request: ApiFetch): Promise<T>;
+    /**
+     * Sends a PATCH method request.
+     *
+     * Отправляет запрос метода PATCH.
+     * @param request fetch configuration / конфигурация запроса
+     * @returns Promise with response data / Promise с данными ответа
+     */
+    patch<T>(request: ApiFetch): Promise<T>;
+    /**
+     * Sends a DELETE method request.
+     *
+     * Отправляет запрос метода DELETE.
+     * @param request fetch configuration / конфигурация запроса
+     * @returns Promise with response data / Promise с данными ответа
+     */
+    delete<T>(request: ApiFetch): Promise<T>;
+    /**
+     * Gets retry delay with jitter.
+     *
+     * Получает задержку повтора с джиттером.
+     * @param retryCount count of retries / количество повторов
+     * @param retryDelay base delay between retries / базовая задержка между повторами
+     * @returns delay in milliseconds / задержка в миллисекундах
+     */
+    protected getRetryDelay(retryCount: number, retryDelay: number): number;
+    /**
+     * Execute API request with retry support.
+     *
+     * Выполнить запрос API с поддержкой повторов.
+     * @param apiFetch fetch configuration / конфигурация запроса
+     * @param retryCount current retry count / текущий счетчик повторов
+     */
+    protected fetch<T>(apiFetch: ApiFetch, retryCount?: number): Promise<T>;
+    /**
+     * Executing the HTTP request.
+     *
+     * Выполнение HTTP-запроса.
+     * @param apiFetch fetch configuration / конфигурация запроса
+     * @param pathToApi base path to API / базовый путь к API
+     * @returns object containing response and optional timeout ID / объект, содержащий ответ и опциональный ID таймера
+     */
+    protected makeQuery(apiFetch: ApiFetch, pathToApi: string): Promise<{
+        query: Response;
+        timeoutId: any;
+    }>;
+    /**
+     * Processing an error.
+     *
+     * Обработка ошибки.
+     * @param error error object / объект ошибки
+     * @param group error group for error center (default: 'api') / группа ошибки для центра ошибок (по умолчанию: 'api')
+     */
+    protected makeError(error: Record<string, any> & {
+        name: string;
+    }, group?: string): void;
+    /**
+     * Processes an error response.
+     *
+     * Обрабатывает ошибку ответа.
+     * @param query error response / ответ с ошибкой
+     */
+    protected makeErrorQuery(query: Response): void;
+    /**
+     * Initialize controller for request with timeout support.
+     *
+     * Инициализация контроллера для запроса с поддержкой таймаута.
+     * @param apiFetch request options / опции запроса
+     * @param fetchInit request initialization object / объект инициализации запроса
+     * @returns timeout ID (from setTimeout) or undefined / ID таймера (от setTimeout) или undefined
+     */
+    protected initController(apiFetch: ApiFetch, fetchInit: RequestInit): any;
+}

package/dist/classes/ApiPreparation.d.ts

@@ -0,0 +1,58 @@
+import { ApiFetch, ApiPreparationEnd } from '../types/apiTypes';
+/**
+ * Class for preparing requests.
+ *
+ * Класс для подготовки запросов.
+ */
+export declare class ApiPreparation {
+    /** Function for call before the request / Функция для вызова перед запросом */
+    protected callback?: (apiFetch: ApiFetch) => Promise<void>;
+    /** Function for call after the request / Функция для вызова после запроса */
+    protected callbackEnd?: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>;
+    /** Is the preparation in progress / Идет ли подготовка */
+    protected loading: boolean;
+    /**
+     * Executes preparation before the request.
+     *
+     * Выполняет подготовку перед выполнением запроса.
+     * @param active is preparation active / активна ли подготовка
+     * @param apiFetch request options / опции запроса
+     * @returns Promise<void> / Promise без возвращаемого значения
+     */
+    make(active: boolean, apiFetch: ApiFetch): Promise<void>;
+    /**
+     * Analyzes the request after execution.
+     *
+     * Анализирует запрос после выполнения.
+     * @param active is preparation active / активна ли подготовка
+     * @param query data received in the request / данные, полученные в запросе
+     * @param apiFetch request options / опции запроса
+     * @returns preparation end data / данные завершения подготовки
+     */
+    makeEnd(active: boolean, query: Response, apiFetch: ApiFetch): Promise<ApiPreparationEnd>;
+    /**
+     * Modifies the function to be called before the request.
+     *
+     * Изменяет функцию для вызова перед запросом.
+     * @param callback function to call before request / функция для вызова перед запросом
+     * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
+     */
+    set(callback: (apiFetch: ApiFetch) => Promise<void>): this;
+    /**
+     * Modifies the function to be called after the request.
+     *
+     * Изменяет функцию для вызова после запроса.
+     * @param callback function to call after request / функция для вызова после запроса
+     * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
+     */
+    setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this;
+    /**
+     * To execute preparation.
+     *
+     * Выполнить подготовку.
+     * @param apiFetch request options / опции запроса
+     * @param limit limit of retry attempts / лимит попыток повтора
+     * @returns Promise<void> / Promise без возвращаемого значения
+     */
+    protected go(apiFetch: ApiFetch, limit?: number): Promise<void>;
+}

package/dist/classes/ApiResponse.d.ts

@@ -0,0 +1,154 @@
+import { ApiDefault } from './ApiDefault';
+import { ApiFetch, ApiMethod, ApiResponseItem } from '../types/apiTypes';
+/**
+ * Class for working with API responses.
+ *
+ * Класс для работы с ответами API.
+ */
+export declare class ApiResponse {
+    protected readonly requestDefault: ApiDefault;
+    /** List of first-time API requests / Список первичных API запросов */
+    protected readonly first: ApiResponseItem[];
+    /** Cached responses / Кешированные ответы */
+    protected readonly response: ApiResponseItem[];
+    /** Loading instance / Экземпляр загрузки */
+    protected loading?: any;
+    /** Developer mode flag / Флаг режима разработчика */
+    protected devMode: boolean;
+    /**
+     * Constructor
+     * @param requestDefault default request class/ класс запросов по умолчанию
+     */
+    constructor(requestDefault: ApiDefault);
+    /**
+     * Checks if there is a global cached request, if there is, returns it.
+     *
+     * Проверяет, есть ли глобальный кешированный запрос, если есть, возвращает его.
+     * @param path link to the request / ссылка на запрос
+     * @param method request method / метод запроса
+     * @param request data for the request / данные для запроса
+     * @param devMode optional developer mode flag / необязательный флаг режима разработчика
+     * @returns cached response item or undefined / кешированный элемент ответа или undefined
+     */
+    get(path: string | undefined, method: ApiMethod, request?: ApiFetch['request'], devMode?: boolean): ApiResponseItem | undefined;
+    /**
+     * Returns a list of cached API responses (excluding global responses).
+     *
+     * Возвращает список кешированных ответов API (исключая глобальные ответы).
+     */
+    getList(): (ApiResponseItem & Record<string, any>)[];
+    /**
+     * Adds cached requests.
+     *
+     * Добавляет кешированные запросы.
+     * @param response data for caching / данные для кеширования
+     */
+    add(response: ApiResponseItem | ApiResponseItem[]): this;
+    /**
+     * Sets developer mode.
+     *
+     * Устанавливает режим разработчика.
+     * @param devMode is it developer mode / является ли режим разработчика
+     * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
+     */
+    setDevMode(devMode: boolean): this;
+    /**
+     * Executes the emulator if available.
+     *
+     * Выполняет эмулятор, если доступно.
+     * @param apiFetch fetch configuration / конфигурация запроса
+     * @returns emulated response or undefined / эмулированный ответ или undefined
+     */
+    emulator<T>(apiFetch: ApiFetch): Promise<T | undefined>;
+    /**
+     * Executes the emulator synchronously if available.
+     *
+     * Выполняет эмулятор синхронно, если доступно.
+     * @param apiFetch fetch configuration / конфигурация запроса
+     * @returns emulated response or undefined / эмулированный ответ или undefined
+     */
+    emulatorAsync<T>(apiFetch: ApiFetch): T | undefined;
+    /**
+     * Checks if the cached item is disabled.
+     *
+     * Проверяет, отключен ли кешированный элемент.
+     * @param item cached item / кешированный элемент
+     * @returns true if item is disabled / true, если элемент отключен
+     */
+    protected isDisable(item: ApiResponseItem): boolean;
+    /**
+     * Checks if the path matches the cached one.
+     *
+     * Проверяет, совпадает ли путь с кешированным.
+     * @param item cached item / кешированный элемент
+     * @param path request path / путь запроса
+     * @returns true if paths match / true, если пути совпадают
+     */
+    protected isPath(item: ApiResponseItem, path: string): boolean;
+    /**
+     * Checks if it is developer mode.
+     *
+     * Проверяет, является ли режимом разработчика.
+     * @param devMode is it developer mode / является ли режим разработчика
+     * @returns true if in dev mode / true, если в режиме разработчика
+     */
+    protected isDevMode(devMode?: boolean): boolean;
+    /**
+     * Checks if this is the first request.
+     *
+     * Проверяет, является ли это первым запросом.
+     * @param item cached item / кешированный элемент
+     * @param devMode is it developer mode / является ли режим разработчика
+     * @returns true if this is the first request / true, если это первый запрос
+     */
+    protected isFirst(item: ApiResponseItem, devMode?: boolean): boolean;
+    /**
+     * Checks if the request matches the cached one.
+     *
+     * Проверяет, совпадает ли запрос с кешированным.
+     * @param item cached item / кешированный элемент
+     * @param request request data / данные запроса
+     * @returns true if requests match / true, если запросы совпадают
+     */
+    protected isResponse(item: ApiResponseItem, request?: ApiFetch['request']): boolean;
+    /**
+     * Reads cached data configuration.
+     *
+     * Считывает конфигурацию кешированных данных.
+     * @param apiFetch fetch configuration / конфигурация запроса
+     * @returns object with response and request data or undefined / объект с данными ответа и запроса или undefined
+     */
+    protected readData(apiFetch: ApiFetch): {
+        response: ApiResponseItem;
+        request: string | Record<string, any> | FormData | undefined;
+    } | undefined;
+    /**
+     * Emulates an execution request (internal fetch).
+     *
+     * Эмулирует запрос выполнения (внутренний fetch).
+     * @param response response item for emulation / элемент ответа для эмуляции
+     * @param request data for the request / данные для запроса
+     * @returns Promise with emulated response data / Promise с эмулированными данными ответа
+     */
+    protected fetch<T>(response: ApiResponseItem, request?: ApiFetch['request']): Promise<T>;
+    /**
+     * Emulates an execution request synchronously (internal fetch).
+     *
+     * Эмулирует запрос выполнения синхронно (внутренний fetch).
+     * @param response response item for emulation / элемент ответа для эмуляции
+     * @returns emulated response data / эмулированные данные ответа
+     */
+    protected fetchAsync<T>(response: ApiResponseItem): T;
+    /**
+     * Enables loading for request emulation.
+     *
+     * Включает загрузку для эмуляции запроса.
+     */
+    protected startResponseLoading(): void;
+    /**
+     * Disables loading for request emulation.
+     *
+     * Отключает загрузку для эмуляции запроса.
+     */
+    protected stopResponseLoading(): void;
+}

package/dist/classes/ApiStatus.d.ts

@@ -0,0 +1,130 @@
+import { ApiStatusItem, ApiStatusType } from '../types/apiTypes';
+/**
+ * Class for managing API request status.
+ *
+ * Класс для управления статусом запросов API.
+ */
+export declare class ApiStatus {
+    protected value?: ApiStatusItem;
+    /**
+     * Returns the last status item data.
+     *
+     * Возвращает данные последнего элемента статуса.
+     * @returns status item or undefined / элемент статуса или undefined
+     */
+    get(): ApiStatusItem | undefined;
+    /**
+     * Returns the execution status code.
+     *
+     * Возвращает код статуса выполнения.
+     * @returns HTTP status code or undefined / код статуса HTTP или undefined
+     */
+    getStatus(): number | undefined;
+    /**
+     * Returns the execution status text.
+     *
+     * Возвращает текст статуса выполнения.
+     * @returns status text or undefined / текст статуса или undefined
+     */
+    getStatusText(): string | undefined;
+    /**
+     * Returns the last status type.
+     *
+     * Возвращает последний тип статуса.
+     * @returns status type or undefined / тип статуса или undefined
+     */
+    getStatusType(): ApiStatusType | undefined;
+    /**
+     * Returns the execution status code (string or number from response).
+     *
+     * Возвращает код статуса выполнения (строка или число из ответа).
+     * @returns status code or undefined / код статуса или undefined
+     */
+    getCode(): string | undefined;
+    /**
+     * Returns the script execution error.
+     *
+     * Возвращает ошибку выполнения скрипта.
+     * @returns error message or undefined / сообщение об ошибке или undefined
+     */
+    getError(): string | undefined;
+    /**
+     * Returns the data of the last request.
+     *
+     * Возвращает данные последнего запроса.
+     * @returns last response data or undefined / данные последнего ответа или undefined
+     */
+    getResponse<T>(): T | undefined;
+    /**
+     * Returns messages from the last request.
+     *
+     * Возвращает сообщения от последнего запроса.
+     * @returns message string / строка сообщения
+     */
+    getMessage(): string;
+    /**
+     * Sets the status item data.
+     *
+     * Устанавливает данные элемента статуса.
+     * @param data status item data/ данные элемента статуса
+     * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
+     */
+    set(data: ApiStatusItem): this;
+    /**
+     * Sets the status code and optional status text.
+     *
+     * Устанавливает код статуса и необязательный текст статуса.
+     * @param status status code / код статуса
+     * @param statusText optional status text / необязательный текст статуса
+     * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
+     */
+    setStatus(status?: number, statusText?: string): this;
+    /**
+     * Sets the error message.
+     *
+     * Устанавливает сообщение об ошибке.
+     * @param error error message/ сообщение об ошибке
+     * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
+     */
+    setError(error?: string): this;
+    /**
+     * Sets the data of the last response and automatically extracts status/message if it's an object.
+     *
+     * Устанавливает данные последнего ответа и автоматически извлекает статус / сообщение, если это объект.
+     * @param response response data / данные ответа
+     * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
+     */
+    setLastResponse(response?: any): this;
+    /**
+     * Sets the last status.
+     *
+     * Устанавливает последний статус.
+     * @param status status/ статус
+     * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
+     */
+    setLastStatus(status?: ApiStatusType): this;
+    /**
+     * Sets the last execution code.
+     *
+     * Устанавливает последний код выполнения.
+     * @param code status code / код статуса
+     * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
+     */
+    setLastCode(code?: string): this;
+    /**
+     * Sets messages from the last request.
+     *
+     * Устанавливает сообщения от последнего запроса.
+     * @param message message text/ текст сообщения
+     * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
+     */
+    setLastMessage(message?: string): this;
+    /**
+     * Sets a specific field in the status item.
+     *
+     * Устанавливает конкретное поле в элементе статуса.
+     * @param name field name/ название поля
+     * @param value field value/ значение поля
+     */
+    protected setValue<K extends keyof ApiStatusItem>(name: K, value?: ApiStatusItem[K]): void;
+}