@dxtmisha/wiki 0.39.6 → 0.39.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dxtmisha/wiki",
   "private": false,
-  "version": "0.39.6",
+  "version": "0.39.8",
   "type": "module",
   "description": "Wiki documentation and storybook utilities for DXT UI design system",
   "keywords": [

package/src/library.ts

@@ -1,6 +1,5 @@
 // Classes
 export * from './classes/WikiStorybook'
-export * from './classes/WikiStorybookDescriptions'
 export * from './classes/WikiStorybookItem'
 export * from './classes/WikiStorybookProp'
 

package/src/media/functional/functional-basic/api/api.en.mdx

@@ -6,6 +6,17 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 The `Api` class is a central utility for making HTTP requests. It provides a simple interface for common methods and manages global settings like base URL, default headers, and lifecycle hooks.
 
+### Key Capabilities
+
+The class provides a comprehensive set of tools for managing network communication:
+- **CRUD Methods** — execution of `GET`, `POST`, `PUT`, `PATCH`, `DELETE` requests.
+- **Global Configuration** — setting up base URLs, headers, and parameters.
+- **Lifecycle Hooks** — handling events before and after the request (e.g., for Refresh Token).
+- **Hydration (SSR)** — transferring data from server to client to prevent duplicate requests.
+- **Caching** — saving responses in memory or external storage (LocalStorage).
+- **Response Emulation** — creating mock data for development and testing.
+- **Loading and Error Management** — integration with global indicator components and error centers.
+
 ## Basic Usage
 
 The simplest way to make a request is by using the static methods `get`, `post`, `put`, or `delete`. All methods support response typing via Generics.
@@ -84,6 +95,40 @@ Api.setEnd(async (response, apiFetch) => {
 })
 ```
 
+## Hydration
+
+Hydration allows transferring data obtained during server-side rendering (SSR) to the client side. This prevents the same requests from being executed again immediately after the page loads.
+
+1. **On the Server**: Perform the necessary requests and get the script via `Api.getHydrationScript()`.
+2. **In the Template**: Insert the resulting string into the HTML.
+3. **On the Client**: Upon `Api` initialization, the data will be automatically loaded into the response manager.
+
+```javascript
+// SSR Example
+await Api.get({ path: 'settings' });
+const hydrationScript = Api.getHydrationScript(); // <script>...</script>
+```
+
+## Caching
+
+The `Api` class supports automatic response caching. You can use either the built-in in-memory storage or connect external storage (e.g., `LocalStorage`).
+
+```javascript
+import { ApiCache, DataStorage } from '@dxtmisha/functional-basic';
+
+// Connecting external storage (optional)
+ApiCache.init(
+  async (key) => DataStorage.get(key),
+  async (key, value) => DataStorage.set(key, value)
+);
+
+// Usage in a request
+const data = await Api.get({
+  path: 'catalog/list',
+  cache: 3600 // Cache for 1 hour (in seconds)
+});
+```
+
 ## Response Emulation
 
 The built-in `ApiResponse` manager (accessible via `Api.getResponse()`) allows you to intercept requests and return mock data. This is extremely useful for UI development when the backend is not ready, or for writing tests.

package/src/media/functional/functional-basic/api/api.ru.mdx

@@ -6,6 +6,17 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 Класс `Api` — это основной инструмент для работы с HTTP-запросами. Он предоставляет простой интерфейс для стандартных методов и управляет глобальными настройками, такими как базовый URL, заголовки по умолчанию и хуки жизненного цикла.
 
+### Основные возможности
+
+Класс предоставляет полный набор инструментов для управления сетевым взаимодействием:
+- **CRUD методы** — выполнение `GET`, `POST`, `PUT`, `PATCH`, `DELETE` запросов.
+- **Глобальная конфигурация** — настройка базовых URL, заголовков и параметров.
+- **Хуки жизненного цикла** — обработка событий до и после запроса (например, для Refresh Token).
+- **Гидратация (SSR)** — передача данных от сервера к клиенту для предотвращения дублирования запросов.
+- **Кэширование** — сохранение ответов в памяти или внешнем хранилище (LocalStorage).
+- **Эмуляция ответов** — создание мок-данных для разработки и тестирования.
+- **Управление загрузкой и ошибками** — интеграция с глобальными компонентами индикации и центрами ошибок.
+
 ## Базовое использование
 
 Самый простой способ выполнить запрос — использовать статические методы `get`, `post`, `put`, или `delete`. Все методы поддерживают типизацию ответа через Generic.
@@ -84,6 +95,40 @@ Api.setEnd(async (response, apiFetch) => {
 })
 ```
 
+## Гидратация
+
+Гидратация позволяет передавать данные, полученные при серверном рендеринге (SSR), на клиентскую сторону. Это предотвращает повторное выполнение одних и тех же запросов сразу после загрузки страницы.
+
+1. **На сервере**: выполните нужные запросы и получите скрипт через `Api.getHydrationScript()`.
+2. **В шаблоне**: вставьте полученную строку в HTML.
+3. **На клиенте**: при инициализации `Api` данные будут автоматически загружены в менеджер ответов.
+
+```javascript
+// Пример на сервере (SSR)
+await Api.get({ path: 'settings' });
+const hydrationScript = Api.getHydrationScript(); // <script>...</script>
+```
+
+## Кэширование
+
+Класс `Api` поддерживает автоматическое кэширование ответов. Вы можете использовать как встроенное хранилище в памяти, так и подключить внешнее (например, `LocalStorage`).
+
+```javascript
+import { ApiCache, DataStorage } from '@dxtmisha/functional-basic';
+
+// Подключение внешнего хранилища (необязательно)
+ApiCache.init(
+  async (key) => DataStorage.get(key),
+  async (key, value) => DataStorage.set(key, value)
+);
+
+// Использование в запросе
+const data = await Api.get({
+  path: 'catalog/list',
+  cache: 3600 // Кэшировать на 1 час (в секундах)
+});
+```
+
 ## Эмуляция ответов
 
 Встроенный менеджер `ApiResponse` (доступен через `Api.getResponse()`) позволяет перехватывать запросы и возвращать мок-данные. Это крайне полезно при разработке интерфейса, когда бэкенд еще не готов, или для написания тестов.

package/src/media/functional/functional-basic/api/api.vi.mdx

@@ -6,6 +6,17 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 Lớp `Api` là công cụ trung tâm để thực hiện các yêu cầu HTTP. Nó cung cấp một giao diện đơn giản cho các phương thức phổ biến và quản lý các cài đặt toàn cục như URL cơ sở, tiêu đề mặc định và các hook vòng đời.
 
+### Các khả năng chính
+
+Lớp cung cấp một bộ công cụ toàn diện để quản lý tương tác mạng:
+- **Các phương thức CRUD** — thực hiện các yêu cầu `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
+- **Cấu hình toàn cục** — thiết lập URL cơ sở, tiêu đề và tham số.
+- **Hook vòng đời** — xử lý các sự kiện trước và sau yêu cầu (ví dụ: cho Refresh Token).
+- **Hydration (SSR)** — chuyển dữ liệu từ máy chủ sang máy khách để ngăn chặn các yêu cầu trùng lặp.
+- **Bộ nhớ đệm (Caching)** — lưu các phản hồi trong bộ nhớ hoặc bộ nhớ ngoài (LocalStorage).
+- **Giả lập phản hồi** — tạo dữ liệu giả để phát triển và kiểm thử.
+- **Quản lý tải và lỗi** — tích hợp với các thành phần chỉ báo toàn cục và trung tâm lỗi.
+
 ## Cách dùng cơ bản
 
 Cách đơn giản nhất để thực hiện yêu cầu là sử dụng các phương thức tĩnh `get`, `post`, `put`, hoặc `delete`. Tất cả các phương thức đều hỗ trợ định nghĩa kiểu dữ liệu (typing) thông qua Generic.
@@ -84,6 +95,40 @@ Api.setEnd(async (response, apiFetch) => {
 })
 ```
 
+## Hydration
+
+Hydration cho phép chuyển dữ liệu thu được trong quá trình server-side rendering (SSR) sang phía máy khách. Điều này ngăn chặn việc thực hiện lại các yêu cầu tương tự ngay sau khi trang tải xong.
+
+1. **Trên máy chủ**: Thực hiện các yêu cầu cần thiết và lấy script qua `Api.getHydrationScript()`.
+2. **Trong mẫu (Template)**: Chèn chuỗi kết quả vào HTML.
+3. **Trên máy khách**: Khi khởi tạo `Api`, dữ liệu sẽ tự động được tải vào trình quản lý phản hồi.
+
+```javascript
+// Ví dụ SSR
+await Api.get({ path: 'settings' });
+const hydrationScript = Api.getHydrationScript(); // <script>...</script>
+```
+
+## Bộ nhớ đệm (Caching)
+
+Lớp `Api` hỗ trợ tự động lưu bộ nhớ đệm cho các phản hồi. Bạn có thể sử dụng bộ nhớ trong tích hợp hoặc kết nối bộ nhớ ngoài (ví dụ: `LocalStorage`).
+
+```javascript
+import { ApiCache, DataStorage } from '@dxtmisha/functional-basic';
+
+// Kết nối bộ nhớ ngoài (tùy chọn)
+ApiCache.init(
+  async (key) => DataStorage.get(key),
+  async (key, value) => DataStorage.set(key, value)
+);
+
+// Sử dụng trong một yêu cầu
+const data = await Api.get({
+  path: 'catalog/list',
+  cache: 3600 // Lưu bộ nhớ đệm trong 1 giờ (tính bằng giây)
+});
+```
+
 ## Giả lập phản hồi
 
 Trình quản lý `ApiResponse` tích hợp sẵn (có thể truy cập qua `Api.getResponse()`) cho phép bạn chặn các yêu cầu và trả về dữ liệu giả (mock). Điều này cực kỳ hữu ích cho việc phát triển giao diện khi backend chưa sẵn sàng hoặc để viết các bài kiểm thử.

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

@@ -1,78 +1,78 @@
 import {Meta} from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/en/functional-basic/Classes/Api - Request Management'/>
+<Meta title='@dxtmisha/en/functional-basic/Classes/Api - Request Management (Static)'/>
 
 # Api Class
 
-`Api` is a static wrapper class around the `ApiInstance` instance for efficient network request operations.
+The `Api` class is a **Primary Class (Static)** and serves as the main entry point for managing HTTP requests. It is a static wrapper around a globally managed `ApiInstance`, providing a clean, singleton-based interface for standard network operations.
 
-All methods of the `Api` class are automatically delegated to an internal global `ApiInstance` object. This allows you to work with HTTP requests without the need to manually instantiate objects:
+## Key Features
 
-```typescript
-import { Api } from '@dxtmisha/functional'
+- **Static Interface** — perform standard HTTP operations (`GET`, `POST`, etc.) without manual instantiation.
+- **Global Lifecycle Hooks** — configure request preparation and analysis once for the entire application.
+- **SSR Isolation** — utilizes `ServerStorage` to manage individual instance isolation during server-side rendering.
+- **Simplified Setup** — provides a unified `setConfig` method to apply multiple configuration layers at once.
 
-// These calls interact with the same global instance under the hood
-Api.setUrl('https://api.example.com/v1/')
-Api.setHeaders({ 'Authorization': 'Bearer token123' })
+## Methods
 
-const data = await Api.get({ path: 'users' })
-```
+### Action
 
-## Methods
+Methods for performing physical network requests.
+
+- `request<T>(pathRequest: string | ApiFetch): Promise<T>` — Core executor; accepts a path string or configuration object.
+- `get<T>(request: ApiFetch): Promise<T>` — Sends a GET request.
+- `post<T>(request: ApiFetch): Promise<T>` — Sends a POST request.
+- `put<T>(request: ApiFetch): Promise<T>` — Sends a PUT request.
+- `patch<T>(request: ApiFetch): Promise<T>` — Sends a PATCH request.
+- `delete<T>(request: ApiFetch): Promise<T>` — Sends a DELETE request.
+
+### Check
+
+- `isLocalhost(): boolean` — Checks if the current environment is a local development server.
 
-### Instance Access
+### Configuration
 
-- `getItem(): ApiInstance` — Returns the internal `ApiInstance` object used by all static method delegations.
+- `setUrl(url: string): void` — Changes the base API URL.
+- `setHeaders(headers: Record<string, string>): void` — Sets default request headers.
+- `setRequestDefault(request: Record<string, any>): void` — Sets default request body data.
+- `setPreparation(callback): void` — Registers a hook to run before every enabled request.
+- `setEnd(callback): void` — Registers a hook to run after every enabled response.
+- `setTimeout(timeout: number): void` — Changes the global request timeout.
+- `setConfig(config?: ApiConfig): void` — Applies a complete configuration object.
 
-### Information Methods
+### Auxiliary
 
-- `isLocalhost(): boolean` — Returns `true` if the code is running on a local development server.
-- `getStatus(): ApiStatus` — Returns the `ApiStatus` manager for tracking the state and errors of the last request.
-- `getResponse(): ApiResponse` — Returns the responses/emulation manager `ApiResponse`.
-- `getUrl(path: string, api?: boolean): string` — Returns the full URL for the request. Dynamic placeholders `{locale}`, `{country}`, `{language}` are automatically replaced.
-- `getBody(request?, method?): string | FormData | undefined` — Returns data for the request body.
-- `getBodyForGet(request, path?, method?): string` — Returns the query string for GET method requests.
+- `getStatus(): ApiStatus` — Accesses the status manager for the last request.
+- `getResponse(): ApiResponse` — Accesses the response/emulation manager.
+- `getHydration(): ApiHydration` — Accesses the hydration manager.
+- `getHydrationScript(): string` — Returns the script block for SSR-to-client hydration.
+- `getUrl(path: string, api?: boolean): string` — Returns the fully resolved URL with `{locale}`, `{country}`, `{language}` placeholder substitution.
+- `getBody(request, method?): string | FormData | undefined` — Prepares the request body.
+- `getBodyForGet(request, path?, method?): string` — Prepares the query string.
+- `getItem(): ApiInstance` — Returns the underlying `ApiInstance` object.
 
-### Configuration Methods
+## Types
 
-All configuration methods return the `Api` class itself for chaining:
+### ApiConfig
 
-- `setUrl(url: string): Api` — Sets the base URL for all requests.
-- `setHeaders(headers: Record<string, string>): Api` — Sets default headers for all requests.
-- `setRequestDefault(request: Record<string, any>): Api` — Sets default request data merged into every request body.
-- `setPreparation(callback): Api` — Sets a callback function executed before each request.
-- `setEnd(callback): Api` — Sets a callback function executed after each request.
-- `setConfig(config?: ApiConfig): Api` — Applies a full configuration object at once (`urlRoot`, `headers`, `requestDefault`, `preparation`, `end`).
+- `urlRoot: string` — the base URL for the API.
+- `headers: Record<string, string>` — default request headers.
+- `requestDefault: Record<string, any>` — default request data.
+- `preparation: (apiFetch: ApiFetch) => Promise<void>` — entry hook.
+- `end: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>` — exit hook.
+- `timeout: number` — global timeout in milliseconds.
 
-### Request Methods
+## Proxy Architecture
 
-- `request<T>(pathRequest: string | ApiFetch): Promise<T>` — Core request executor. Accepts a string path or an `ApiFetch` configuration object.
-- `get<T>(request: ApiFetch): Promise<T>` — Sends an HTTP GET request.
-- `post<T>(request: ApiFetch): Promise<T>` — Sends an HTTP POST request.
-- `put<T>(request: ApiFetch): Promise<T>` — Sends an HTTP PUT request.
-- `delete<T>(request: ApiFetch): Promise<T>` — Sends an HTTP DELETE request.
+The `Api` class operates as a **Static Proxy**. All method calls are redirected to an internal `ApiInstance`.
 
-## setConfig
+### Instance Management
 
-The `setConfig` method allows applying multiple configuration options at once using an `ApiConfig` object:
+The internal manager is stored in `ServerStorage` using a unique key (`__dxt_api_instance__`). This architecture solves two major problems:
 
-```typescript
-import { Api } from '@dxtmisha/functional'
+1.  **Thread Safety in SSR**: During server-side rendering, `ServerStorage` ensures that each incoming request has its own isolated API configuration and state, preventing data leaks between users.
+2.  **Singleton Simplicity on Client**: On the client side, it behaves as a true singleton, allowing you to configure the API in your entry point and use it anywhere without passing instances.
 
-Api.setConfig({
-  urlRoot: 'https://api.example.com/v1/',
-  headers: { 'Authorization': 'Bearer token123' },
-  requestDefault: { source: 'webapp' },
-  preparation: async (apiFetch) => {
-    console.log('Preparing:', apiFetch.path)
-  },
-  end: async (response, apiFetch) => {
-    if (response.status === 401) {
-      return { reset: true }
-    }
-    return {}
-  }
-})
-```
+### Delegation
 
-> **Important:** The exhaustive details on `ApiFetch` options, lifecycle hooks, response emulation, and response data structure are documented in the core **ApiInstance** documentation.
+While `Api` is the preferred interface for standard application logic, the core logic (retries, hydration logic, jitter) resides within `ApiInstance`. For advanced scenarios involving multiple base URLs or different header sets simultaneously, you may instantiate `ApiInstance` directly.

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

@@ -1,78 +1,78 @@
 import {Meta} from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/ru/functional-basic/Classes/Api - Управление запросами'/>
+<Meta title='@dxtmisha/ru/functional-basic/Classes/Api - Управление запросами (Static)'/>
 
 # Класс Api
 
-`Api` — это статичная обертка над инстансом `ApiInstance`.
+Класс `Api` является **основным классом (статическим)** и служит главной точкой входа для управления HTTP-запросами. Он представляет собой статическую обертку над глобально управляемым `ApiInstance`, предоставляя чистый интерфейс на основе синглтона для стандартных сетевых операций.
 
-Все вызовы методов `Api` автоматически делегируются внутреннему глобальному объекту `ApiInstance`. Это позволяет работать с HTTP запросами без необходимости самостоятельного создания инстансов:
+## Ключевые особенности
 
-```typescript
-import { Api } from '@dxtmisha/functional'
+- **Статический интерфейс** — выполнение стандартных HTTP-операций (`GET`, `POST` и т. д.) без необходимости ручного создания экземпляров.
+- **Глобальные хуки жизненного цикла** — настройте подготовку и анализ запросов один раз для всего приложения.
+- **Изоляция в SSR** — использует `ServerStorage` для управления изоляцией отдельных экземпляров во время рендеринга на стороне сервера.
+- **Упрощенная настройка** — предоставляет унифицированный метод `setConfig` для одновременного применения нескольких слоев конфигурации.
 
-// Эти вызовы обращаются к одному и тому же глобальному инстансу под капотом
-Api.setUrl('https://api.example.com/v1/')
-Api.setHeaders({ 'Authorization': 'Bearer token123' })
+## Методы
 
-const data = await Api.get({ path: 'users' })
-```
+### Действие
 
-## Методы
+Методы для выполнения физических сетевых запросов.
+
+- `request<T>(pathRequest: string | ApiFetch): Promise<T>` — Основной исполнитель; принимает строку пути или объект конфигурации.
+- `get<T>(request: ApiFetch): Promise<T>` — Отправляет GET-запрос.
+- `post<T>(request: ApiFetch): Promise<T>` — Отправляет POST-запрос.
+- `put<T>(request: ApiFetch): Promise<T>` — Отправляет PUT-запрос.
+- `patch<T>(request: ApiFetch): Promise<T>` — Отправляет PATCH-запрос.
+- `delete<T>(request: ApiFetch): Promise<T>` — Отправляет DELETE-запрос.
+
+### Проверка
+
+- `isLocalhost(): boolean` — Проверяет, запущена ли среда на локальном сервере разработки.
 
-### Доступ к инстансу
+### Конфигурация
 
-- `getItem(): ApiInstance` — Возвращает внутренний объект `ApiInstance`, используемый всеми статическими методами.
+- `setUrl(url: string): void` — Изменяет базовый URL API.
+- `setHeaders(headers: Record<string, string>): void` — Устанавливает заголовки запроса по умолчанию.
+- `setRequestDefault(request: Record<string, any>): void` — Устанавливает данные тела запроса по умолчанию.
+- `setPreparation(callback): void` — Регистрирует хук, запускаемый перед каждым включенным запросом.
+- `setEnd(callback): void` — Регистрирует хук, запускаемый после каждого включенного ответа.
+- `setTimeout(timeout: number): void` — Изменяет глобальный таймаут запроса.
+- `setConfig(config?: ApiConfig): void` — Применяет полный объект конфигурации.
 
-### Информационные методы
+### Вспомогательные
 
-- `isLocalhost(): boolean` — Возвращает `true`, если код работает на локальном сервере разработки.
-- `getStatus(): ApiStatus` — Возвращает менеджер `ApiStatus` для отслеживания состояния и ошибок последнего запроса.
-- `getResponse(): ApiResponse` — Возвращает менеджер ответов/эмуляции `ApiResponse`.
-- `getUrl(path: string, api?: boolean): string` — Возвращает полный URL запроса. Динамические заполнители `{locale}`, `{country}`, `{language}` заменяются автоматически.
-- `getBody(request?, method?): string | FormData | undefined` — Возвращает данные для тела запроса.
-- `getBodyForGet(request, path?, method?): string` — Возвращает строку параметров запроса для метода GET.
+- `getStatus(): ApiStatus` — Доступ к менеджеру статуса последнего запроса.
+- `getResponse(): ApiResponse` — Доступ к менеджеру ответов/эмуляции.
+- `getHydration(): ApiHydration` — Доступ к менеджеру гидратации.
+- `getHydrationScript(): string` — Возвращает блок скрипта для гидратации SSR-клиент.
+- `getUrl(path: string, api?: boolean): string` — Возвращает полностью разрешенный URL с подстановкой плейсхолдеров `{locale}`, `{country}`, `{language}`.
+- `getBody(request?, method?): string | FormData | undefined` — Подготавливает тело запроса.
+- `getBodyForGet(request, path?, method?): string` — Подготавливает строку запроса.
+- `getItem(): ApiInstance` — Возвращает базовый объект `ApiInstance`.
 
-### Методы конфигурации
+## Типы
 
-Все методы конфигурации возвращают сам класс `Api` для цепочечного вызова:
+### ApiConfig
 
-- `setUrl(url: string): Api` — Устанавливает базовый URL для всех запросов.
-- `setHeaders(headers: Record<string, string>): Api` — Устанавливает заголовки по умолчанию для всех запросов.
-- `setRequestDefault(request: Record<string, any>): Api` — Устанавливает данные запроса по умолчанию, объединяемые с каждым телом запроса.
-- `setPreparation(callback): Api` — Устанавливает функцию обратного вызова, выполняемую перед каждым запросом.
-- `setEnd(callback): Api` — Устанавливает функцию обратного вызова, выполняемую после каждого запроса.
-- `setConfig(config?: ApiConfig): Api` — Применяет полный объект конфигурации сразу (`urlRoot`, `headers`, `requestDefault`, `preparation`, `end`).
+- `urlRoot: string` — базовый URL для API.
+- `headers: Record<string, string>` — заголовки запроса по умолчанию.
+- `requestDefault: Record<string, any>` — данные запроса по умолчанию.
+- `preparation: (apiFetch: ApiFetch) => Promise<void>` — входной хук.
+- `end: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>` — выходной хук.
+- `timeout: number` — глобальный таймаут в миллисекундах.
 
-### Методы запросов
+## Прокси-архитектура
 
-- `request<T>(pathRequest: string | ApiFetch): Promise<T>` — Основной исполнитель запросов. Принимает строку пути или объект конфигурации `ApiFetch`.
-- `get<T>(request: ApiFetch): Promise<T>` — Отправляет HTTP GET запрос.
-- `post<T>(request: ApiFetch): Promise<T>` — Отправляет HTTP POST запрос.
-- `put<T>(request: ApiFetch): Promise<T>` — Отправляет HTTP PUT запрос.
-- `delete<T>(request: ApiFetch): Promise<T>` — Отправляет HTTP DELETE запрос.
+Класс `Api` работает как **статический прокси**. Все вызовы методов перенаправляются на внутренний `ApiInstance`.
 
-## setConfig
+### Управление экземпляром
 
-Метод `setConfig` позволяет применить несколько параметров конфигурации одновременно с помощью объекта `ApiConfig`:
+Внутренний менеджер хранится в `ServerStorage` под уникальным ключом (`__dxt_api_instance__`). Эта архитектура решает две основные проблемы:
 
-```typescript
-import { Api } from '@dxtmisha/functional'
+1.  **Потокобезопасность в SSR**: Во время рендеринга на стороне сервера `ServerStorage` гарантирует, что каждый входящий запрос имеет свою собственную изолированную конфигурацию и состояние API, предотвращая утечку данных между пользователями.
+2.  **Простота синглтона на клиенте**: На стороне клиента он ведет себя как настоящий синглтон, позволяя настроить API в точке входа и использовать его где угодно без передачи экземпляров.
 
-Api.setConfig({
-  urlRoot: 'https://api.example.com/v1/',
-  headers: { 'Authorization': 'Bearer token123' },
-  requestDefault: { source: 'webapp' },
-  preparation: async (apiFetch) => {
-    console.log('Подготовка:', apiFetch.path)
-  },
-  end: async (response, apiFetch) => {
-    if (response.status === 401) {
-      return { reset: true }
-    }
-    return {}
-  }
-})
-```
+### Делегирование
 
-> **Важно:** Полный список параметров (`ApiFetch`), хуков (Lifecycle Hooks), эмуляции ответов и структуры данных ответа описан в документации базового класса **ApiInstance**.
+Хотя `Api` является предпочтительным интерфейсом для стандартной логики приложения, основная логика (повторы, гидратация, джиттер) находится внутри `ApiInstance`. Для сложных сценариев, включающих несколько базовых URL-адресов или разные наборы заголовков одновременно, вы можете создавать экземпляры `ApiInstance` напрямую.

package/src/media/functional/functional-basic/classes/Api/Api.vi.mdx

@@ -1,78 +1,78 @@
 import {Meta} from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/vi/functional-basic/Classes/Api - Quản lý yêu cầu (Request)'/>
+<Meta title='@dxtmisha/vi/functional-basic/Classes/Api - Quản lý yêu cầu (Static)'/>
 
 # Lớp Api
 
-`Api` là một lớp tĩnh (static wrapper) bao bọc xung quanh một đối tượng `ApiInstance`.
+Lớp `Api` là **Lớp chính (Tĩnh)** và đóng vai trò là điểm truy cập chính để quản lý các yêu cầu HTTP. Nó là một wrapper tĩnh bao quanh một `ApiInstance` được quản lý toàn cục, cung cấp một giao diện singleton sạch sẽ cho các hoạt động mạng tiêu chuẩn.
 
-Mọi phương thức của lớp `Api` đều được tự động ủy quyền (delegate) cho một đối tượng `ApiInstance` chung (global object) bên trong. Điều này cho phép bạn làm việc với các yêu cầu HTTP mà không cần phải tự khởi tạo (instantiate) các đối tượng:
+## Các tính năng chính
 
-```typescript
-import { Api } from '@dxtmisha/functional'
+- **Giao diện tĩnh** — thực hiện các hoạt động HTTP tiêu chuẩn (`GET`, `POST`, v.v.) mà không cần khởi tạo thủ công.
+- **Hook vòng đời toàn cục** — cấu hình việc chuẩn bị và phân tích yêu cầu một lần cho toàn bộ ứng dụng.
+- **Cách ly SSR** — sử dụng `ServerStorage` để quản lý việc cách ly các instance riêng lẻ trong quá trình render phía máy chủ.
+- **Thiết lập đơn giản** — cung cấp phương thức `setConfig` thống nhất để áp dụng nhiều lớp cấu hình cùng một lúc.
 
-// Các lệnh gọi này tương tác với cùng một đối tượng toàn phần (global instance) bên dưới
-Api.setUrl('https://api.example.com/v1/')
-Api.setHeaders({ 'Authorization': 'Bearer token123' })
+## Các phương thức
 
-const data = await Api.get({ path: 'users' })
-```
+### Hành động
 
-## Các phương thức
+Các phương thức để thực hiện các yêu cầu mạng vật lý.
+
+- `request<T>(pathRequest: string | ApiFetch): Promise<T>` — Trình thực thi cốt lõi; chấp nhận một chuỗi đường dẫn hoặc đối tượng cấu hình.
+- `get<T>(request: ApiFetch): Promise<T>` — Gửi yêu cầu GET.
+- `post<T>(request: ApiFetch): Promise<T>` — Gửi yêu cầu POST.
+- `put<T>(request: ApiFetch): Promise<T>` — Gửi yêu cầu PUT.
+- `patch<T>(request: ApiFetch): Promise<T>` — Gửi yêu cầu PATCH.
+- `delete<T>(request: ApiFetch): Promise<T>` — Gửi yêu cầu DELETE.
+
+### Kiểm tra
+
+- `isLocalhost(): boolean` — Kiểm tra xem môi trường hiện tại có phải là máy chủ phát triển cục bộ hay không.
 
-### Truy cập instance
+### Cấu hình
 
-- `getItem(): ApiInstance` — Trả về đối tượng `ApiInstance` nội bộ được sử dụng bởi tất cả các phương thức tĩnh.
+- `setUrl(url: string): void` — Thay đổi URL base của API.
+- `setHeaders(headers: Record<string, string>): void` — Thiết lập các header yêu cầu mặc định.
+- `setRequestDefault(request: Record<string, any>): void` — Thiết lập dữ liệu body yêu cầu mặc định.
+- `setPreparation(callback): void` — Đăng ký một hook để chạy trước mỗi yêu cầu được bật.
+- `setEnd(callback): void` — Đăng ký một hook để chạy sau mỗi phản hồi được bật.
+- `setTimeout(timeout: number): void` — Thay đổi timeout yêu cầu toàn cục.
+- `setConfig(config?: ApiConfig): void` — Áp dụng một đối tượng cấu hình đầy đủ.
 
-### Phương thức thông tin
+### Phụ trợ
 
-- `isLocalhost(): boolean` — Trả về `true` nếu mã đang chạy trên máy chủ phát triển cục bộ.
-- `getStatus(): ApiStatus` — Trả về trình quản lý `ApiStatus` để theo dõi trạng thái và lỗi của yêu cầu cuối cùng.
-- `getResponse(): ApiResponse` — Trả về trình quản lý phản hồi/mô phỏng `ApiResponse`.
-- `getUrl(path: string, api?: boolean): string` — Trả về URL đầy đủ cho yêu cầu. Các trình giữ chỗ động `{locale}`, `{country}`, `{language}` được thay thế tự động.
-- `getBody(request?, method?): string | FormData | undefined` — Trả về dữ liệu cho phần thân (body) của yêu cầu.
-- `getBodyForGet(request, path?, method?): string` — Trả về chuỗi tham số truy vấn (query string) cho phương thức GET.
+- `getStatus(): ApiStatus` — Truy cập trình quản lý trạng thái cho yêu cầu cuối cùng.
+- `getResponse(): ApiResponse` — Truy cập trình quản lý phản hồi/mô phỏng.
+- `getHydration(): ApiHydration` — Truy cập trình quản lý hydration.
+- `getHydrationScript(): string` — Trả về khối script để hydration từ SSR sang client.
+- `getUrl(path: string, api?: boolean): string` — Trả về URL đã được phân giải đầy đủ với các token bản địa hóa.
+- `getBody(request?, method?): string | FormData | undefined` — Chuẩn bị body yêu cầu.
+- `getBodyForGet(request, path?, method?): string` — Chuẩn bị chuỗi truy vấn (query string).
+- `getItem(): ApiInstance` — Trả về đối tượng `ApiInstance` cơ sở.
 
-### Phương thức cấu hình
+## Các kiểu dữ liệu (Types)
 
-Tất cả các phương thức cấu hình đều trả về chính lớp `Api` để hỗ trợ chuỗi lệnh (chaining):
+### ApiConfig
 
-- `setUrl(url: string): Api` — Đặt URL cơ sở cho tất cả các yêu cầu.
-- `setHeaders(headers: Record<string, string>): Api` — Đặt các headers mặc định cho tất cả các yêu cầu.
-- `setRequestDefault(request: Record<string, any>): Api` — Đặt dữ liệu yêu cầu mặc định được hợp nhất vào mọi thân yêu cầu (request body).
-- `setPreparation(callback): Api` — Đặt hàm callback được thực thi trước mỗi yêu cầu.
-- `setEnd(callback): Api` — Đặt hàm callback được thực thi sau mỗi yêu cầu.
-- `setConfig(config?: ApiConfig): Api` — Áp dụng toàn bộ đối tượng cấu hình cùng một lúc (`urlRoot`, `headers`, `requestDefault`, `preparation`, `end`).
+- `urlRoot: string` — URL base cho API.
+- `headers: Record<string, string>` — các header yêu cầu mặc định.
+- `requestDefault: Record<string, any>` — dữ liệu yêu cầu mặc định.
+- `preparation: (apiFetch: ApiFetch) => Promise<void>` — hook đầu vào (entry hook).
+- `end: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>` — hook đầu ra (exit hook).
+- `timeout: number` — timeout toàn cục tính bằng mili giây.
 
-### Phương thức yêu cầu
+## Kiến trúc Proxy
 
-- `request<T>(pathRequest: string | ApiFetch): Promise<T>` — Trình thực thi yêu cầu chính. Chấp nhận chuỗi đường dẫn hoặc đối tượng cấu hình `ApiFetch`.
-- `get<T>(request: ApiFetch): Promise<T>` — Gửi yêu cầu HTTP GET.
-- `post<T>(request: ApiFetch): Promise<T>` — Gửi yêu cầu HTTP POST.
-- `put<T>(request: ApiFetch): Promise<T>` — Gửi yêu cầu HTTP PUT.
-- `delete<T>(request: ApiFetch): Promise<T>` — Gửi yêu cầu HTTP DELETE.
+Lớp `Api` hoạt động như một **Proxy tĩnh**. Tất cả các lệnh gọi phương thức đều được chuyển hướng đến một `ApiInstance` nội bộ.
 
-## setConfig
+### Quản lý Instance
 
-Phương thức `setConfig` cho phép áp dụng nhiều tùy chọn cấu hình cùng lúc bằng đối tượng `ApiConfig`:
+Trình quản lý nội bộ được lưu trữ trong `ServerStorage` bằng một khóa duy nhất (`__dxt_api_instance__`). Kiến trúc này giải quyết hai vấn đề lớn:
 
-```typescript
-import { Api } from '@dxtmisha/functional'
+1.  **An toàn luồng trong SSR**: Trong quá trình render phía máy chủ, `ServerStorage` đảm bảo rằng mỗi yêu cầu đến có cấu hình và trạng thái API riêng biệt, ngăn chặn rò rỉ dữ liệu giữa các người dùng.
+2.  **Sự đơn giản của Singleton trên Client**: Ở phía client, nó hoạt động như một singleton thực sự, cho phép bạn cấu hình API tại điểm truy cập và sử dụng nó ở bất cứ đâu mà không cần truyền instance.
 
-Api.setConfig({
-  urlRoot: 'https://api.example.com/v1/',
-  headers: { 'Authorization': 'Bearer token123' },
-  requestDefault: { source: 'webapp' },
-  preparation: async (apiFetch) => {
-    console.log('Chuẩn bị:', apiFetch.path)
-  },
-  end: async (response, apiFetch) => {
-    if (response.status === 401) {
-      return { reset: true }
-    }
-    return {}
-  }
-})
-```
+### Ủy quyền (Delegation)
 
-> **Quan trọng:** Toàn bộ danh sách đầy đủ về các tùy chọn `ApiFetch`, hook vòng đời, mô phỏng phản hồi và cấu trúc dữ liệu phản hồi đã được ghi chép chi tiết tại tài liệu gốc của lớp **ApiInstance**.
+Mặc dù `Api` là giao diện được ưu tiên cho logic ứng dụng tiêu chuẩn, nhưng logic cốt lõi (thử lại, logic hydration, jitter) nằm bên trong `ApiInstance`. Đối với các tình huống nâng cao liên quan đến nhiều URL base hoặc các bộ header khác nhau đồng thời, bạn có thể khởi tạo `ApiInstance` trực tiếp.