@dxtmisha/wiki 0.39.7 → 0.56.0

package/src/media/functional/functional-basic/classes/ApiInstance/ApiInstance.en.mdx

@@ -10,11 +10,13 @@ It includes tight integration with dependency classes: `ApiStatus`, `ApiResponse
 
 ## Key Features
 
-- **CRUD Methods** — convenient aliases `get`, `post`, `put`, `delete` for handling HTTP requests
+- **CRUD Methods** — convenient aliases `get`, `post`, `put`, `patch`, `delete` for handling HTTP requests
 - **Global Configuration** — setting base URL, default headers, and parameters for all requests
 - **Lifecycle Hooks** — ability to set custom callback functions executed before (`setPreparation`) and after (`setEnd`) each request
 - **Status Tracking** — access to the status and errors of the last request via `ApiStatus`
-- **Caching & Emulation** — managing mock responses and caching via `ApiResponse`
+- **Hydration** — transferring data from server to client (SSR) for instant rendering
+- **Caching** — saving responses in internal or external storage via `ApiCache`
+- **Response Emulation** — flexible management of mock data via `ApiResponse`
 - **Automatic Parsing** — converting the request body into JSON/FormData and automatically extracting data from JSON responses
 - **Geolocation** — automatic substitution of `{locale}`, `{country}`, `{language}` placeholders into request paths
 
@@ -35,10 +37,13 @@ The `ApiInstance` can be configured during initialization with custom dependency
 - `preparationClass?: typeof ApiPreparation` — class for lifecycle hook management.
 - `loadingClass?: LoadingInstance` — instance of the loading indicator manager (defaults to `Loading.getItem()`).
 - `errorCenterClass?: ErrorCenterInstance` — instance of the error center for triggering events (defaults to `ErrorCenter.getItem()`).
+- `hydrationClass?: typeof ApiHydration` — class for SSR hydration management.
 
-## API Calling Methods
+## Methods
 
-### `request`
+### Action
+
+#### `request`
 
 Core executor sequence method managing pure physical network fetch pipelines. Should a solitary string serve as param context, default `GET` assumptions trigger automatically.
 In case of network failures (e.g., 500 status), the method explicitly throws an exception (`throw e`), allowing errors to be natively intercepted in `try/catch`. If the server returns a JSON object, the system automatically injects a `statusObject` field (instance of request status) to the returned payload.
@@ -48,49 +53,21 @@ In case of network failures (e.g., 500 status), the method explicitly throws an
 
 **Returns:** `Promise<ApiData<T>>` — decoded endpoint structural response formatted interface (including `data`, `statusObject`, etc., when returning an object payload).
 
-### `get`
-
-Dispatches a basic query through HTTP `GET` methodologies natively optimizing inputs payload onto string search parameters formats automatically.
-
-**Parameters:**
-- `request: ApiFetch` — fetch execution configuration property mapping (`path`, `request` body, and so on).
-
-**Returns:** `Promise<T>`
-
-### `post`
+### Shorthand
 
-Transfers query packets across standard REST/GraphQL pipelines formatted onto the HTTP `POST` specification.
+- `get(request: ApiFetch): Promise<T>` — Dispatches a basic query through HTTP `GET` methodologies natively optimizing inputs payload onto string search parameters formats automatically.
+- `post(request: ApiFetch): Promise<T>` — Transfers query packets across standard REST/GraphQL pipelines formatted onto the HTTP `POST` specification.
+- `put(request: ApiFetch): Promise<T>` — Directs object modifications over target remote points using typical system environment HTTP `PUT`.
+- `patch(request: ApiFetch): Promise<T>` — Initiates partial resource updates using the standard HTTP `PATCH` method.
+- `delete(request: ApiFetch): Promise<T>` — Forwards structural clearance/purge request using classic URL targeted HTTP `DELETE`.
 
-**Parameters:**
-- `request: ApiFetch` — parameters interface structure container including URL pointing directives.
-
-**Returns:** `Promise<T>`
-
-### `put`
-
-Directs object modifications over target remote points using typical system environment HTTP `PUT`.
-
-**Parameters:**
-- `request: ApiFetch` — query options mapped against backend routing.
-
-**Returns:** `Promise<T>`
-
-### `delete`
-
-Forwards structural clearance/purge request using classic URL targeted HTTP `DELETE`.
-
-**Parameters:**
-- `request: ApiFetch` — arguments package structure wrapper.
-
-**Returns:** `Promise<T>`
-
-## Instance Retrieval Methods
+### Check
 
 - `isLocalhost(): boolean` — Returns `true` if the code is running on a local development server.
 - `getStatus(): ApiStatus` — Returns the `ApiStatus` manager for tracking the state, errors, and complete response object of the last network request.
 - `getResponse(): ApiResponse` — Returns the responses/emulation manager `ApiResponse` for controlling mock-responses.
 
-## Configuration Methods
+### Configuration
 
 Methods to configure the API (support chaining, returning the `ApiInstance` object):
 - `setHeaders(headers: Record<string, string>): this` — Applies universal headers injected automatically toward outbound fetch activities.
@@ -98,22 +75,26 @@ Methods to configure the API (support chaining, returning the `ApiInstance` obje
 - `setUrl(url: string): this` — Overwrites generic target URL configurations prefix points.
 - `setPreparation(callback: (apiFetch: ApiFetch) => Promise<void>): this` — Connects a custom hook function actively running just _before_ execution trigger occurs.
 - `setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this` — Sets the hook triggered exactly _after_ network response returns.
+- `setOrigin(origin: string): this` — Sets the origin (protocol and domain) for the base URL.
 
-## Request Preparation Methods
+### Auxiliary
 
-- `getUrl(path: string, api?: boolean): string` — Generates the full target URL referencing the script, handling dynamic geography variables.
+- `getUrl(path: string, api?: boolean): string` — Generates the full target URL referencing the script, handling `{locale}`, `{country}`, `{language}` placeholder substitution.
+- `getOrigin(): string` — Returns the base origin URL combined with the API path.
 - `getBody(request?: ApiFetch['request'], method?: string): string | FormData | undefined` — Creates data to be passed into the request physical body.
 - `getBodyForGet(request: ApiFetch['request'], path?: string, method?: string): string` — Forms query parameters specifically for HTTP arguments assigned into the URL directly used when sending `GET` queries.
+- `getHydration(): ApiHydration` — Returns the hydration manager.
+- `getHydrationScript(): string` — Returns a string representation of the hydration data for the client.
 
 ## ApiFetch Object
 
-`ApiFetch` is the main configuration object passed to all request methods (`request`, `get`, `post`, `put`, `delete`). All fields are optional:
+`ApiFetch` is the main configuration object passed to all request methods (`request`, `get`, `post`, `put`, `patch`, `delete`). All fields are optional:
 
 - `path?: string` — endpoint path relative to the base URL (e.g. `'users/list'`).
 - `pathFull?: string` — full request URL. If provided, overrides `api` and `path`.
 - `api?: boolean` — whether to prepend the base URL before `path`. Default: `true`.
-- `method?: ApiMethod` — HTTP method (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`). Default: `'GET'`.
-- `request?: FormData | Record<string, any> | string` — request body (for POST/PUT) or query parameters (for GET). Serialized as JSON or `FormData`.
+- `method?: ApiMethod` — HTTP method (`'GET'`, `'POST'`, `'PUT'`, `'PATCH'`, `'DELETE'`). Default: `'GET'`.
+- `request?: FormData | Record<string, any> | string` — request body (for POST/PUT/PATCH) or query parameters (for GET). Serialized as JSON or `FormData`.
 - `headers?: Record<string, string> | null` — additional request headers. Pass `null` to disable all headers.
 - `type?: string` — `Content-Type` header value. Default: `'application/json;charset=UTF-8'`.
 - `auth?: boolean` — include authentication headers.
@@ -125,10 +106,11 @@ Methods to configure the API (support chaining, returning the `ApiInstance` obje
 - `globalEnd?: boolean` — whether to run the global `setEnd` hook after the response. Default: `true`.
 - `queryReturn?: (query: Response) => Promise<any>` — custom response processor instead of the default JSON reader.
 - `init?: RequestInit` — additional options passed directly to native `fetch()` (CORS, cache mode, etc.).
-- `timeout?: number` — request timeout in milliseconds. Default: `16000`ms.
-- `controller?: AbortController` — controller for canceling the request.
+- `timeout?: number` — request timeout in milliseconds. Default: `16000`ms (only used if `controller` is not provided).
+- `controller?: AbortController` — controller for canceling the request. If provided, timeout is ignored.
 - `retry?: number` — number of retries on failure.
-- `retryDelay?: number` — base delay between retries in milliseconds. Default: `64`ms.
+- `retryDelay?: number` — base delay between retries in milliseconds. Default: `64`ms. Jitter is used to prevent thundering herd problems.
+- `endResetLimit?: number` — limit for recursive retries via `setEnd` with `reset: true`. Default: `8`.
 
 ## Response Data Structure
 
@@ -215,7 +197,7 @@ The `setEnd` method sets a callback function that is called after receiving a re
 - `apiFetch: ApiFetch` — the parameters object with which the request was performed.
 
 **Returns:** `Promise<ApiPreparationEnd>`. The result object can contain the following fields:
-- `reset?: boolean` — if set to `true`, the library will abort the current chain and **execute the request again** (recursively) after a jittered delay (see `retryDelay`). The entire process of preparation and execution will be restarted. This is used for automatic handling of refreshed access rights.
+- `reset?: boolean` — if set to `true`, the library will abort the current chain and **execute the request again** (recursively) after a jittered delay (see `retryDelay`). The entire process of preparation and execution will be restarted. This is used for automatic handling of refreshed access rights. This recursion is limited by `endResetLimit` (default: 8).
 - `data?: any` — allows you to override the data returned by the API method. If this field is specified, the standard response reading mechanism (JSON/text) will be ignored.
 
 ```javascript
@@ -245,7 +227,80 @@ You can selectively disable global hooks in the `ApiFetch` object:
 - `globalPreparation: false` — skip the `setPreparation` hook execution.
 - `globalEnd: false` — skip the `setEnd` hook execution.
 
-## Response Emulation (ApiResponse)
+## Hydration
+
+Hydration is a mechanism for transferring data obtained during Server-Side Rendering (SSR) to the client side. This avoids re-executing the same network requests immediately after the page loads in the browser, which significantly speeds up rendering and reduces server load.
+
+### How it works
+
+1. **Server-side (SSR):**
+   - All executed requests (usually `GET` methods with `global: true`) are automatically saved in the hydration list.
+   - After the page is formed, you need to call `api.getHydrationScript()` and insert the resulting string into the HTML template (usually at the end of the `<body>` tag).
+
+2. **Client-side (Browser):**
+   - When an `ApiInstance` is created, it automatically looks for the hydration script on the page.
+   - Found data is loaded into the system and substituted for the first call of similar requests.
+   - Thus, the client code receives data instantly without waiting for a network response.
+
+### Usage Example (SSR)
+
+```javascript
+// On the server
+const api = new ApiInstance();
+await api.get({ path: 'settings' });
+
+// In the page template (e.g., at the end of body)
+// The method returns a string: <script id="__ui:api:hydration:id__" type="application/json">[...]</script>
+const hydrationScript = api.getHydrationScript();
+```
+
+
+## Caching
+
+The library provides a built-in mechanism for caching responses, allowing you to save request results in memory or in external storage (e.g., `LocalStorage`).
+
+### Key Features
+
+- **Time to Live (TTL)** — for each request, you can specify the cache validity time in seconds.
+- **External Storage** — ability to integrate with any asynchronous data storage.
+- **Automatic Cleanup** — old data is removed from memory when limits are exceeded.
+
+### Setting up External Storage
+
+By default, the cache works only in RAM and is reset when the page is reloaded. To save data long-term, you need to initialize `ApiCache` with your own listeners (for example, using `LocalStorage` or `IndexedDB`):
+
+```javascript
+import { ApiCache, DataStorage } from '@dxtmisha/functional';
+
+// Example of initialization using LocalStorage via DataStorage wrapper
+ApiCache.init(
+  async (key) => DataStorage.get(key),
+  async (key, value) => {
+    DataStorage.set(key, value);
+    return true;
+  },
+  async (key) => {
+    DataStorage.remove(key);
+    return true;
+  }
+);
+```
+
+### Usage in Requests
+
+To enable caching, just pass the time in seconds in the `cache` field of the `ApiFetch` object:
+
+```javascript
+// Cache response for 1 hour (3600 seconds)
+const data = await api.get({
+  path: 'catalog/list',
+  cache: 3600
+});
+```
+
+If the data is in the cache and its lifetime has not expired, the library will return it instantly without performing a real request to the server.
+
+## Response Emulation
 
 The emulator manager `ApiResponse` (accessible via `api.getResponse()`) allows configuring mock responses for specified paths. This is incredibly useful during frontend UI development without a completely ready backend API or for writing test fixtures.
 
@@ -255,7 +310,7 @@ The `add` method accepts an `ApiResponseItem` object or an array of such objects
 
 **Key `ApiResponseItem` fields:**
 - `path` — String (exact match) or Regular Expression (`RegExp`) to intercept the request URL.
-- `method` — HTTP method (`ApiMethodItem.get`, `post`, etc.).
+- `method` — HTTP method (`ApiMethodItem.get`, `post`, `put`, `patch`, etc.).
 - `request` — (Optional) Request body filter. You can use the special marker `'*any'` to bypass payload validation and capture all requests to this path.
 - `response` — Static data object _or_ a dynamic factory function `(request) => any` that generates a response based on the incoming request payload.
 - `disable` — (Optional) Disable this mock (boolean or callback).

package/src/media/functional/functional-basic/classes/ApiInstance/ApiInstance.ru.mdx

@@ -10,11 +10,13 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 ## Ключевые особенности
 
-- **CRUD методы** — удобные алиасы `get`, `post`, `put`, `delete` для работы с HTTP-запросами
+- **CRUD методы** — удобные алиасы `get`, `post`, `put`, `patch`, `delete` для работы с HTTP-запросами
 - **Глобальная конфигурация** — установка базового URL, заголовков и параметров по умолчанию для всех запросов
 - **Хуки жизненного цикла** — возможность задать функции, выполняемые до (`setPreparation`) и после (`setEnd`) каждого запроса
 - **Отслеживание статуса** — доступ к статусу и ошибкам последнего запроса через `ApiStatus`
-- **Кэширование и эмуляция** — управление мок-ответами и кэшированием через `ApiResponse`
+- **Гидратация** — передача данных от сервера к клиенту (SSR) для мгновенной отрисовки
+- **Кэширование** — сохранение ответов во внутреннем или внешнем хранилище через `ApiCache`
+- **Эмуляция ответов** — гибкое управление мок-данными через `ApiResponse`
 - **Автоматический парсинг** — преобразование тела запроса в JSON/FormData и автоматическое извлечение данных из JSON-ответов
 - **Геолокация** — автоматическая подстановка `{locale}`, `{country}`, `{language}` в пути запросов
 
@@ -35,10 +37,13 @@ import {Meta} from '@storybook/addon-docs/blocks'
 - `preparationClass?: typeof ApiPreparation` — класс для управления хуками жизненного цикла.
 - `loadingClass?: LoadingInstance` — экземпляр менеджера индикации загрузки (по умолчанию: `Loading.getItem()`).
 - `errorCenterClass?: ErrorCenterInstance` — экземпляр центра ошибок для вызова событий (по умолчанию: `ErrorCenter.getItem()`).
+- `hydrationClass?: typeof ApiHydration` — класс для управления гидратацией SSR.
 
-## Методы запросов
+## Методы
 
-### `request`
+### Действие
+
+#### `request`
 
 Универсальный метод для выполнения сетевого HTTP-запроса. Если передана строка, выполняется простой `GET` запрос по этому адресу.
 В случае сетевых сбоев (например, 500 статус) метод явно выбрасывает исключение (`throw e`), что позволяет перехватывать ошибки в `try/catch`. Если сервер возвращает JSON объект, к возвращаемым данным автоматически добавляется поле `statusObject` (инстанс статуса запроса).
@@ -48,49 +53,21 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 **Возвращает:** `Promise<ApiData<T>>` — возвращает спарсенные данные ответа сервера (с полями `data`, `statusObject` и др., если возвращается объект).
 
-### `get`
-
-Отправляет запрос методом `GET`.
-
-**Параметры:**
-- `request: ApiFetch` — конфигурационный объект запроса (содержащий `path`, `request` и т.д.).
-
-**Возвращает:** `Promise<T>`
-
-### `post`
+### Сокращенные методы
 
-Отправляет запрос методом `POST`. Идеально для создания/сохранения сущностей.
+- `get(request: ApiFetch): Promise<T>` — Отправляет запрос методом `GET`.
+- `post(request: ApiFetch): Promise<T>` — Отправляет запрос методом `POST`. Идеально для создания/сохранения сущностей.
+- `put(request: ApiFetch): Promise<T>` — Отправляет запрос методом `PUT`. Применяется для обновления данных.
+- `patch(request: ApiFetch): Promise<T>` — Отправляет запрос методом `PATCH`. Используется для частичного обновления данных ресурса.
+- `delete(request: ApiFetch): Promise<T>` — Отправляет запрос методом `DELETE`. Применяется для удаления данных из системы.
 
-**Параметры:**
-- `request: ApiFetch` — конфигурационный объект запроса (содержащий `path`, `request` и т.д.).
-
-**Возвращает:** `Promise<T>`
-
-### `put`
-
-Отправляет запрос методом `PUT`. Применяется для обновления данных.
-
-**Параметры:**
-- `request: ApiFetch` — конфигурационный объект запроса (содержащий `path`, `request` и т.д.).
-
-**Возвращает:** `Promise<T>`
-
-### `delete`
-
-Отправляет запрос методом `DELETE`. Применяется для удаления данных из системы.
-
-**Параметры:**
-- `request: ApiFetch` — конфигурационный объект запроса (содержащий `path`, `request` и т.д.).
-
-**Возвращает:** `Promise<T>`
-
-## Методы получения инстансов
+### Проверка
 
 - `isLocalhost(): boolean` — Возвращает `true`, если код запущен на локальном сервере.
 - `getStatus(): ApiStatus` — Возвращает менеджер `ApiStatus` для работы со статусом последнего запроса.
 - `getResponse(): ApiResponse` — Возвращает менеджер эмуляции `ApiResponse`.
 
-## Конфигурация
+### Конфигурация
 
 Методы для настройки API (поддерживают чейнинг вызовов, возвращают объект `ApiInstance`):
 - `setHeaders(headers: Record<string, string>): this` — Устанавливает глобальные заголовки по умолчанию.
@@ -98,22 +75,26 @@ import {Meta} from '@storybook/addon-docs/blocks'
 - `setUrl(url: string): this` — Изменяет базовый URL путь для API скриптов.
 - `setPreparation(callback: (apiFetch: ApiFetch) => Promise<void>): this` — Устанавливает хук, выполняемый перед каждым сетевым запросом.
 - `setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this` — Устанавливает хук, выполняемый после получения ответа.
+- `setOrigin(origin: string): this` — Устанавливает источник (протокол и домен) для формирования базового URL.
 
-## Формирование запроса
+### Вспомогательные
 
-- `getUrl(path: string, api?: boolean): string` — Формирует полный адрес к скрипту запроса с подстановкой гео-меток.
+- `getUrl(path: string, api?: boolean): string` — Формирует полный адрес к скрипту запроса с подстановкой плейсхолдеров `{locale}`, `{country}`, `{language}`.
+- `getOrigin(): string` — Возвращает базовый URL источника, объединенный с путем API.
 - `getBody(request?: ApiFetch['request'], method?: string): string | FormData | undefined` — Формирует данные для тела запроса.
 - `getBodyForGet(request: ApiFetch['request'], path?: string, method?: string): string` — Формирует строку query-параметров для GET-запроса.
+- `getHydration(): ApiHydration` — Возвращает менеджер гидратации.
+- `getHydrationScript(): string` — Возвращает строковое представление данных гидратации для клиента.
 
 ## Объект ApiFetch
 
-`ApiFetch` — главный конфигурационный объект, передаваемый в методы `request`, `get`, `post`, `put`, `delete`. Все поля опциональны:
+`ApiFetch` — главный конфигурационный объект, передаваемый в методы `request`, `get`, `post`, `put`, `patch`, `delete`. Все поля опциональны:
 
 - `path?: string` — путь к endpoint-скрипту относительно базового URL (например: `'users/list'`).
 - `pathFull?: string` — полный URL запроса. Если указан, игнорирует `api` и `path`.
 - `api?: boolean` — добавлять ли базовый URL перед `path`. По умолчанию: `true`.
-- `method?: ApiMethod` — HTTP-метод (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`). По умолчанию: `'GET'`.
-- `request?: FormData | Record<string, any> | string` — тело запроса (для POST/PUT) или query-параметры (для GET). Передается как JSON или `FormData`.
+- `method?: ApiMethod` — HTTP-метод (`'GET'`, `'POST'`, `'PUT'`, `'PATCH'`, `'DELETE'`). По умолчанию: `'GET'`.
+- `request?: FormData | Record<string, any> | string` — тело запроса (для POST/PUT/PATCH) или query-параметры (for GET). Передается как JSON или `FormData`.
 - `headers?: Record<string, string> | null` — дополнительные заголовки запроса. `null` — отключить все заголовки.
 - `type?: string` — значение `Content-Type`. По умолчанию: `'application/json;charset=UTF-8'`.
 - `auth?: boolean` — добавить заголовки аутентификации.
@@ -125,10 +106,11 @@ import {Meta} from '@storybook/addon-docs/blocks'
 - `globalEnd?: boolean` — запускать ли глобальный хук `setEnd` после ответа. По умолчанию: `true`.
 - `queryReturn?: (query: Response) => Promise<any>` — обработчик ответа вместо стандартного чтения JSON.
 - `init?: RequestInit` — дополнительные опции для нативного `fetch()` (CORS, режим кеша и др.).
-- `timeout?: number` — таймаут запроса в миллисекундах. По умолчанию: `16000`мс.
-- `controller?: AbortController` — контроллер для отмены запроса.
+- `timeout?: number` — таймаут запроса в миллисекундах. По умолчанию: `16000`мс (используется только если не передан `controller`).
+- `controller?: AbortController` — контроллер для отмены запроса. Если передан, таймаут игнорируется.
 - `retry?: number` — количество повторов при сбое.
-- `retryDelay?: number` — базовая задержка между повторами в миллисекундах. По умолчанию: `64`мс.
+- `retryDelay?: number` — базовая задержка между повторами в миллисекундах. По умолчанию: `64`мс. Используется алгоритм с джиттером для предотвращения лавинообразных запросов.
+- `endResetLimit?: number` — лимит рекурсивных повторов через `setEnd` с `reset: true`. По умолчанию: `8`.
 
 ## Структура данных ответа
 
@@ -187,7 +169,7 @@ controller.abort()
 Метод `setPreparation` устанавливает callback-функцию, которая вызывается непосредственно перед отправкой запроса на сервер (до выполнения нативного `fetch`).
 
 **Особенности работы:**
-- **Очередность исполнения**: Если одновременно запускается несколько запросов, класс гарантирует, что хук подготовки будет выполнен **последовательно**. Все последующие запросы будут ждать завершения текущего хука в режиме ожидания (с интервалом опроса 160мс). Это предотвращает конфликты, например, при одновременном обновлении токена несколькими запросами.
+- **Очередность исполнения**: Если одновременно запускается несколько запросов, класс гарантирует, что хук подготовки будет выполнен **последовательно**. Все последующие запросы будут ждать завершения текущего хука в режиме ожидания (с интервалом опроса 16мс). Это предотвращает конфликты, например, при одновременном обновлении токена несколькими запросами.
 - **Параметры**: Получает объект `apiFetch`, содержащий все текущие настройки запроса. Вы можете изменять этот объект (например, добавляя заголовки или модифицируя тело запроса).
 - **Возвращает**: `Promise<void>`.
 
@@ -215,7 +197,7 @@ api.setPreparation(async (apiFetch) => {
 - `apiFetch: ApiFetch` — объект параметров, с которыми был выполнен запрос.
 
 **Возвращает:** `Promise<ApiPreparationEnd>`. Объект результата может содержать следующие поля:
-- `reset?: boolean` — если установлено в `true`, библиотека прервет текущую цепочку и **выполнит запрос заново** (рекурсивно) через рандомизированную задержку (см. `retryDelay`). Весь процесс подготовки и выполнения будет запущен повторно. Используется для автоматической обработки обновленных прав доступа.
+- `reset?: boolean` — если установлено в `true`, библиотека прервет текущую цепочку и **выполнит запрос заново** (рекурсивно) через рандомизированную задержку (см. `retryDelay`). Весь процесс подготовки и выполнения будет запущен повторно. Используется для автоматической обработки обновленных прав доступа. Лимит таких повторов ограничен параметром `endResetLimit` (по умолчанию 8).
 - `data?: any` — позволяет переопределить данные, которые вернет метод API. Если это поле указано, стандартный механизм чтения ответа (JSON/текст) будет проигнорирован.
 
 ```javascript
@@ -245,7 +227,80 @@ api.setEnd(async (response, apiFetch) => {
 - `globalPreparation: false` — пропустить выполнение хука `setPreparation`.
 - `globalEnd: false` — пропустить выполнение хука `setEnd`.
 
-## Эмуляция ответов (ApiResponse)
+## Гидратация
+
+Гидратация — это механизм передачи данных, полученных в ходе серверного рендеринга (SSR), на сторону клиента. Это позволяет избежать повторного выполнения тех же самых сетевых запросов сразу после загрузки страницы в браузере, что значительно ускоряет отрисовку и снижает нагрузку на сервер.
+
+### Как это работает
+
+1. **На стороне сервера (SSR):**
+   - Все выполненные запросы (обычно метода `GET` с параметром `global: true`) автоматически сохраняются в списке гидратации.
+   - После завершения формирования страницы необходимо вызвать метод `api.getHydrationScript()` и вставить полученную строку в HTML-шаблон (обычно в конец тега `<body>`).
+
+2. **На стороне клиента (Браузер):**
+   - При создании экземпляра `ApiInstance` он автоматически ищет на странице скрипт с данными гидратации.
+   - Найденные данные загружаются в систему и подставляются вместо первого вызова аналогичных запросов.
+   - Таким образом, клиентский код получает данные мгновенно, не дожидаясь ответа от сети.
+
+### Пример использования (SSR)
+
+```javascript
+// На сервере
+const api = new ApiInstance();
+await api.get({ path: 'settings' });
+
+// В шаблоне страницы (например, в конце body)
+// Метод вернет строку: <script id="__ui:api:hydration:id__" type="application/json">[...]</script>
+const hydrationScript = api.getHydrationScript();
+```
+
+
+## Кэширование
+
+Библиотека предоставляет встроенный механизм кэширования ответов, который позволяет сохранять результаты запросов в памяти или во внешнем хранилище (например, `LocalStorage`).
+
+### Основные возможности
+
+- **Время жизни (TTL)** — для каждого запроса можно указать время актуальности кэша в секундах.
+- **Внешние хранилища** — возможность интеграции с любым асинхронным хранилищем данных.
+- **Автоматическая очистка** — старые данные удаляются из памяти при превышении лимитов.
+
+### Настройка внешнего хранилища
+
+По умолчанию кэш работает только в оперативной памяти и сбрасывается при перезагрузке страницы. Чтобы сохранять данные надолго, необходимо инициализировать `ApiCache` своими слушателями (например, используя `LocalStorage` или `IndexedDB`):
+
+```javascript
+import { ApiCache, DataStorage } from '@dxtmisha/functional';
+
+// Пример инициализации с использованием LocalStorage через обертку DataStorage
+ApiCache.init(
+  async (key) => DataStorage.get(key),
+  async (key, value) => {
+    DataStorage.set(key, value);
+    return true;
+  },
+  async (key) => {
+    DataStorage.remove(key);
+    return true;
+  }
+);
+```
+
+### Использование в запросах
+
+Для включения кэширования достаточно передать время в секундах в поле `cache` объекта `ApiFetch`:
+
+```javascript
+// Кэшировать ответ на 1 час (3600 секунд)
+const data = await api.get({
+  path: 'catalog/list',
+  cache: 3600
+});
+```
+
+Если данные есть в кэше и их время жизни не истекло, библиотека вернет их мгновенно, не выполняя реальный запрос к серверу.
+
+## Эмуляция ответов
 
 Менеджер эмуляции `ApiResponse` (доступен через `api.getResponse()`) позволяет настраивать мок-ответы для определенных путей — это невероятно полезно при разработке UI без готового Backend API или для написания тестов.
 
@@ -255,7 +310,7 @@ api.setEnd(async (response, apiFetch) => {
 
 **Важные поля `ApiResponseItem`:**
 - `path` — Строка (точное совпадение) или Регулярное выражение (`RegExp`) для перехвата пути.
-- `method` — HTTP метод (`ApiMethodItem.get`, `post` и т.д.).
+- `method` — HTTP метод (`ApiMethodItem.get`, `post`, `put`, `patch` и т.д.).
 - `request` — (Опционально) Фильтр по телу запроса. Можно использовать специальный маркер `'*any'`, чтобы перехватывать любые данные.
 - `response` — Статический объект с данными ответа _или_ функция `(request) => any`, генерирующая ответ динамически на основе параметров запроса.
 - `disable` — (Опционально) Отключить этот мок (boolean или callback).