@dxtmisha/wiki 0.39.7 → 0.56.0

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

@@ -10,11 +10,13 @@ Nó kết hợp chặt chẽ với các lớp phụ thuộc: `ApiStatus`, `ApiRe
 
 ## Các tính năng chính
 
-- **Các phương thức CRUD** — các bí danh (alias) tiện lợi `get`, `post`, `put`, `delete` để thao tác với các yêu cầu HTTP
+- **Các phương thức CRUD** — các bí danh (alias) tiện lợi `get`, `post`, `put`, `patch`, `delete` để thao tác với các yêu cầu HTTP
 - **Cấu hình toàn cục (Global Configuration)** — thiết lập URL cơ sở (base URL), header và tham số mặc định cho tất cả yêu cầu
 - **Các Hook vòng đời (Lifecycle Hooks)** — khả năng xác định các hàm callback được thực thi trước (`setPreparation`) và sau (`setEnd`) mỗi yêu cầu
 - **Theo dõi trạng thái** — truy cập trạng thái và lỗi của yêu cầu cuối cùng thông qua `ApiStatus`
-- **Bộ nhớ đệm & Giả lập dữ liệu (Caching & Emulation)** — quản lý các phản hồi mẫu (mock responses) thông qua `ApiResponse`
+- **Hydration** — chuyển dữ liệu từ máy chủ sang máy khách (SSR) để hiển thị tức thì
+- **Bộ nhớ đệm (Caching)** — lưu các phản hồi trong bộ nhớ trong hoặc ngoài thông qua `ApiCache`
+- **Giả lập phản hồi** — quản lý linh hoạt dữ liệu giả thông qua `ApiResponse`
 - **Tự động phân tích dữ liệu** — tự động chuyển đổi định dạng body thành JSON/FormData và trích xuất dữ liệu từ các phản hồi JSON
 - **Định vị khu vực (Geolocation)** — tự động thay thế các tham số `{locale}`, `{country}`, `{language}` trong đường dẫn yêu cầu
 
@@ -36,9 +38,11 @@ Thực thể `ApiInstance` có thể được cấu hình trong quá trình kh
 - `loadingClass?: LoadingInstance` — thực thể của trình quản lý chỉ báo tải (mặc định: `Loading.getItem()`).
 - `errorCenterClass?: ErrorCenterInstance` — thực thể của trung tâm lỗi để kích hoạt các sự kiện (mặc định: `ErrorCenter.getItem()`).
 
-## Phương thức Gọi Tín Hiệu (API Calling Methods)
+## Các phương thức
 
-### `request`
+### Hành động
+
+#### `request`
 
 Thuật toán kích hoạt thực hiện tác vụ chính trên fetch thuần mạng vật lý. Nếu cung cấp trong ngữ cảnh string cô đơn mà không phải Object, nó kích hoạt hệ phân tán luồng định sẵn cài cắm theo kiểu `GET`.
 Khi hệ thống bối rối hoặc gọi trượt giao thức mạng (như lỗi nội bộ 500 status), chương trình chủ lực sẽ trực xuất luôn mã lỗi (`throw e`), qua đó giúp lập trình viên dùng `try/catch` thu hồi lệnh dễ dàng. Khi máy chủ trả lại tệp Object thuộc chuẩn JSON, gói nhận dạng trạng thái lệnh (`statusObject`) sẽ đắp kèm thành khối liền mạch trước khi đẩy về UI.
@@ -48,72 +52,46 @@ Khi hệ thống bối rối hoặc gọi trượt giao thức mạng (như lỗ
 
 **Trả về:** `Promise<ApiData<T>>` — giao diện format hoàn thiện của phản hồi mã hóa (decoded). Bao gồm các thông số biến (`data`, `statusObject`...) đi kèm nếu server nhả form dữ liệu có bọc.
 
-### `get`
-
-Bật một khối yêu cầu API bằng giao thức `GET` theo cơ chế gỡ rối và ép đầu cung dữ liệu thông số search URL lên cấu trúc HTTP tự động.
-
-**Tham số:**
-- `request: ApiFetch` — Các thông số truy xuất của lệnh.
-
-**Trả về:** `Promise<T>`
-
-### `post`
-
-Giao chuyển chùm truy vấn truyền động REST/GraphQL bằng luồng định tuyến tuân thủ HTTP `POST`.
-
-**Tham số:**
-- `request: ApiFetch` — Cơ sở cấu hình bao bọc giao diện, kèm tham số URL hiện chỉ định.
-
-**Trả về:** `Promise<T>`
-
-### `put`
-
-Trình bày khả năng hiệu chỉnh một khối dữ liệu thông qua cấu hình thao tác tiêu chuẩn ở hệ phương án `PUT`.
+### Các phương thức rút gọn
 
-**Tham số:**
-- `request: ApiFetch` — Các lựa chọn query dẫn đường backend map.
-
-**Trả về:** `Promise<T>`
-
-### `delete`
-
-Phát tín hiệu dọn dẹp theo phân hóa truyền thống ở nhát kích HTTP `DELETE`.
-
-**Tham số:**
-- `request: ApiFetch` — Bọc thông số liên kết arguments format.
+- `get(request: ApiFetch): Promise<T>` — Bật một khối yêu cầu API bằng giao thức `GET` theo cơ chế gỡ rối và ép đầu cung dữ liệu thông số search URL lên cấu trúc HTTP tự động.
+- `post(request: ApiFetch): Promise<T>` — Giao chuyển chùm truy vấn truyền động REST/GraphQL bằng luồng định tuyến tuân thủ HTTP `POST`.
+- `put(request: ApiFetch): Promise<T>` — Trình bày khả năng hiệu chỉnh một khối dữ liệu thông qua cấu hình thao tác tiêu chuẩn ở hệ phương án `PUT`.
+- `patch(request: ApiFetch): Promise<T>` — Kích hoạt việc cập nhật từng phần thông tin (partial update) của tài nguyên thông qua phương thức HTTP `PATCH`.
+- `delete(request: ApiFetch): Promise<T>` — Phát tín hiệu dọn dẹp theo phân hóa truyền thống ở nhát kích HTTP `DELETE`.
 
-**Trả về:** `Promise<T>`
-
-## Các phương thức khởi tạo Interface
+### Kiểm tra
 
 - `isLocalhost(): boolean` — Kiểm tra xem mã có đang thực thi trên một máy chủ phát triển localhost không.
 - `getStatus(): ApiStatus` — Trả về trình quản lý trạng thái `ApiStatus` để theo dõi mã trạng thái HTTP.
 - `getResponse(): ApiResponse` — Trả về trình quản lý bộ giả lập và phản hồi `ApiResponse`.
 
-## Cấu hình hệ thống (Configuration)
+### Cấu hình
 
-Hỗ trợ phương pháp nối chuỗi (chaining methods) trả về đối tượng `ApiInstance` mấu chốt):
+Hỗ trợ phương pháp nối chuỗi (chaining methods) trả về đối tượng `ApiInstance` mấu chốt:
 - `setHeaders(headers: Record<string, string>): this` — Áp dụng một thư mục Header chuẩn cho toàn hệ thống.
 - `setRequestDefault(request: Record<string, any>): this` — Đưa toàn bộ thông số tham số mặc định chuẩn vào mạng.
 - `setUrl(url: string): this` — Ghi đè định danh URL mặc định nhánh server API.
 - `setPreparation(callback: (apiFetch: ApiFetch) => Promise<void>): this` — Thiết lập vòng lặp hook _ngay trước_ thời khắc thao tác diễn ra.
 - `setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this` — Thiết lập vòng lặp hook _sau_ khi tín hiệu mạng phản hồi trả về.
+- `setOrigin(origin: string): this` — Thiết lập nguồn (giao thức và tên miền) cho URL base.
 
-## Chuẩn bị gửi thông tin (Request Preparation)
+### Phụ trợ
 
 - `getUrl(path: string, api?: boolean): string` — Tạo ra đường dẫn API đầy đủ, tự thay thế thẻ định danh quốc gia `{locale}`, `{country}` v.v...
+- `getOrigin(): string` — Trả về URL base đã kết hợp với đường dẫn API.
 - `getBody(request?: ApiFetch['request'], method?: string): string | FormData | undefined` — Hoán đổi tài liệu để form nạp JSON hoặc `FormData`.
 - `getBodyForGet(request: ApiFetch['request'], path?: string, method?: string): string` — Hoàn trả dữ liệu params cấu hình chuẩn cho thanh Search URL `GET`.
 
 ## Đối tượng ApiFetch
 
-`ApiFetch` là đối tượng cấu hình chính được truyền vào các phương thức `request`, `get`, `post`, `put`, `delete`. Tất cả các trường đều là tùy chọn:
+`ApiFetch` là đối tượng cấu hình chính được truyền vào các phương thức `request`, `get`, `post`, `put`, `patch`, `delete`. Tất cả các trường đều là tùy chọn:
 
 - `path?: string` — đường dẫn đến endpoint tương đối với URL cơ sở (ví dụ: `'users/list'`).
 - `pathFull?: string` — URL đầy đủ của yêu cầu. Nếu có, sẽ bỏ qua `api` và `path`.
 - `api?: boolean` — có thêm URL cơ sở vào trước `path` không. Mặc định: `true`.
-- `method?: ApiMethod` — phương thức HTTP (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`). Mặc định: `'GET'`.
-- `request?: FormData | Record<string, any> | string` — nội dung yêu cầu (POST/PUT) hoặc tham số query (GET). Được gửi dưới dạng JSON hoặc `FormData`.
+- `method?: ApiMethod` — phương thức HTTP (`'GET'`, `'POST'`, `'PUT'`, `'PATCH'`, `'DELETE'`). Mặc định: `'GET'`.
+- `request?: FormData | Record<string, any> | string` — nội dung yêu cầu (POST/PUT/PATCH) hoặc tham số query (GET). Được gửi dưới dạng JSON hoặc `FormData`.
 - `headers?: Record<string, string> | null` — tiêu đề bổ sung. `null` — tắt tất cả tiêu đề.
 - `type?: string` — giá trị `Content-Type`. Mặc định: `'application/json;charset=UTF-8'`.
 - `auth?: boolean` — thêm tiêu đề xác thực.
@@ -128,7 +106,8 @@ Hỗ trợ phương pháp nối chuỗi (chaining methods) trả về đối tư
 - `timeout?: number` — thời gian chờ yêu cầu tính bằng mili giây. Mặc định: `16000`ms.
 - `controller?: AbortController` — bộ điều khiển để hủy yêu cầu.
 - `retry?: number` — số lần thử lại khi thất bại.
-- `retryDelay?: number` — độ trễ cơ bản giữa các lần thử lại tính bằng mili giây. Mặc định: `64`ms.
+- `retryDelay?: number` — độ trễ cơ bản giữa các lần thử lại tính bằng mili giây. Mặc định: `64`ms. Jitter được sử dụng để ngăn chặn vấn đề thundering herd.
+- `endResetLimit?: number` — giới hạn đệ quy thử lại thông qua `setEnd` với `reset: true`. Mặc định: `8`.
 
 ## Cấu trúc dữ liệu phản hồi
 
@@ -215,7 +194,7 @@ Phương thức `setEnd` thiết lập một hàm callback được gọi sau kh
 - `apiFetch: ApiFetch` — đối tượng tham số đã dùng để thực hiện yêu cầu.
 
 **Trả về:** `Promise<ApiPreparationEnd>`. Đối tượng kết quả có thể chứa các trường sau:
-- `reset?: boolean` — nếu được đặt thành `true`, thư viện sẽ hủy chuỗi hiện tại và **thực hiện lại yêu cầu** (đệ quy) sau một khoảng trễ ngẫu nhiên (xem `retryDelay`). Toàn bộ quá trình chuẩn bị và thực thi sẽ được khởi động lại. Việc này được dùng để tự động xử lý quyền truy cập đã được làm mới.
+- `reset?: boolean` — nếu được đặt thành `true`, thư viện sẽ hủy chuỗi hiện tại và **thực hiện lại yêu cầu** (đệ quy) sau một khoảng trễ ngẫu nhiên (xem `retryDelay`). Toàn bộ quá trình chuẩn bị và thực thi sẽ được khởi động lại. Việc này được dùng để tự động xử lý quyền truy cập đã được làm mới. Quá trình đệ quy này được giới hạn bởi `endResetLimit` (mặc định: 8).
 - `data?: any` — cho phép bạn ghi đè dữ liệu mà phương thức API trả về. Nếu trường này được chỉ định, cơ chế đọc phản hồi tiêu chuẩn (JSON/văn bản) sẽ bị bỏ qua.
 
 ```javascript
@@ -245,7 +224,82 @@ Bạn có thể tắt chọn lọc các hook toàn cục trong đối tượng `
 - `globalPreparation: false` — bỏ qua việc thực thi hook `setPreparation`.
 - `globalEnd: false` — bỏ qua việc thực thi hook `setEnd`.
 
-## Giả lập phản hồi (ApiResponse)
+
+## Hydration
+
+
+Hydration là một cơ chế để chuyển dữ liệu thu được trong quá trình Server-Side Rendering (SSR) sang phía client. Điều này giúp tránh việc thực hiện lại các yêu cầu mạng tương tự ngay sau khi trang được tải trong trình duyệt, giúp tăng tốc độ hiển thị và giảm tải cho máy chủ.
+
+### Cách thức hoạt động
+
+1. **Phía máy chủ (SSR):**
+   - Tất cả các yêu cầu đã thực hiện (thường là phương thức `GET` với `global: true`) sẽ tự động được lưu vào danh sách hydration.
+   - Sau khi hoàn tất tạo trang, cần gọi phương thức `api.getHydrationScript()` và chèn chuỗi kết quả vào mẫu HTML (thường là ở cuối thẻ `<body>`).
+
+2. **Phía client (Trình duyệt):**
+   - Khi tạo một instance `ApiInstance`, nó sẽ tự động tìm kiếm script hydration trên trang.
+   - Dữ liệu tìm thấy sẽ được tải vào hệ thống và được thay thế cho lần gọi đầu tiên của các yêu cầu tương tự.
+   - Nhờ đó, mã phía client nhận được dữ liệu ngay lập tức mà không cần chờ phản hồi từ mạng.
+
+### Ví dụ sử dụng (SSR)
+
+```javascript
+// Trên máy chủ
+const api = new ApiInstance();
+await api.get({ path: 'settings' });
+
+// Trong mẫu trang (ví dụ: ở cuối thẻ body)
+// Phương thức trả về chuỗi: <script id="__ui:api:hydration:id__" type="application/json">[...]</script>
+const hydrationScript = api.getHydrationScript();
+```
+
+
+## Bộ nhớ đệm
+
+Thư viện cung cấp cơ chế bộ nhớ đệm (caching) tích hợp cho các phản hồi, cho phép bạn lưu kết quả yêu cầu trong bộ nhớ hoặc trong bộ nhớ ngoài (ví dụ: `LocalStorage`).
+
+### Các tính năng chính
+
+- **Thời gian sống (TTL)** — đối với mỗi yêu cầu, bạn có thể chỉ định thời gian hiệu lực của bộ nhớ đệm tính bằng giây.
+- **Bộ nhớ ngoài** — khả năng tích hợp với bất kỳ bộ lưu trữ dữ liệu bất đồng bộ nào.
+- **Tự động làm sạch** — dữ liệu cũ sẽ bị xóa khỏi bộ nhớ khi vượt quá giới hạn.
+
+### Thiết lập bộ nhớ ngoài
+
+Mặc định, bộ nhớ đệm chỉ hoạt động trong RAM và sẽ bị xóa khi tải lại trang. Để lưu dữ liệu lâu dài, bạn cần khởi tạo `ApiCache` với các listener của riêng mình (ví dụ: sử dụng `LocalStorage` hoặc `IndexedDB`):
+
+```javascript
+import { ApiCache, DataStorage } from '@dxtmisha/functional';
+
+// Ví dụ về khởi tạo bằng LocalStorage qua trình bọc DataStorage
+ApiCache.init(
+  async (key) => DataStorage.get(key),
+  async (key, value) => {
+    DataStorage.set(key, value);
+    return true;
+  },
+  async (key) => {
+    DataStorage.remove(key);
+    return true;
+  }
+);
+```
+
+### Sử dụng trong các yêu cầu
+
+Để bật tính năng bộ nhớ đệm, chỉ cần truyền thời gian tính bằng giây vào trường `cache` của đối tượng `ApiFetch`:
+
+```javascript
+// Lưu bộ nhớ đệm trong 1 giờ (3600 giây)
+const data = await api.get({
+  path: 'catalog/list',
+  cache: 3600
+});
+```
+
+Nếu dữ liệu có trong bộ nhớ đệm và thời gian sống của nó chưa hết hạn, thư viện sẽ trả về dữ liệu đó ngay lập tức mà không thực hiện yêu cầu thực tế tới máy chủ.
+
+## Giả lập phản hồi
 
 Trình quản lý giả lập `ApiResponse` (có thể truy cập thông qua `api.getResponse()`) cho phép cấu hình các phản hồi mẫu (mock) cho những đường dẫn cụ thể. Hệ thống này vô cùng hữu ích khi phát triển giao diện (UI frontend) trước khi có API backend hoàn chỉnh hoặc khi cần viết test.
 
@@ -255,7 +309,7 @@ Phương thức `add` nhận một đối tượng dạng `ApiResponseItem` ho
 
 **Các trường quan trọng trong `ApiResponseItem`:**
 - `path` — Dạng chuỗi (String - khớp chính xác) hoặc Biểu thức chính quy (`RegExp`) dùng để chặn đường dẫn (URL) cụ thể.
-- `method` — Phương thức HTTP (`ApiMethodItem.get`, `post`, v.v...).
+- `method` — Phương thức HTTP (`ApiMethodItem.get`, `post`, `put`, `patch`, v.v...).
 - `request` — (Tùy chọn) Bộ lọc theo tải trọng body. Bạn có thể dùng chuỗi đánh dấu đặc biệt `'*any'` để vô hiệu hoá bộ kiểm tra nội dung và bắt mọi yêu cầu gửi đến đường dẫn này.
 - `response` — Một đối tượng dữ liệu tĩnh _hoặc_ một hàm khởi tạo (factory function) `(request) => any` dùng để tạo câu trả lời tự động dựa trên tải trọng yêu cầu gửi đến.
 - `disable` — (Tùy chọn) Vô hiệu hóa mock này (boolean hoặc callback).

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

@@ -4,40 +4,58 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 # ApiPreparation Class
 
-A class specifically designed to handle tasks and side effects immediately running before and after an API request execution. It serves to intercept requests globally via tracking hooks (`callback` and `callbackEnd`), perform state manipulations, or trigger global logic like loading indicators.
+A specialized class designed to handle tasks and side effects immediately before and after an API request execution. It serves to intercept requests globally via tracking hooks, enabling state manipulation or triggering of global logic like token refreshes or logging.
+
+> `ApiPreparation` is an **auxiliary class**, designed for managing request lifecycles. In most cases, it is recommended to interact with hooks through the `setPreparation` and `setEnd` methods of the main `Api` instance.
 
 ## Key Features
 
-- **Pre-request Execution** — hook into the API lifecycle immediately before the actual `fetch` call is made.
-- **Post-request Analysis** — execute logic exactly after a request completes, with proper access to the `Response` object and the original request configuration.
-- **Concurrency Control** — ensures overlapping hooks are resolved collectively without collision.
-- **Data Injection** — post-request hooks optionally return data or a `reset` flag that can manipulate downstream handlers.
+- **Sequential Execution** — ensures that preparation hooks resolve one at a time, preventing collisions during concurrent operations (e.g., duplicate token refreshes).
+- **Global Interception** — provides a single point of entry and exit for all network traffic initiated by its parent manager.
+- **Request Replay** — post-request hooks can signal the system to automatically retry a request after state changes.
 
-## Initialization
+## Methods
 
-To initialize the object, call the `ApiPreparation()` constructor.
+### Action
 
-```typescript
-import { ApiPreparation } from '@dxtmisha/functional'
+#### `make`
 
-// 1. Simple initialization
-const preparation = new ApiPreparation()
+Executes the registered preparation callback. If another preparation is currently in progress, it waits for it to complete.
 
-// 2. Setting pre-request callback
-preparation.set(async (apiFetch) => {
-  console.log('Preparing request to:', apiFetch.path)
-})
+**Parameters:**
+- `active: boolean` — Whether the hook is enabled for the current request.
+- `apiFetch: ApiFetch` — The configuration for the upcoming request.
 
-// 3. Setting post-request callback
-preparation.setEnd(async (query, apiFetch) => {
-  console.log('Request finished with status:', query.status)
-  return { reset: false }
-})
-```
+**Returns:** `Promise<void>`
 
-## Methods
+#### `makeEnd`
+
+Executes the registered analysis callback after a request completes.
+
+**Parameters:**
+- `active: boolean` — Whether the hook is enabled for the current request.
+- `query: Response` — The native Fetch API response object.
+- `apiFetch: ApiFetch` — The configuration used for the request.
+
+**Returns:** `Promise<ApiPreparationEnd>` — An object controlling the next steps (e.g., reset, data injection).
+
+### Configuration
+
+- `set(callback: (apiFetch: ApiFetch) => Promise<void>): this` — Registers a function to run before every enabled request.
+- `setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this` — Registers a function to run after every enabled response.
+
+## Types
+
+#### `ApiPreparationEnd`
+Result of the analysis hook execution.
+- `reset?: boolean` — If true, the request will be aborted and restarted.
+- `data?: any` — Custom data to pass along.
+
+## Guide: Mechanics of Hooks
+
+The following rules and conditions define how the preparation system synchronizes and manages lifecycle hooks:
 
-- `make(active: boolean, apiFetch: ApiFetch): Promise<void>` — Executes the preparation callback before executing the request.
-- `makeEnd(active: boolean, query: Response, apiFetch: ApiFetch): Promise<ApiPreparationEnd>` — Executes analysis logically after the request finishes.
-- `set(callback: (apiFetch: ApiFetch) => Promise<void>): this` — Connects a callback function triggered right before a request execution.
-- `setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this` — Connects a callback function executed after request termination.
+- **Synchronization** — the system uses a polling mechanism (160ms interval) to ensure that only one `setPreparation` hook executes at a time. If multiple requests start concurrently, subsequent calls will wait up to 32 polling attempts (~5 seconds) for the first one to finish.
+- **Context Injection** — the `apiFetch` object is passed to the hooks by reference. Modifying its properties (like headers or request body) inside `setPreparation` directly affects the physical network call that follows.
+- **Flow Control (Reset)** — the `setEnd` hook can return `{ reset: true }`. When this flag is detected, the `ApiInstance` will abort the current request chain and immediately restart it from the preparation phase. This is primarily used for silent, automatic token refreshing.
+- **Execution Scope** — hooks only run if they are explicitly enabled in the request configuration. By default, `globalPreparation` and `globalEnd` are set to true in `ApiFetch`.

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

@@ -1,43 +1,61 @@
 import {Meta} from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/ru/functional-basic/Classes/ApiPreparation - Подготовка API запросов'/>
+<Meta title='@dxtmisha/ru/functional-basic/Classes/ApiPreparation - Подготовка запросов API'/>
 
 # Класс ApiPreparation
 
-Класс, специально разработанный для обработки задач и побочных эффектов непосредственно до и после выполнения API-запроса. Представляет собой хуки (`callback` и `callbackEnd`) для перехвата запросов, выполнения манипуляций или запуска глобальной логики, такой как индикаторы загрузки.
+Специализированный класс, предназначенный для обработки задач и побочных эффектов непосредственно перед и после выполнения API-запроса. Он служит для глобального перехвата запросов через хуки, позволяя манипулировать состоянием или запускать глобальную логику, такую как обновление токенов или логирование.
+
+> `ApiPreparation` является **вспомогательным классом**, предназначенным для управления жизненным циклом запросов. В большинстве случаев рекомендуется взаимодействовать с хуками через методы `setPreparation` и `setEnd` основного инстанса `Api`.
 
 ## Ключевые особенности
 
-- **Выполнение перед запросом** — хук в жизненном цикле API непосредственно перед фактическим вызовом `fetch`.
-- **Анализ после запроса** — выполнение логики сразу после завершения запроса с доступом к объекту `Response` и конфигурации исходного запроса.
-- **Контроль параллелизма** — гарантирует корректное разрешение перекрывающихся хуков без конфликтов.
-- **Внедрение данных** — хуки после запроса могут возвращать данные или флаг `reset`, которые могут повлиять на общую обработку ответа API.
+- **Последовательное выполнение** — гарантирует, что хуки подготовки выполняются по одному, предотвращая коллизии при параллельных операциях (например, дублирование запросов на обновление токена).
+- **Глобальный перехват** — предоставляет единую точку входа и выхода для всего сетевого трафика, инициируемого родительским менеджером.
+- **Повтор запроса** — хуки после запроса могут сигнализировать системе о необходимости автоматического повтора запроса после изменения состояния.
 
-## Инициализация
+## Методы
 
-Для инициализации объекта вызовите конструктор `ApiPreparation()`.
+### Действие
 
-```typescript
-import { ApiPreparation } from '@dxtmisha/functional'
+#### `make`
 
-// 1. Простая инициализация
-const preparation = new ApiPreparation()
+Выполняет зарегистрированный коллбэк подготовки. Если другая подготовка уже выполняется, метод ожидает её завершения.
 
-// 2. Установка колбэка перед запросом
-preparation.set(async (apiFetch) => {
-  console.log('Подготовка запроса к:', apiFetch.path)
-})
+**Параметры:**
+- `active: boolean` — Активен ли хук для текущего запроса.
+- `apiFetch: ApiFetch` — Конфигурация предстоящего запроса.
 
-// 3. Установка колбэка после запроса
-preparation.setEnd(async (query, apiFetch) => {
-  console.log('Запрос завершен со статусом:', query.status)
-  return { reset: false }
-})
-```
+**Возвращает:** `Promise<void>`
 
-## Методы
+#### `makeEnd`
+
+Выполняет зарегистрированный коллбэк анализа после завершения запроса.
+
+**Параметры:**
+- `active: boolean` — Активен ли хук для текущего запроса.
+- `query: Response` — Нативный объект ответа Fetch API.
+- `apiFetch: ApiFetch` — Конфигурация, использованная для запроса.
+
+**Возвращает:** `Promise<ApiPreparationEnd>` — Объект, управляющий дальнейшими шагами (например, сброс или подмена данных).
+
+### Конфигурация
+
+- `set(callback: (apiFetch: ApiFetch) => Promise<void>): this` — Регистрирует функцию для запуска перед каждым включенным запросом.
+- `setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this` — Регистрирует функцию для запуска после каждого включенного ответа.
+
+## Типы
+
+#### `ApiPreparationEnd`
+Результат выполнения хука анализа.
+- `reset?: boolean` — Если true, запрос будет прерван и перезапущен.
+- `data?: any` — Произвольные данные.
+
+## Руководство: Механика хуков
+
+Следующие правила и условия определяют, как система подготовки синхронизирует и управляет хуками жизненного цикла:
 
-- `make(active: boolean, apiFetch: ApiFetch): Promise<void>` — Выполняет логику подготовки перед выполнением запроса.
-- `makeEnd(active: boolean, query: Response, apiFetch: ApiFetch): Promise<ApiPreparationEnd>` — Выполняет анализ после завершения запроса.
-- `set(callback: (apiFetch: ApiFetch) => Promise<void>): this` — Устанавливает колбэк, который запускается перед запросом.
-- `setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this` — Устанавливает колбэк, который запускается после завершения запроса.
+- **Синхронизация** — система использует механизм опроса (интервал 160 мс), чтобы гарантировать, что одновременно выполняется только один хук `setPreparation`. Если одновременно запускаются несколько запросов, последующие вызовы будут ждать до 32 попыток опроса (~5 секунд), пока первый не завершится.
+- **Инъекция контекста** — объект `apiFetch` передается в хук по ссылке. Изменение его свойств (таких как заголовки или тело запроса) внутри `setPreparation` напрямую влияет на последующий сетевой вызов.
+- **Управление потоком (Reset)** — хук `setEnd` может вернуть `{ reset: true }`. Когда этот флаг обнаружен, `ApiInstance` прервет текущую цепочку запроса и немедленно перезапустит её с фазы подготовки. Это в основном используется для прозрачного автоматического обновления токенов.
+- **Область выполнения** — хуки запускаются только в том случае, если они явно включены в конфигурации запроса. По умолчанию `globalPreparation` и `globalEnd` в `ApiFetch` установлены в true.

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

@@ -4,40 +4,58 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 # Lớp ApiPreparation
 
-Một lớp được thiết kế đặc biệt để xử lý các tác vụ và hiệu ứng phụ (side effects) chạy ngay trước và sau khi thực thi một yêu cầu API. Nó đóng vai trò cung cấp các siêu liên kết điểm chốt (`callback` và `callbackEnd`) để chặn hoặc theo dõi các yêu cầu, thực hiện thao tác hay kích hoạt xử lý giao diện như đồ họa tải trang.
+Một lớp chuyên dụng được thiết kế để xử lý các tác vụ và hiệu ứng phụ ngay trước và sau khi thực thi một yêu cầu API. Nó phục vụ việc chặn các yêu cầu trên toàn cục thông qua các hook theo dõi, cho phép thao tác trạng thái hoặc kích hoạt logic toàn cục như làm mới token hoặc ghi log.
+
+> `ApiPreparation` là một **lớp bổ trợ** (auxiliary class), được thiết kế để quản lý vòng đời yêu cầu. Trong hầu hết các trường hợp, bạn nên tương tác với các hook thông qua các phương thức `setPreparation` và `setEnd` của thực thể `Api` chính.
 
 ## Các tính năng chính
 
-- **Thực thi trước yêu cầu (Pre-request Execution)** — can thiệp vào vòng đời API ngay trước thời điểm tiến hành gọi `fetch` vật lý thực tế.
-- **Phân tích sau yêu cầu (Post-request Analysis)** — kích hoạt chạy logic ngay khi yêu cầu truy vấn hoàn tất, có khả năng kết nối tới các thông số `Response` trả về cộng với cấu hình truy vấn ban đầu.
-- **Kiểm soát động (Concurrency Control)** — đảm bảo các hook chồng chéo được xử lý hợp lý mà không bị tắt nghẽn.
-- **Móc nối dữ liệu (Data Injection)** — các hook nối mạng có đặc quyền trả về dữ liệu hoặc một cờ tín hiệu `reset` nhằm thao túng hay ngắt phiên xử lý phản hồi API toàn cục sau đó.
+- **Thực thi tuần tự** — đảm bảo rằng các hook chuẩn bị được giải quyết từng cái một, ngăn chặn xung đột trong các hoạt động đồng thời (ví dụ: làm mới token bị trùng lặp).
+- **Chặn luồng toàn cục** — cung cấp một điểm vào và ra duy nhất cho tất cả lưu lượng mạng được khởi tạo bởi trình quản lý cha của nó.
+- **Phát lại yêu cầu** — các hook sau yêu cầu có thể báo hiệu hệ thống tự động thử lại một yêu cầu sau khi trạng thái thay đổi.
 
-## Khởi tạo
+## Các phương thức
 
-Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `ApiPreparation()`.
+### Hành động
 
-```typescript
-import { ApiPreparation } from '@dxtmisha/functional'
+#### `make`
 
-// 1. Khởi tạo đơn giản
-const preparation = new ApiPreparation()
+Thực thi callback chuẩn bị đã đăng ký. Nếu một quá trình chuẩn bị khác đang diễn ra, nó sẽ đợi cho đến khi hoàn thành.
 
-// 2. Thiết lập callback trước yêu cầu
-preparation.set(async (apiFetch) => {
-  console.log('Đang chuẩn bị yêu cầu tới:', apiFetch.path)
-})
+**Tham số:**
+- `active: boolean` — Hook có được bật cho yêu cầu hiện tại hay không.
+- `apiFetch: ApiFetch` — Cấu hình cho yêu cầu sắp tới.
 
-// 3. Thiết lập callback sau yêu cầu
-preparation.setEnd(async (query, apiFetch) => {
-  console.log('Yêu cầu đã hoàn tất với trạng thái:', query.status)
-  return { reset: false }
-})
-```
+**Trả về:** `Promise<void>`
 
-## Các phương thức
+#### `makeEnd`
+
+Thực thi callback phân tích đã đăng ký sau khi một yêu cầu hoàn thành.
+
+**Tham số:**
+- `active: boolean` — Hook có được bật cho yêu cầu hiện tại hay không.
+- `query: Response` — Đối tượng phản hồi Fetch API gốc.
+- `apiFetch: ApiFetch` — Cấu hình đã được sử dụng cho yêu cầu.
+
+**Trả về:** `Promise<ApiPreparationEnd>` — Một đối tượng điều khiển các bước tiếp theo (ví dụ: reset, tiêm dữ liệu).
+
+### Cấu hình
+
+- `set(callback: (apiFetch: ApiFetch) => Promise<void>): this` — Đăng ký một hàm sẽ chạy trước mọi yêu cầu được bật.
+- `setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this` — Đăng ký một hàm sẽ chạy sau mọi phản hồi được bật.
+
+## Các kiểu dữ liệu
+
+#### `ApiPreparationEnd`
+Kết quả thực thi của hook phân tích.
+- `reset?: boolean` — Nếu true, yêu cầu sẽ bị hủy và khởi động lại.
+- `data?: any` — Dữ liệu tùy chỉnh để truyền đi.
+
+## Hướng dẫn: Cơ chế của Hook
+
+Các quy tắc và điều kiện sau đây xác định cách hệ thống chuẩn bị đồng bộ hóa và quản lý các hook vòng đời:
 
-- `make(active: boolean, apiFetch: ApiFetch): Promise<void>` — Thực thi vòng lặp chuẩn bị ngay trước thời khắc truy vấn vận hành.
-- `makeEnd(active: boolean, query: Response, apiFetch: ApiFetch): Promise<ApiPreparationEnd>` — Thực thi tính chất phân tích vòng lặp móc nối sau khi liên kết server đóng băng.
-- `set(callback: (apiFetch: ApiFetch) => Promise<void>): this` — Cách đấu nối một hàm tuỳ chỉnh thiết lập logic chạy tuần tự trước một yêu cầu.
-- `setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this` — Thiết lập một hàm vòng sự kiện được kích hoạt tức thì sau khi một phiên yêu cầu khép lại.
+- **Đồng bộ hóa** — hệ thống sử dụng cơ chế thăm dò (khoảng thời gian 160ms) để đảm bảo rằng chỉ có một hook `setPreparation` thực thi tại một thời điểm. Nếu nhiều yêu cầu bắt đầu đồng thời, các cuộc gọi tiếp theo sẽ đợi tối đa 32 lần thăm dò (~5 giây) để cuộc gọi đầu tiên hoàn thành.
+- **Tiêm ngữ cảnh** — đối tượng `apiFetch` được truyền vào các hook theo dạng tham chiếu. Việc sửa đổi các thuộc tính của nó (như tiêu đề hoặc thân yêu cầu) bên trong `setPreparation` sẽ ảnh hưởng trực tiếp đến lệnh gọi mạng vật lý ngay sau đó.
+- **Điều khiển luồng (Reset)** — hook `setEnd` có thể trả về `{ reset: true }`. Khi cờ này được phát hiện, `ApiInstance` sẽ hủy chuỗi yêu cầu hiện tại và khởi động lại nó ngay lập tức từ giai đoạn chuẩn bị. Điều này chủ yếu được sử dụng để làm mới token tự động và thầm lặng.
+- **Phạm vi thực thi** — các hook chỉ chạy nếu chúng được bật rõ ràng trong cấu hình yêu cầu. Theo mặc định, `globalPreparation` và `globalEnd` được đặt thành true trong `ApiFetch`.

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

@@ -4,7 +4,9 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 # ApiResponse Class
 
-A manager class for intercepting, caching, and emulating API responses. It allows you to intercept outgoing API requests and return predefined mock data instead of triggering actual physical network traffic. Crucial during early UI development, automated unit testing, or offline development environments.
+A manager class for intercepting, caching, and emulating API responses. It allows you to intercept outgoing API requests and return predefined mock data instead of triggering actual physical network traffic.
+
+> `ApiResponse` is an **auxiliary class**, designed for API emulation and mocking. In most cases, it is recommended to register mock responses through the `response` parameter in the global `Api` configuration.
 
 ## Key Features
 
@@ -15,32 +17,68 @@ A manager class for intercepting, caching, and emulating API responses. It allow
 
 ## Initialization
 
-To initialize the object, call the `ApiResponse(requestDefault)` constructor.
+To initialize the object, call the constructor `ApiResponse(requestDefault)`.
 
 **Parameters:**
-- `requestDefault: ApiDefault` — an instance for processing default request parameters.
+- `requestDefault: ApiDefault` — default request class used for configuration and storage.
 
 ```typescript
-import { ApiResponse, ApiDefault } from '@dxtmisha/functional'
-
-// 1. Initialize dependencies
-const apiDefault = new ApiDefault()
-
-// 2. Create emulator instance
-const apiResponse = new ApiResponse(apiDefault)
+import { ApiResponse } from '@dxtmisha/functional-basic'
 
-// 3. Adding a mock response
-apiResponse.add({
-  path: 'user/get',
-  method: 'get',
-  response: { id: 1, name: 'Admin' }
-})
+const apiResponse = new ApiResponse(myApiDefault)
 ```
 
 ## Methods
 
-- `get(path: string = '', method: ApiMethod, request?: ApiFetch['request'], devMode?: boolean): ApiResponseItem | undefined` — Synchronously checks for a global matching cached mock request and returns its configuration.
-- `getList(): (ApiResponseItem & Record<string, any>)[]` — Returns a flat list of all currently registered emulator mock configurations.
-- `add(response: ApiResponseItem | ApiResponseItem[]): this` — Connects routing pathways and attaches fallback mock-response objects to the local registry.
-- `setDevMode(devMode: boolean): this` — Sets the development output log mode on/off natively.
-- `emulator<T>(apiFetch: ApiFetch): Promise<T | undefined>` — Core engine loop validating configurations and executing matched routing latency mock responses recursively.
+### Action
+
+#### `emulator`
+
+Core engine loop that validates request configurations and executes matched routing latency mock responses. This method only runs in DOM environments.
+
+**Parameters:**
+- `apiFetch: ApiFetch` — The properties of the request to emulate.
+
+**Returns:** `Promise<T | undefined>` — The emulated response data.
+
+#### `emulatorAsync`
+
+Synchronous version of the emulator. It returns the mock response immediately without any delay or loading state. This method only runs in DOM environments.
+
+**Parameters:**
+- `apiFetch: ApiFetch` — The properties of the request to emulate.
+
+**Returns:** `T | undefined` — The emulated response data.
+
+### Check
+
+- `get(path: string, method: ApiMethod, request?: ApiFetch['request'], devMode?: boolean): ApiResponseItem | undefined` — Synchronously checks for a matching cached mock request.
+- `getList(): (ApiResponseItem & Record<string, any>)[]` — Returns a list of all registered emulator configurations.
+
+### Configuration
+
+- `add(response: ApiResponseItem | ApiResponseItem[]): this` — Adds mock response objects to the local registry.
+- `setDevMode(devMode: boolean): this` — Toggles the development debug log mode.
+
+## Types
+
+#### `ApiResponseItem`
+An object defining a mock response configuration.
+- `path: string | RegExp` — The matching URL path or pattern.
+- `method: ApiMethod` — The HTTP method (GET, POST, etc.).
+- `response: any | ((request?: any) => any)` — The mock data or a function returning it.
+- `request?: ApiFetch['request'] | '*any'` — Optional request payload to match against.
+- `lag?: boolean` — Whether to simulate network latency.
+- `disable?: any` — Condition to disable the mock (boolean or function).
+- `isForGlobal?: boolean` — Mark as global mock (hidden from getList).
+
+## Guide: API Emulation
+
+The following rules and conditions define how the emulation system intercepts and mocks network requests:
+
+- **Mock Registration** — responses added via `add()` take precedence and are checked before any real network call is initiated.
+- **Matching Criteria** — a mock is triggered only if the path (string or RegExp), HTTP method, and request body all match the configuration.
+- **Body Wildcards** — using `*any` as the request value allows the mock to match any payload, bypassing deep object comparison.
+- **Dynamic Data** — the `response` property can be a function, allowing you to generate dynamic mock data based on the incoming request parameters.
+- **Latency Simulation** — setting `lag: true` adds a random delay (0-2000ms) and triggers the common loading state (`d-response-loading` class on body).
+- **Match Persistence** — by default, an emulator configuration matches only once unless `devMode` is enabled, preventing duplicate mock triggers for the same state.