@dxtmisha/wiki 0.39.7 → 0.56.0

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

@@ -1,78 +1,81 @@
 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.
+- `setOrigin(origin: string): void` — Thay đổi nguồn (giao thức và tên miền) cho URL base.
+- `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.
+- `getOrigin(): string` — Trả về URL base đã kết hợp với đường dẫn API.
+- `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.
+- `origin: string` — giao thức và tên miền cho URL base.
+- `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.

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

@@ -0,0 +1,111 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/ApiCache - API Response Caching'/>
+
+# ApiCache Class
+
+A class for caching API responses. It allows storing query results in memory or an external storage, preventing redundant network calls within a specified period. In the current implementation, caching is active by default only on the server side (SSR) to speed up rendering and reduce API load during concurrent requests.
+
+> `ApiCache` is an **auxiliary class**, designed for low-level cache management. In most cases, it is recommended to interact with caching through the `cache` parameter in `ApiInstance` or the global `Api` object.
+
+## Key Features
+
+- **Automated Key Management** — generates unique cache keys based on request parameters (path, method, body, etc.).
+- **Flexible TTL (Time To Live)** — allows setting the storage duration for each request individually or using a default (24 hours).
+- **SSR Optimization** — prevents unnecessary API calls in the Node.js environment. Disabled by default in the browser (only works if explicitly enabled through configuration parameters).
+- **Listener Support** — ability to connect external storage (e.g., Redis, Nitro Storage) via callback functions.
+- **Background Cleanup** — automatically removes expired entries when accessing the cache.
+
+## Methods
+
+### Action
+
+Methods for managing cache entries.
+
+- `get<T>(key: string): Promise<T | undefined>` — Retrieves a value from the cache.
+- `getByFetch<T>(fetch: ApiFetch): Promise<T | undefined>` — Retrieves a value using request options as the key source.
+- `set<T>(key: string, value: T, age?: number): Promise<void>` — Stores a value in the cache.
+- `setByFetch<T>(fetch: ApiFetch, value: T): Promise<void>` — Stores a value using request options.
+- `remove(key: string): Promise<void>` — Manually removes an entry.
+
+### Configuration
+
+- `init(getListener, setListener, removeListener, cacheStepAgeClearOld?): void` — Configures the cache with storage listeners.
+- `reset(): void` — Clears in-memory items and detaches listeners.
+
+## Types
+
+#### `ApiCacheItem<T>`
+The structure of a cached record.
+- `value: T` — The cached data.
+- `age: number` — TTL in seconds.
+- `cacheAge: number` — Creation timestamp (ms).
+
+#### `ApiCacheList`
+An internal dictionary for in-memory storage fallback.
+- `[key: string]: ApiCacheItem` — Key-value pairs of cached items.
+
+## Initialization and External Storage
+
+By default, `ApiCache` stores records in the process RAM and works only on the server side. While this is fast, it has limitations in production environments:
+1. **Cluster Synchronization**: In a multi-instance setup, caches are not shared between processes.
+2. **Process Restarts**: Memory is cleared whenever the server restarts or a serverless function "cold starts".
+3. **Memory Limits**: Storing large amounts of data in RAM can lead to increased memory consumption.
+
+To solve these issues, you must initialize `ApiCache` with the `init` method, providing listeners that bridge it to an external storage mechanism.
+
+> Important: You must call `ApiCache.init()` during your application's bootstrap phase (before the first API request) to ensure the cache is correctly configured.
+
+### Node.js (Custom Storage)
+
+In a standard Node.js environment, you can use listeners to interact with a centralized database or a persistent cache like Redis.
+
+```typescript
+import { ApiCache } from '@dxtmisha/functional-basic'
+
+// Configuration with storage listeners
+ApiCache.init(
+  // 1. Get data from external storage
+  async (key) => await myExternalStorage.get(key),
+  
+  // 2. Save data to external storage
+  async (key, value) => {
+    await myExternalStorage.put(key, value)
+    return true // Return true to indicate successful external storage
+  },
+  
+  // 3. Remove data from external storage
+  async (key) => {
+    await myExternalStorage.delete(key)
+    return true
+  },
+  
+  // 4. Optional: threshold for background cleanup trigger
+  16384
+)
+```
+
+### Nuxt / Nitro
+
+In Nuxt/Nitro, the recommended approach is to use the built-in `useStorage` helper within a server plugin. This allows you to leverage Redis, FS, or other Nitro-supported storage drivers.
+
+```typescript
+// server/plugins/api-cache.ts
+import { ApiCache } from '@dxtmisha/functional-basic'
+
+export default defineNitroPlugin(() => {
+  const storage = useStorage('cache') // Nitro Cache region
+
+  ApiCache.init(
+    async (key) => await storage.getItem(key),
+    async (key, value) => {
+      await storage.setItem(key, value)
+      return true
+    },
+    async (key) => {
+      await storage.removeItem(key)
+      return true
+    }
+  )
+})
+```

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

@@ -0,0 +1,111 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/ApiCache - Кэширование ответов API'/>
+
+# Класс ApiCache
+
+Класс для кэширования ответов API. Он позволяет сохранять результаты запросов в памяти или во внешнем хранилище, предотвращая избыточные сетевые вызовы в течение заданного периода. В текущей реализации кэширование по умолчанию активно только на стороне сервера (SSR) для ускорения рендеринга и снижения нагрузки на API при одновременных запросах.
+
+> `ApiCache` является **вспомогательным классом**, предназначенным для низкоуровневого управления кэшем. В большинстве случаев рекомендуется взаимодействовать с кэшированием через параметр `cache` в `ApiInstance` или глобальный объект `Api`.
+
+## Основные возможности
+
+- **Автоматическое управление ключами** — генерирует уникальные ключи кэша на основе параметров запроса (путь, метод, тело запроса и т.д.).
+- **Гибкий TTL (Time To Live)** — позволяет устанавливать время хранения для каждого запроса индивидуально или использовать значение по умолчанию (24 часа).
+- **Оптимизация SSR** — предотвращает ненужные вызовы API в среде Node.js. По умолчанию отключено в браузере (работает только если явно включено через параметры конфигурации).
+- **Поддержка слушателей** — возможность подключения внешнего хранилища (например, Redis, Nitro Storage) через функции обратного вызова.
+- **Фоновая очистка** — автоматически удаляет устаревшие записи при обращении к кэшу.
+
+## Методы
+
+### Действие
+
+Методы для управления записями кэша.
+
+- `get<T>(key: string): Promise<T | undefined>` — Извлекает значение из кэша.
+- `getByFetch<T>(fetch: ApiFetch): Promise<T | undefined>` — Извлекает значение, используя опции запроса как источник ключа.
+- `set<T>(key: string, value: T, age?: number): Promise<void>` — Сохраняет значение в кэше.
+- `setByFetch<T>(fetch: ApiFetch, value: T): Promise<void>` — Сохраняет значение на основе опций запроса.
+- `remove(key: string): Promise<void>` — Удаляет запись вручную.
+
+### Конфигурация
+
+- `init(getListener, setListener, removeListener, cacheStepAgeClearOld?): void` — Настраивает кэш слушателями хранилища.
+- `reset(): void` — Очищает элементы в памяти и отключает слушателей.
+
+## Типы данных
+
+#### `ApiCacheItem<T>`
+Структура кэшированной записи.
+- `value: T` — Значение данных.
+- `age: number` — TTL в секундах.
+- `cacheAge: number` — Метка времени создания (мс).
+
+#### `ApiCacheList`
+Внутренний словарь для резервного хранения в оперативной памяти.
+- `[key: string]: ApiCacheItem` — Пары ключ-значение кэшированных элементов.
+
+## Инициализация и внешнее хранилище
+
+По умолчанию `ApiCache` сохраняет записи в оперативной памяти (RAM) процесса и работает только на стороне сервера. Хотя это очень быстро, в продуктовой среде такой подход имеет ограничения:
+1. **Синхронизация в кластере**: В многоэкземплярной конфигурации кэши не разделяются между процессами.
+2. **Перезагрузка процесса**: Память очищается при каждом перезапуск сервера или «холодном старте» серверных функций.
+3. **Лимиты памяти**: Хранение больших объемов данных в RAM может привести к чрезмерному потреблению ресурсов.
+
+Для решения этих задач необходимо инициализировать `ApiCache` с помощью метода `init`, предоставив слушателей (listeners) для связи с внешним механизмом хранения.
+
+> Важно: Метод `ApiCache.init()` должен быть вызван на этапе запуска приложения (до первого API-запроса), чтобы гарантировать правильную конфигурацию кэша.
+
+### Node.js (Произвольное хранилище)
+
+В стандартной среде Node.js вы можете использовать слушателей для взаимодействия с централизованной базой данных или персистентным кэшем, таким как Redis.
+
+```typescript
+import { ApiCache } from '@dxtmisha/functional-basic'
+
+// Конфигурация со слушателями хранилища
+ApiCache.init(
+  // 1. Получение данных из внешнего хранилища
+  async (key) => await myExternalStorage.get(key),
+  
+  // 2. Сохранение данных во внешнее хранилище
+  async (key, value) => {
+    await myExternalStorage.put(key, value)
+    return true // Возвращаем true для подтверждения внешнего сохранения
+  },
+  
+  // 3. Удаление данных из внешнего хранилища
+  async (key) => {
+    await myExternalStorage.delete(key)
+    return true
+  },
+  
+  // 4. Опционально: порог срабатывания фоновой очистки
+  16384
+)
+```
+
+### Nuxt / Nitro
+
+В Nuxt/Nitro рекомендуемый подход — использование встроенного хелпера `useStorage` внутри серверного плагина. Это позволяет задействовать Redis, файловую систему или любой другой драйвер, поддерживаемый Nitro.
+
+```typescript
+// server/plugins/api-cache.ts
+import { ApiCache } from '@dxtmisha/functional-basic'
+
+export default defineNitroPlugin(() => {
+  const storage = useStorage('cache') // Регион кэша Nitro
+
+  ApiCache.init(
+    async (key) => await storage.getItem(key),
+    async (key, value) => {
+      await storage.setItem(key, value)
+      return true
+    },
+    async (key) => {
+      await storage.removeItem(key)
+      return true
+    }
+  )
+})
+```

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

@@ -0,0 +1,111 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/ApiCache - Bộ nhớ đệm phản hồi API'/>
+
+# Lớp ApiCache
+
+Một lớp để lưu bộ nhớ đệm (caching) cho các phản hồi API. Nó cho phép lưu trữ kết quả truy vấn trong bộ nhớ hoặc kho lưu trữ bên ngoài, ngăn chặn các cuộc gọi mạng dư thừa trong một khoảng thời gian cụ thể. Trong phiên bản hiện tại, việc lưu bộ nhớ đệm chỉ hoạt động ở phía máy chủ (SSR) để tăng tốc độ hiển thị và giảm tải API trong quá trình xử lý nhiều yêu cầu đồng thời.
+
+> `ApiCache` là một **lớp bổ trợ**, được thiết kế để quản lý bộ nhớ đệm ở cấp độ thấp. Trong hầu hết các trường hợp, bạn nên tương tác với việc lưu bộ nhớ đệm thông qua tham số `cache` trong `ApiInstance` hoặc đối tượng `Api` toàn cục.
+
+## Các tính năng chính
+
+- **Quản lý khóa tự động** — tạo các khóa cache duy nhất dựa trên các tham số yêu cầu (đường dẫn, phương thức, thân yêu cầu, v.v.).
+- **TTL linh hoạt (Time To Live)** — cho phép thiết lập thời gian lưu trữ cho từng yêu cầu riêng lẻ hoặc sử dụng mặc định (24 giờ).
+- **Tối ưu hóa SSR** — ngăn chặn các cuộc gọi API không cần thiết trong môi trường Node.js. Chế độ này mặc định bị tắt trong trình duyệt.
+- **Hỗ trợ Bộ lắng nghe (Listener)** — khả năng kết nối kho lưu trữ bên ngoài (ví dụ: Redis, Nitro Storage) thông qua các hàm callback.
+- **Dọn dẹp chạy ngầm** — tự động xóa các mục đã hết hạn khi truy cập bộ nhớ đệm.
+
+## Các phương thức
+
+### Hành động
+
+Các phương thức để quản lý các mục lưu trữ trong cache.
+
+- `get<T>(key: string): Promise<T | undefined>` — Lấy một giá trị từ cache.
+- `getByFetch<T>(fetch: ApiFetch): Promise<T | undefined>` — Lấy một giá trị sử dụng các tùy chọn yêu cầu làm nguồn tạo khóa.
+- `set<T>(key: string, value: T, age?: number): Promise<void>` — Lưu một giá trị vào cache.
+- `setByFetch<T>(fetch: ApiFetch, value: T): Promise<void>` — Lưu một giá trị dựa trên các tùy chọn yêu cầu.
+- `remove(key: string): Promise<void>` — Xóa một mục cache thủ công.
+
+### Cấu hình
+
+- `init(getListener, setListener, removeListener, cacheStepAgeClearOld?): void` — Cấu hình cache với các listener của bộ lưu trữ.
+- `reset(): void` — Xóa các mục trong bộ nhớ RAM và ngắt kết nối các listener.
+
+## Các kiểu dữ liệu
+
+#### `ApiCacheItem<T>`
+Cấu trúc của một bản ghi trong bộ nhớ đệm.
+- `value: T` — Dữ liệu được lưu.
+- `age: number` — TTL tính bằng giây.
+- `cacheAge: number` — Dấu thời gian (ms) khi bản ghi được tạo.
+
+#### `ApiCacheList`
+Từ điển nội bộ dành cho việc lưu trữ dự phòng trong bộ nhớ RAM.
+- `[key: string]: ApiCacheItem` — Các cặp khóa-giá trị của các mục được lưu vào bộ nhớ đệm.
+
+## Khởi tạo và Kho lưu trữ bên ngoài
+
+Theo mặc định, `ApiCache` lưu trữ các bản ghi trong RAM của tiến trình. Mặc dù cách này rất nhanh, nhưng nó có những hạn chế khi triển khai thực tế:
+1. **Đồng bộ hóa trong cụм (Cluster)**: Trong thiết lập đa thực thể, bộ nhớ đệm không được chia sẻ giữa các tiến trình.
+2. **Khởi động lại tiến trình**: Bộ nhớ sẽ bị xóa bất khi nào máy chủ khởi động lại hoặc có một "cold start" của các hàm serverless.
+3. **Giới hạn bộ nhớ**: Lưu trữ lượng lớn dữ liệu trong RAM có thể dẫnถึง việc tiêu thụ bộ nhớ quá mức.
+
+Để giải quyết những vấn đề này, bạn phải khởi tạo `ApiCache` bằng phương thức `init`, cung cấp các bộ lắng nghe (listeners) đóng vai trò cầu nối với cơ chế lưu trữ bên ngoài.
+
+> Quan trọng: Bạn phải gọi `ApiCache.init()` trong giai đoạn khởi tạo ứng dụng (trước yêu cầu API đầu tiên) để đảm bảo bộ nhớ đệm được cấu hình chính xác.
+
+### Node.js (Kho lưu trữ tùy chỉnh)
+
+Trong môi trường Node.js tiêu chuẩn, bạn có thể sử dụng các bộ lắng nghe để tương tác với một cơ sở dữ liệu tập trung hoặc một bộ nhớ đệm bền vững như Redis.
+
+```typescript
+import { ApiCache } from '@dxtmisha/functional-basic'
+
+// Cấu hình với các bộ lắng nghe lưu trữ
+ApiCache.init(
+  // 1. Lấy dữ liệu từ kho lưu trữ bên ngoài
+  async (key) => await myExternalStorage.get(key),
+  
+  // 2. Lưu dữ liệu vào kho lưu trữ bên ngoài
+  async (key, value) => {
+    await myExternalStorage.put(key, value)
+    return true // Trả về true để xác nhận đã lưu trữ bên ngoài thành công
+  },
+  
+  // 3. Xóa dữ liệu khỏi kho lưu trữ bên ngoài
+  async (key) => {
+    await myExternalStorage.delete(key)
+    return true
+  },
+  
+  // 4. Tùy chọn: ngưỡng kích hoạt dọn dẹp chạy ngầm
+  16384
+)
+```
+
+### Nuxt / Nitro
+
+Trong Nuxt/Nitro, cách tiếp cận được khuyến nghị là sử dụng helper `useStorage` tích hợp sẵn bên trong một plugin máy chủ. Điều này cho phép bạn tận dụng Redis, FS, hoặc bất kỳ trình điều khiển lưu trữ nào khác được Nitro hỗ trợ.
+
+```typescript
+// server/plugins/api-cache.ts
+import { ApiCache } from '@dxtmisha/functional-basic'
+
+export default defineNitroPlugin(() => {
+  const storage = useStorage('cache') // Nitro Cache region
+
+  ApiCache.init(
+    async (key) => await storage.getItem(key),
+    async (key, value) => {
+      await storage.setItem(key, value)
+      return true
+    },
+    async (key) => {
+      await storage.removeItem(key)
+      return true
+    }
+  )
+})
+```

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

@@ -0,0 +1,32 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/ApiDataReturn - API Response Data Processing'/>
+
+# ApiDataReturn Class
+
+A class for handling and processing data received from an API request. It transforms raw response data into a structured format, extracts metadata, and maps content according to the requested configuration.
+
+> `ApiDataReturn` is an **auxiliary class**, designed for handling and formatting API response data. In most cases, it is recommended to interact with results through the response returned by `ApiInstance` methods or the global `Api` object.
+
+## Key Features
+
+- **Automated Parsing** — intelligently parses JSON responses or returns raw text based on Content-Type headers.
+- **Data Normalization** — ensures that the returned object follows a consistent structure, even if the server response varies.
+- **Metadata Extraction** — automatically extracts common fields like `success`, `status`, `code`, and `message` from the root of the response and merges them into the data object.
+- **Flexible Configuration** — supports custom processing logic via `queryReturn` and controls whether to unwrap the `data` field using `toData`.
+
+## Methods
+
+### Action
+
+- `async init(): Promise<this>` — Initializes the class by reading and parsing data from the response object.
+- `get(): ApiData<T>` — Returns the processed and formatted data.
+- `getAndStatus(status: ApiStatus): ApiData<T>` — Returns the processed data injected with a `statusObject` from the provided status instance.
+- `getData(): ApiData<T> | undefined` — Returns the raw, unformatted data as initially read from the response.
+
+## Internal Logic (Protected)
+
+- `readData<T>(): Promise<ApiData<T>>` — Low-level method that reads the response body and parses it as JSON or text.
+- `initData(): ApiData<T>` — Formats the raw data according to configuration, handling property unwrapping.
+- `initItem(data: Record<string, any>): ApiData<T>` — Merges metadata fields from the response root into the main data object.
+

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

@@ -0,0 +1,32 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/ApiDataReturn - Обработка данных ответа API'/>
+
+# Класс ApiDataReturn
+
+Класс для обработки и подготовки данных, полученных в результате запроса к API. Он преобразует необработанные данные ответа в структурированный формат, извлекает метаданные и сопоставляет содержимое в соответствии с запрошенной конфигурацией.
+
+> `ApiDataReturn` является **вспомогательным классом**, предназначенным для обработки и форматирования данных ответа API. В большинстве случаев рекомендуется взаимодействовать с результатами через ответ, возвращаемый методами `ApiInstance` или глобальным объектом `Api`.
+
+## Ключевые особенности
+
+- **Автоматический парсинг** — интеллектуально анализирует JSON-ответы или возвращает необработанный текст на основе заголовков Content-Type.
+- **Нормализация данных** — гарантирует, что возвращаемый объект соответствует согласованной структуре, даже если ответ сервера различается.
+- **Извлечение метаданных** — автоматически извлекает общие поля, такие как `success`, `status`, `code` и `message`, из корня ответа и объединяет их с объектом данных.
+- **Гибкая конфигурация** — поддерживает пользовательскую логику обработки через `queryReturn` и управляет развертыванием поля `data` с помощью `toData`.
+
+## Методы
+
+### Действие
+
+- `async init(): Promise<this>` — Инициализирует класс, считывая и анализируя данные из объекта ответа.
+- `get(): ApiData<T>` — Возвращает обработанные и отформатированные данные.
+- `getAndStatus(status: ApiStatus): ApiData<T>` — Возвращает обработанные данные с внедренным объектом `statusObject` из предоставленного экземпляра статуса.
+- `getData(): ApiData<T> | undefined` — Возвращает исходные, неотформатированные данные, как они были изначально считаны из ответа.
+
+## Внутренняя логика (Protected)
+
+- `readData<T>(): Promise<ApiData<T>>` — Низкоуровневый метод, который считывает тело ответа и парсит его как JSON или текст.
+- `initData(): ApiData<T>` — Форматирует необработанные данные в соответствии с конфигурацией, обрабатывая развертывание свойств.
+- `initItem(data: Record<string, any>): ApiData<T>` — Переносит поля метаданных из корня ответа в основной объект данных.
+

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

@@ -0,0 +1,32 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/ApiDataReturn - Xử lý dữ liệu phản hồi API'/>
+
+# Lớp ApiDataReturn
+
+Lớp dùng để xử lý và chuẩn bị dữ liệu nhận được từ yêu cầu API. Nó chuyển đổi dữ liệu phản hồi thô thành định dạng có cấu trúc, trích xuất metadata và ánh xạ nội dung theo cấu hình đã yêu cầu.
+
+> `ApiDataReturn` là một **lớp phụ trợ**, được thiết kế để xử lý và định dạng dữ liệu phản hồi API. Trong hầu hết các trường hợp, khuyến khích tương tác với kết quả thông qua phản hồi được trả về bởi các phương thức của `ApiInstance` hoặc đối tượng `Api` toàn cục.
+
+## Các tính năng chính
+
+- **Phân tích tự động** — phân tích thông minh các phản hồi JSON hoặc trả về văn bản thô dựa trên tiêu đề Content-Type.
+- **Chuẩn hóa dữ liệu** — đảm bảo rằng đối tượng trả về tuân theo một cấu trúc nhất quán, ngay cả khi phản hồi của máy chủ thay đổi.
+- **Trích xuất Metadata** — tự động trích xuất các trường chung như `success`, `status`, `code` và `message` từ gốc của phản hồi và hợp nhất chúng vào đối tượng dữ liệu.
+- **Cấu hình linh hoạt** — hỗ trợ logic xử lý tùy chỉnh thông qua `queryReturn` và kiểm soát việc giải nén trường `data` bằng `toData`.
+
+## Các phương thức
+
+### Hành động
+
+- `async init(): Promise<this>` — Khởi tạo lớp bằng cách đọc và phân tích dữ liệu từ đối tượng phản hồi.
+- `get(): ApiData<T>` — Trả về dữ liệu đã được xử lý và định dạng.
+- `getAndStatus(status: ApiStatus): ApiData<T>` — Trả về dữ liệu đã xử lý được chèn thêm `statusObject` từ đối tượng status được cung cấp.
+- `getData(): ApiData<T> | undefined` — Trả về dữ liệu thô, chưa định dạng như lúc ban đầu được đọc từ phản hồi.
+
+## Logic nội bộ (Protected)
+
+- `readData<T>(): Promise<ApiData<T>>` — Phương thức cấp thấp đọc thân phản hồi và phân tích nó dưới dạng JSON hoặc văn bản.
+- `initData(): ApiData<T>` — Định dạng dữ liệu thô theo cấu hình, xử lý việc giải nén các thuộc tính.
+- `initItem(data: Record<string, any>): ApiData<T>` — Hợp nhất các trường metadata từ gốc phản hồi vào đối tượng dữ liệu chính.
+