@dxtmisha/functional-basic 1.1.0 → 1.1.6

package/dist/classes/Api.d.ts

@@ -0,0 +1,201 @@
+import { ApiInstance } from './ApiInstance';
+import { ApiConfig, ApiFetch, ApiMethodItem, ApiPreparationEnd } from '../types/apiTypes';
+import { ApiStatus } from './ApiStatus';
+import { ApiResponse } from './ApiResponse';
+import { ApiHydration } from './ApiHydration';
+/**
+ * Class for working with HTTP requests.
+ *
+ * Класс для работы с HTTP-запросами.
+ */
+export declare class Api {
+    /**
+     * Checks if the server is running on localhost.
+     *
+     * Проверяет, работает ли сервер на localhost.
+     * @returns true if server is localhost / true, если сервер является локальным
+     */
+    static isLocalhost(): boolean;
+    /**
+     * Returns the singleton instance of the ApiInstance class.
+     *
+     * Возвращает синглтон-экземпляр класса ApiInstance.
+     * @returns ApiInstance singleton / синглтон ApiInstance
+     */
+    static getItem(): ApiInstance;
+    /**
+     * Returns the status of the last request.
+     *
+     * Возвращает статус последнего запроса.
+     * @returns ApiStatus instance / экземпляр ApiStatus
+     */
+    static getStatus(): ApiStatus;
+    /**
+     * Gets the response handler.
+     *
+     * Получает обработчик ответа.
+     * @returns ApiResponse instance / экземпляр ApiResponse
+     */
+    static getResponse(): ApiResponse;
+    /**
+     * Gets the hydration handler.
+     *
+     * Получает обработчик гидратации.
+     * @returns ApiHydration instance / экземпляр ApiHydration
+     */
+    static getHydration(): ApiHydration;
+    /**
+     * Returns a string representation of the hydration data for the client.
+     *
+     * Возвращает строковое представление данных гидратации для клиента.
+     * @returns HTML script element string / строка HTML элемента script
+     */
+    static getHydrationScript(): string;
+    /**
+     * Gets the base origin URL combined with the API path.
+     *
+     * Получает базовый URL источника, объединенный с путем API.
+     * @returns final base URL string / итоговая строка базового URL
+     */
+    static 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
+     */
+    static 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
+     */
+    static getBody(request?: ApiFetch['request'], method?: ApiMethodItem): 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 for GET requests / строка запроса для GET-запросов
+     */
+    static getBodyForGet(request: ApiFetch['request'], path?: string, method?: ApiMethodItem): string;
+    /**
+     * Modifies the default header data.
+     *
+     * Изменяет данные заголовка по умолчанию.
+     * @param headers default headers / заголовки по умолчанию
+     * @returns void / ничего не возвращает
+     */
+    static setHeaders(headers: Record<string, string>): void;
+    /**
+     * Modifies the default request data.
+     *
+     * Изменяет данные запроса по умолчанию.
+     * @param request default request data / данные запроса по умолчанию
+     * @returns void / ничего не возвращает
+     */
+    static setRequestDefault(request: Record<string, any>): void;
+    /**
+     * Changes the base path to the script.
+     *
+     * Изменяет базовый путь к скрипту.
+     * @param url path to the script / путь к скрипту
+     * @returns void / ничего не возвращает
+     */
+    static setUrl(url: string): void;
+    /**
+     * Modifies the function to be called before the request.
+     *
+     * Изменяет функцию для вызова перед запросом.
+     * @param callback function to call before request / функция для вызова перед запросом
+     * @returns void / ничего не возвращает
+     */
+    static setPreparation(callback: (apiFetch: ApiFetch) => Promise<void>): void;
+    /**
+     * Modifies the function to be called after the request.
+     *
+     * Изменяет функцию для вызова после запроса.
+     * @param callback function to call after request / функция для вызова после запроса
+     * @returns void / ничего не возвращает
+     */
+    static setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): void;
+    /**
+     * Changes the timeout for the request in milliseconds.
+     *
+     * Изменяет таймаут запроса в миллисекундах.
+     * @param timeout timeout in milliseconds / таймаут в миллисекундах
+     * @returns void / ничего не возвращает
+     */
+    static setTimeout(timeout: number): void;
+    /**
+     * Changes the origin (protocol and domain) for the base URL.
+     *
+     * Изменяет источник (протокол и домен) для базового URL.
+     * @param origin protocol and domain / протокол и домен
+     * @returns void / ничего не возвращает
+     */
+    static setOrigin(origin: string): void;
+    /**
+     * Sets multiple API configuration options at once.
+     *
+     * Устанавливает несколько опций конфигурации API одновременно.
+     * @param config configuration object / объект конфигурации
+     * @returns void / ничего не возвращает
+     */
+    static setConfig(config?: ApiConfig): void;
+    /**
+     * Executes a request with the given path or configuration.
+     *
+     * Выполняет запрос с указанным путем или конфигурацией.
+     * @param pathRequest path or configuration / путь или конфигурация запроса
+     * @returns Promise with response data / Promise с данными ответа
+     */
+    static request<T>(pathRequest: string | ApiFetch): Promise<T>;
+    /**
+     * Sends a GET method request.
+     *
+     * Отправляет запрос метода GET.
+     * @param request fetch configuration / конфигурация запроса
+     * @returns Promise with response data / Promise с данными ответа
+     */
+    static get<T>(request: ApiFetch): Promise<T>;
+    /**
+     * Sends a POST method request.
+     *
+     * Отправляет запрос метода POST.
+     * @param request fetch configuration / конфигурация запроса
+     * @returns Promise with response data / Promise с данными ответа
+     */
+    static post<T>(request: ApiFetch): Promise<T>;
+    /**
+     * Sends a PUT method request.
+     *
+     * Отправляет запрос метода PUT.
+     * @param request fetch configuration / конфигурация запроса
+     * @returns Promise with response data / Promise с данными ответа
+     */
+    static put<T>(request: ApiFetch): Promise<T>;
+    /**
+     * Sends a PATCH method request.
+     *
+     * Отправляет запрос метода PATCH.
+     * @param request fetch configuration / конфигурация запроса
+     * @returns Promise with response data / Promise с данными ответа
+     */
+    static patch<T>(request: ApiFetch): Promise<T>;
+    /**
+     * Sends a DELETE method request.
+     *
+     * Отправляет запрос метода DELETE.
+     * @param request fetch configuration / конфигурация запроса
+     * @returns Promise with response data / Promise с данными ответа
+     */
+    static delete<T>(request: ApiFetch): Promise<T>;
+}

package/dist/classes/ApiCache.d.ts

@@ -0,0 +1,152 @@
+import { ApiCacheItem, ApiCacheList, ApiFetch } from '../types/apiTypes';
+/**
+ * Class for caching API responses.
+ *
+ * Класс для кэширования ответов API.
+ */
+export declare class ApiCache {
+    /** Cache storage / Кэш-хранилища */
+    protected static items?: ApiCacheList;
+    /** Storage mechanism for getting data / механизм хранения для получения данных */
+    protected static getListener?: (key: string) => Promise<ApiCacheItem | undefined>;
+    /** Storage mechanism for setting data / механизм хранения для сохранения данных */
+    protected static setListener?: (key: string, value: ApiCacheItem) => Promise<boolean>;
+    /** Storage mechanism for removing data / механизм хранения для удаления данных */
+    protected static removeListener?: (key: string) => Promise<boolean>;
+    /**
+     * Number of data retrieval requests before starting the cleaning of old cache/
+     * Количество запросов получения данных перед началом очистки старого кэша
+     */
+    protected static cacheStepAgeClearOld: number;
+    /** Number of data retrieval requests before starting the cleaning of old cache / Количество запросов получения данных перед началом очистки старого кэша */
+    protected static stepAgeClearOld: number;
+    /**
+     * Initializes the storage with listeners.
+     *
+     * Инициализирует хранилище слушателями.
+     * @param getListener Storage mechanism for getting data / механизм хранения для получения данных
+     * @param setListener Storage mechanism for setting data / механизм хранения для сохранения данных
+     * @param removeListener Storage mechanism for removing data / механизм хранения для удаления данных
+     * @param cacheStepAgeClearOld Number of data retrieval requests before starting the cleaning of old cache / количество запросов получения данных перед началом очистки старого кэша
+     */
+    static init(getListener: (key: string) => Promise<ApiCacheItem | undefined>, setListener: (key: string, value: ApiCacheItem) => Promise<boolean>, removeListener: (key: string) => Promise<boolean>, cacheStepAgeClearOld?: number): void;
+    /**
+     * Resets the cache by clearing all in-memory items and resetting listeners.
+     *
+     * Сбрасывает кэш, очищая все элементы в памяти и сбрасывая слушатели.
+     * @returns void / ничего не возвращает
+     */
+    static reset(): void;
+    /**
+     * Gets data from cache.
+     *
+     * Получает данные из кэша.
+     * @param key cache key / ключ кэша
+     * @returns T | undefined / данные из кэша или undefined
+     */
+    static get<T>(key: string): Promise<T | undefined>;
+    /**
+     * Gets data from cache using fetch options.
+     *
+     * Получает данные из кэша с использованием опций fetch.
+     * @param fetch fetch options / опции fetch
+     * @returns T | undefined / данные из кэша или undefined
+     */
+    static getByFetch<T>(fetch: ApiFetch): Promise<T | undefined>;
+    /**
+     * Saves data to cache.
+     *
+     * Сохраняет данные в кэш.
+     * @param key cache key / ключ кэша
+     * @param value data to be stored / данные для хранения
+     * @param age cache age in seconds / возраст кэша в секундах
+     */
+    static set<T>(key: string, value: T, age?: number): Promise<void>;
+    /**
+     * Saves data to cache using fetch options.
+     *
+     * Сохраняет данные в кэш с использованием опций fetch.
+     * @param fetch fetch options / опции fetch
+     * @param value data to be stored / данные для хранения
+     * @returns Promise<void> / Promise без возвращаемого значения
+     */
+    static setByFetch<T>(fetch: ApiFetch, value: T): Promise<void>;
+    /**
+     * Removes data from cache.
+     *
+     * Удаляет данные из кэша.
+     * @param key cache key / ключ кэша
+     * @returns Promise<void> / Promise без возвращаемого значения
+     */
+    static remove(key: string): Promise<void>;
+    /**
+     * Checks if the cache is enabled.
+     *
+     * Проверяет, включен ли кэш.
+     * @param fetch fetch options / опции fetch
+     * @returns true if cache is enabled / true, если кэш включен
+     */
+    protected static isCache(fetch: ApiFetch): boolean;
+    /**
+     * Checks if cache item is still valid (not expired).
+     *
+     * Проверяет, действителен ли элемент кэша (не истек ли срок действия).
+     * @param item cache item / элемент кэша
+     */
+    protected static isAge(item?: ApiCacheItem): boolean;
+    /**
+     * Checks if the key exists in the cache.
+     *
+     * Проверяет, существует ли ключ в кэше.
+     * @param key cache key / ключ кэша
+     * @returns true if key exists / true, если ключ существует
+     */
+    protected static isItem(key: string): boolean;
+    /**
+     * Generates cache key from fetch options.
+     *
+     * Генерирует ключ кэша из опций fetch.
+     * @param fetch fetch options / опции fetch
+     * @returns cache key string / строка ключа кэша (JSON.stringify)
+     */
+    protected static generateKey(fetch: ApiFetch): string;
+    /**
+     * Gets data from cache using listener.
+     *
+     * Получает данные из кэша с использованием слушателя.
+     * @param key cache key / ключ кэша
+     * @returns cache item or undefined / элемент кэша или undefined (если не существует или истек срок действия)
+     */
+    protected static getItemOrListener(key: string): Promise<ApiCacheItem | undefined>;
+    /**
+     * Gets list of cache items.
+     *
+     * Получает список элементов кэша.
+     * @returns list of cache items / список элементов кэша
+     */
+    protected static getList(): ApiCacheList;
+    /**
+     * Saves data to cache using listener.
+     *
+     * Сохраняет данные в кэш с использованием слушателя.
+     * @param key cache key / ключ кэша
+     * @param value data to be stored / данные для хранения
+     * @returns Promise<void>
+     */
+    protected static setItemOrListener(key: string, value: ApiCacheItem): Promise<void>;
+    /**
+     * Removes data from cache using listener.
+     *
+     * Удаляет данные из кэша с использованием слушателя.
+     * @param key cache key / ключ кэша
+     * @returns Promise<void>
+     */
+    protected static removeItemOrListener(key: string): Promise<void>;
+    /**
+     * Clears old in-memory cache data.
+     *
+     * Очищает старый кэш в памяти.
+     * @returns Promise<void> / Promise без возвращаемого значения (удаляет устаревшие элементы из кэша)
+     */
+    protected static clearOld(): Promise<void>;
+}

package/dist/classes/ApiDataReturn.d.ts

@@ -0,0 +1,76 @@
+import { ApiStatus } from './ApiStatus';
+import { ApiData, ApiFetch, ApiPreparationEnd } from '../types/apiTypes';
+/**
+ * Class for handling and processing data returned from an API request.
+ *
+ * Класс для обработки и подготовки данных, полученных в результате запроса к API.
+ */
+export declare class ApiDataReturn<T = any> {
+    protected readonly apiFetch: ApiFetch;
+    protected readonly query: Response;
+    protected readonly end: ApiPreparationEnd;
+    /**
+     * Raw data received from the API/
+     * Исходные данные, полученные от API
+     */
+    protected data?: ApiData<T>;
+    /**
+     * Processed data ready for use/
+     * Обработанные данные, готовые к использованию
+     */
+    protected dataMod?: ApiData<T>;
+    /**
+     * Constructor for ApiDataReturn.
+     *
+     * Конструктор ApiDataReturn.
+     * @param apiFetch API fetch configuration / конфигурация запроса API
+     * @param query response object / объект ответа
+     * @param end preparation end data / данные завершения подготовки
+     */
+    constructor(apiFetch: ApiFetch, query: Response, end: ApiPreparationEnd);
+    /**
+     * Initializes the class by reading data from the response.
+     *
+     * Инициализирует класс, считывая данные из ответа.
+     */
+    init(): Promise<this>;
+    /**
+     * Returns processed data.
+     *
+     * Возвращает обработанные данные.
+     */
+    get(): ApiData<T>;
+    /**
+     * Returns processed data along with the status object.
+     *
+     * Возвращает обработанные данные вместе с объектом статуса.
+     * @param status API status instance / экземпляр статуса API
+     */
+    getAndStatus(status: ApiStatus): ApiData<T>;
+    /**
+     * Returns raw data received from the API.
+     *
+     * Возвращает исходные данные, полученные от API.
+     */
+    getData(): ApiData<T> | undefined;
+    /**
+     * Reads and parses data from the response.
+     *
+     * Считывает и анализирует данные из ответа.
+     */
+    protected readData<T>(): Promise<ApiData<T>>;
+    /**
+     * Prepares and formats the raw data.
+     *
+     * Подготавливает и форматирует исходные данные.
+     */
+    protected initData(): ApiData<T>;
+    /**
+     * Initializes the result item and merges metadata (success, status, code, message) from raw data.
+     *
+     * Инициализирует результирующий объект и переносит метаданные (success, status, code, message) из исходных данных.
+     * @param data raw response data / исходные данные ответа
+     * @returns initialized data with metadata / инициализированные данные с метаданными
+     */
+    protected initItem(data: Record<string, any>): ApiData<T>;
+}

package/dist/classes/ApiDefault.d.ts

@@ -0,0 +1,49 @@
+import { ApiDefaultValue, ApiFetch } from '../types/apiTypes';
+/**
+ * Class for working with default API request data.
+ *
+ * Класс для работы с данными запроса API по умолчанию.
+ */
+export declare class ApiDefault {
+    /** Default request data / Данные запроса по умолчанию */
+    protected value?: ApiDefaultValue;
+    /**
+     * Checks if default request data exists.
+     *
+     * Проверяет, существуют ли данные запроса по умолчанию.
+     * @returns true if default data exists / true, если данные по умолчанию существуют
+     */
+    is(): boolean;
+    /**
+     * Gets the default request data.
+     *
+     * Получает данные запроса по умолчанию.
+     * @returns default request data or undefined / данные запроса по умолчанию или undefined
+     */
+    get(): ApiDefaultValue | undefined;
+    /**
+     * Adds default data to the request.
+     *
+     * Добавляет данные по умолчанию к запросу.
+     * @param request request data / данные запроса
+     * @returns merged request data / объединенные данные запроса
+     */
+    request(request: ApiFetch['request']): ApiFetch['request'];
+    /**
+     * Sets the default request data.
+     *
+     * Устанавливает данные запроса по умолчанию.
+     * @param request default request data / данные запроса по умолчанию
+     * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
+     */
+    set(request: ApiDefaultValue): this;
+    /**
+     * Adds default data to FormData request.
+     *
+     * Добавляет данные по умолчанию к запросу FormData.
+     * @param request FormData request / запрос FormData
+     * @param value default values / значения по умолчанию
+     * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
+     */
+    protected addByFormData(request: FormData, value: ApiDefaultValue): this;
+}

package/dist/classes/ApiHeaders.d.ts

@@ -0,0 +1,37 @@
+import { ApiFetch } from '../types/apiTypes';
+/**
+ * Class for managing HTTP request headers.
+ *
+ * Класс для управления заголовками HTTP-запросов.
+ */
+export declare class ApiHeaders {
+    /** Default headers / Заголовки по умолчанию */
+    protected headers: Record<string, string>;
+    /**
+     * Gets the headers for the request.
+     *
+     * Получает заголовки для запроса.
+     * @param value list of headers / список заголовков
+     * @param type Content-Type header value / значение заголовка Content-Type
+     * @returns merged headers or undefined / объединенные заголовки или undefined
+     */
+    get(value?: Record<string, string> | null, type?: string | undefined | null): Record<string, string> | undefined;
+    /**
+     * Gets the headers for the request based on request type.
+     *
+     * Получает заголовки для запроса на основе типа запроса.
+     * @param request request data / данные запроса
+     * @param value list of headers / список заголовков
+     * @param type Content-Type header value / значение заголовка Content-Type
+     * @returns merged headers or undefined / объединенные заголовки или undefined
+     */
+    getByRequest(request: ApiFetch['request'], value?: Record<string, string> | null, type?: string): Record<string, string> | undefined;
+    /**
+     * Sets the default headers.
+     *
+     * Устанавливает заголовки по умолчанию.
+     * @param headers list of default headers/ список заголовков по умолчанию
+     * @returns this instance for chaining / текущий экземпляр для цепочки вызовов
+     */
+    set(headers: Record<string, string>): this;
+}

package/dist/classes/ApiHydration.d.ts

@@ -0,0 +1,39 @@
+import { ApiResponse } from './ApiResponse';
+import { ApiFetch, ApiHydrationList } from '../types/apiTypes';
+/**
+ * Class for collecting API data for hydration on the client side during SSR.
+ *
+ * Класс для сбора данных API для последующей гидратации на стороне клиента при SSR.
+ */
+export declare class ApiHydration {
+    protected list: ApiHydrationList;
+    /**
+     * Initializes the response with hydration data.
+     *
+     * Инициализирует ответ данными гидратации.
+     * @param response API response / ответ API
+     * @returns void / ничего не возвращает
+     */
+    initResponse(response: ApiResponse): void;
+    /**
+     * Saves API response for client-side hydration.
+     *
+     * Сохраняет ответ API для гидратации на стороне клиента.
+     * @param apiFetch API request configuration / конфигурация запроса API
+     * @param response API response data / данные ответа API
+     * @returns void / ничего не возвращает
+     */
+    toClient<T>(apiFetch: ApiFetch, response: T): void;
+    /**
+     * Returns a string representation of the hydration data for the client.
+     *
+     * Возвращает строковое представление данных гидратации для клиента.
+     */
+    toString(): string;
+    /**
+     * Returns the list of API responses for the client.
+     *
+     * Возвращает список ответов API для клиента.
+     */
+    protected getListByClient(): ApiHydrationList;
+}