@dxtmisha/wiki 0.39.1 → 0.39.3

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

@@ -0,0 +1,115 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/Translate - Управление Переводами и Текстами'/>
+
+# Класс Translate
+
+Статическая обертка для стандартного экземпляра класса `TranslateInstance`. Он управляет переводами и локализованным текстом на глобальном уровне, предоставляя инструменты для получения, кэширования и отображения контента с поддержкой шаблонов и автоматическим определением локали.
+
+## Связь с TranslateInstance
+
+Класс `Translate` выступает в роли глобального, предварительно настроенного интерфейса для `TranslateInstance`. Все статические методы вызывают соответствующие методы внутреннего экземпляра (`Translate.getItem()`).
+
+Хотя `Translate` подходит для большинства общесистемных нужд перевода, вы можете создавать независимые среды перевода, используя `TranslateInstance`.
+
+## Ключевые особенности
+
+- **Пакетная загрузка** — интеллектуально группирует запросы на перевод, отправляя их одним паком через 160 мс после постановки в очередь.
+- **Гибкие шаблоны** — поддерживает замену параметров в тексте как по индексам (`[0]`), так и по именованным ключам (`{key}`).
+- **Синхронный и асинхронный доступ** — методы для мгновенного получения текста из кэша (`getSync`) или гарантированной загрузки с сервера (`get`).
+- **Умный кэш** — хранит переводы с учетом текущей локали и поддерживает фоллбэки (Местоположение > Язык > Глобально).
+
+## Инициализация
+
+Класс является статическим и не требует создания экземпляра. Конфигурация применяется к глобальному экземпляру перевода.
+
+```javascript
+import { Translate } from '@dxtmisha/functional-basic'
+
+// Настройка URL API для глобального экземпляра
+Translate.setUrl('/api/v1/translate')
+
+// Предварительная загрузка необходимых текстов
+await Translate.add(['welcome', 'auth.login'])
+```
+
+## Методы
+
+### Конфигурация
+
+- `setConfig(config: TranslateConfig): Translate` — Устанавливает полную конфигурацию для экземпляра перевода.
+- `setUrl(url: string): Translate` — Изменяет адрес API для получения переводов.
+- `setPropsName(name: string): Translate` — Изменяет имя свойства, используемое в API-запросе/ответе.
+- `setReadApi(value: boolean): Translate` — Включает или отключает получение переводов из API.
+
+### Получение переводов
+
+- `async get(name: string, replacement?: any): Promise<string>` — Асинхронно получает текст. Если его нет в кэше и мы не на localhost, пытается загрузить его с сервера.
+- `getSync(name: string, first?: boolean, replacement?: any): string` — Возвращает текст из кэша. Если `first` равен `true`, вернет пробел ` `, если текст отсутствует.
+- `async getList<T>(names: T): Promise<TranslateList<T>>` — Получает группу переводов (асинхронно).
+- `getListSync<T>(names: T, first?: boolean): TranslateList<T>` — Получает группу переводов из кэша (синхронно).
+
+### Групповое обновление
+
+- `async add(names: string | string[]): Promise<void>` — Добавляет несколько кодов в очередь для пакетной загрузки.
+- `addSync(data: Record<string, string>): void` — Напрямую добавляет переводы в кэш.
+- `async addNormalOrSync(data: Record<string, string>): Promise<void>` — Добавляет переводы напрямую на localhost, иначе ставит их в очередь на загрузку.
+- `addSyncByLocation(data: Record<string, Record<string, string>>): void` — Добавляет переводы для определенных локаций/местоположений.
+- `addSyncByFile(data: TranslateDataFile): void` — Добавляет переводы из определения файла.
+
+### Статика vs Экземпляр
+
+- **Использование**: Глобальный доступ к `Translate` из любой точки приложения или локализованные, независимые экземпляры `TranslateInstance`.
+- **Состояние**: Состояние `Translate` разделяется между всем приложением, тогда как `TranslateInstance` обеспечивает изолированное состояние для конкретных компонентов или модулей.
+- **Создание**: `Translate` не требует создания экземпляра (статическая обертка), а `TranslateInstance` создается через `new TranslateInstance()`.
+
+## Отдельные экземпляры
+
+Если вам нужно управлять отдельным набором переводов (например, для конкретного подприложения или специализированного виджета), используйте `TranslateInstance` вместо глобального класса `Translate`.
+
+```javascript
+import { TranslateInstance, TranslateFile } from '@dxtmisha/functional-basic'
+
+// 1. Создаем специализированный набор файлов переводов
+const widgetFiles = new TranslateFile({
+  'ru-RU': () => import('./locales/widget.ru-RU.json')
+})
+
+// 2. Инициализируем отдельный экземпляр перевода
+const widgetTranslate = new TranslateInstance(
+  '/api/widget/translate', 
+  'list', 
+  widgetFiles
+)
+
+// 3. Используем независимо
+const label = await widgetTranslate.get('widget.welcome')
+```
+
+## Типы
+
+### `TranslateCode`
+Строка (имя кода) или массив строк. Массивы используются для замены в шаблонах:
+- `string` — например, `'welcome'`
+- `string[]` — например, `['welcome', 'Гость']`
+
+### `TranslateList`
+Объект, в котором ключи — коды переводов, а значения — итоговые переведенные строки.
+
+## Примеры
+
+### Работа с шаблонами
+```javascript
+// В базе: "Привет, [0]! У вас {count} уведомлений."
+const text = await Translate.get('user.notifications', ['Иван', { count: 5 }])
+// Результат: "Привет, Иван! У вас 5 уведомлений."
+```
+
+### Групповое получение списка
+```javascript
+const labels = await Translate.getList([
+  'home.title',
+  ['home.welcome', 'Гость'], 
+  'home.footer'
+])
+```

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

@@ -0,0 +1,115 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/Translate - Quản lý Bản dịch và Văn bản'/>
+
+# Lớp Translate
+
+Một lớp bao tĩnh (static wrapper) cho một thực thể mặc định của lớp `TranslateInstance`. Nó quản lý bản dịch và văn bản đa ngôn ngữ ở cấp độ toàn cục, cung cấp các công cụ để truy xuất, lưu trữ bộ nhớ đệm (cache) và hiển thị nội dung với hỗ trợ mẫu (template) cùng khả năng tự động phát hiện ngôn ngữ.
+
+## Mối liên hệ với TranslateInstance
+
+Lớp `Translate` hoạt động như một giao diện toàn cục, được cấu hình sẵn cho `TranslateInstance`. Tất cả các phương thức tĩnh đều gọi đến các phương thức tương ứng trên một thực thể nội bộ (`Translate.getItem()`).
+
+Mặc dù `Translate` phù hợp cho hầu hết các nhu cầu dịch thuật toàn ứng dụng, bạn có thể tạo các môi trường dịch thuật độc lập bằng cách sử dụng `TranslateInstance`.
+
+## Tính năng chính
+
+- **Tải theo lô (Batch Loading)** — Tự động gom nhóm các yêu cầu dịch thuật và gửi đi trong một gói duy nhất sau 160ms kể từ khi đưa vào hàng đợi.
+- **Mẫu văn bản linh hoạt** — Hỗ trợ thay thế tham số trong văn bản thông qua chỉ số (`[0]`) hoặc khóa định danh (`{key}`).
+- **Truy cập Đồng bộ và Bất đồng bộ** — Cung cấp các phương thức lấy văn bản tức thì từ cache (`getSync`) hoặc đảm bảo tải từ máy chủ (`get`).
+- **Bộ nhớ đệm thông minh** — Lưu trữ bản dịch theo mã vùng hiện tại và hỗ trợ cơ chế dự phòng (Vị trí > Ngôn ngữ > Toàn cầu).
+
+## Khởi tạo
+
+Lớp này là tĩnh và không yêu cầu khởi tạo đối tượng. Cấu hình được áp dụng cho thực thể dịch thuật toàn cục.
+
+```javascript
+import { Translate } from '@dxtmisha/functional-basic'
+
+// Cấu hình URL API cho thực thể toàn cục
+Translate.setUrl('/api/v1/translate')
+
+// Tải trước các văn bản cần thiết
+await Translate.add(['welcome', 'auth.login'])
+```
+
+## Phương thức
+
+### Cấu hình
+
+- `setConfig(config: TranslateConfig): Translate` — Thiết lập cấu hình hoàn chỉnh cho thực thể dịch thuật.
+- `setUrl(url: string): Translate` — Thay đổi đường dẫn API để lấy bản dịch.
+- `setPropsName(name: string): Translate` — Thay đổi tên thuộc tính được sử dụng trong yêu cầu/phản hồi API.
+- `setReadApi(value: boolean): Translate` — Bật hoặc tắt việc lấy bản dịch từ API.
+
+### Truy xuất bản dịch
+
+- `async get(name: string, replacement?: any): Promise<string>` — Lấy văn bản bất đồng bộ. Nếu không có trong cache và không phải môi trường localhost, hệ thống sẽ cố gắng tải từ máy chủ.
+- `getSync(name: string, first?: boolean, replacement?: any): string` — Trả về văn bản từ cache. Nếu `first` là `true`, trả về một khoảng trắng ` ` nếu thiếu văn bản.
+- `async getList<T>(names: T): Promise<TranslateList<T>>` — Lấy một nhóm các bản dịch (bất đồng bộ).
+- `getListSync<T>(names: T, first?: boolean): TranslateList<T>` — Lấy một nhóm các bản dịch từ cache (đồng bộ).
+
+### Cập nhật theo lô
+
+- `async add(names: string | string[]): Promise<void>` — Thêm nhiều mã vào hàng đợi để tải theo lô.
+- `addSync(data: Record<string, string>): void` — Thêm trực tiếp các bản dịch vào bộ nhớ đệm.
+- `async addNormalOrSync(data: Record<string, string>): Promise<void>` — Thêm bản dịch trực tiếp trên localhost, ngược lại sẽ đưa vào hàng đợi để tải.
+- `addSyncByLocation(data: Record<string, Record<string, string>>): void` — Thêm bản dịch cho các vị trí/ngôn ngữ cụ thể.
+- `addSyncByFile(data: TranslateDataFile): void` — Thêm bản dịch từ định nghĩa tệp.
+
+### Static và Thực thể (Instance)
+
+- **Cách dùng**: Truy cập toàn cục bằng `Translate` ở bất kỳ đâu trong ứng dụng hoặc sử dụng `TranslateInstance` cho các thực thể độc lập, theo từng khu vực cụ thể.
+- **Trạng thái**: Trạng thái `Translate` chia sẻ chung cho toàn bộ ứng dụng, trong khi `TranslateInstance` cung cấp trạng thái cô lập cho các thành phần hoặc mô-đun cụ thể.
+- **Khởi tạo**: `Translate` không yêu cầu khởi tạo đối tượng (lớp bao tĩnh), trong khi `TranslateInstance` được tạo thông qua `new TranslateInstance()`.
+
+## Các thực thể độc lập
+
+Nếu bạn cần quản lý một tập hợp các bản dịch riêng biệt (ví dụ: cho một ứng dụng con cụ thể hoặc một widget chuyên dụng), hãy sử dụng `TranslateInstance` thay vì lớp `Translate` toàn cục.
+
+```javascript
+import { TranslateInstance, TranslateFile } from '@dxtmisha/functional-basic'
+
+// 1. Tạo một bộ tệp dịch chuyên dụng
+const widgetFiles = new TranslateFile({
+  'vi-VN': () => import('./locales/widget.vi-VN.json')
+})
+
+// 2. Khởi tạo một thực thể dịch thuật độc lập
+const widgetTranslate = new TranslateInstance(
+  '/api/widget/translate', 
+  'list', 
+  widgetFiles
+)
+
+// 3. Sử dụng độc lập
+const label = await widgetTranslate.get('widget.welcome')
+```
+
+## Kiểu dữ liệu (Types)
+
+### `TranslateCode`
+Một chuỗi (mã văn bản) hoặc một mảng các chuỗi. Mảng được dùng để thay thế mẫu (template):
+- `string` — ví dụ: `'welcome'`
+- `string[]` — ví dụ: `['welcome', 'Khách']`
+
+### `TranslateList`
+Một bản ghi (record) với khóa là mã bản dịch và giá trị là các chuỗi đã dịch tương ứng.
+
+## Ví dụ
+
+### Làm việc với mẫu (Template)
+```javascript
+// Trong cơ sở dữ liệu: "Xin chào, [0]! Bạn có {count} thông báo."
+const text = await Translate.get('user.notifications', ['Sơn', { count: 5 }])
+// Kết quả: "Xin chào, Sơn! Bạn có 5 thông báo."
+```
+
+### Lấy danh sách hàng loạt
+```javascript
+const labels = await Translate.getList([
+  'home.title',
+  ['home.welcome', 'Khách'], 
+  'home.footer'
+])
+```

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

@@ -0,0 +1,87 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/TranslateFile - Translation File Management'/>
+
+# TranslateFile Class
+
+A class for managing translation data from external files. It supports lazy loading of translation packs, automatic locale matching, and internal caching to optimize performance and reduce redundant file processing.
+
+Unlike static utilities, `TranslateFile` is an instantiable class, allowing for multiple translation sets with independent locale and location settings.
+
+## Key Features
+
+- **Lazy Loading** — Supports asynchronous loading of translation files only when they are needed for the current locale.
+- **Smart Caching** — Automatically caches the content of loaded files, preventing repetitive file reads or network requests.
+- **Locale Prioritization** — Intelligently selects the best-matching file based on location (Location > Language > Global).
+- **Flexible Context** — Supports custom location and language providers, defaulting to the global `Geo` settings.
+
+## Initialization
+
+To initialize the object, call the `TranslateFile(data, language, location)` constructor.
+
+**Parameters:**
+- `data?: TranslateDataFile` — initial mapping of locales to file loaders.
+- `language: string | (() => string) = () => Geo.getLanguage()` — current language or a function returning it.
+- `location: string | (() => string) = () => Geo.getLocation()` — current location or a function returning it.
+
+```javascript
+import { TranslateFile, Geo } from '@dxtmisha/functional-basic'
+
+// 1. Simple initialization
+const files = new TranslateFile({
+  'en-US': () => import('./locales/en-US.json'),
+  'en': () => import('./locales/en.json'),
+  'global': () => import('./locales/global.json')
+})
+
+// 2. Custom context providers
+const customFiles = new TranslateFile(
+  {}, 
+  () => 'fr', 
+  () => 'fr-FR'
+)
+```
+
+## Methods
+
+### Data Retrieval
+
+- `async getList(): Promise<TranslateDataFileList | undefined>` — Returns a list of translations for the current location. It first checks the internal cache, then tries to load from the registered file loaders.
+- `isFile(): boolean` — Checks if there are any registered file loaders applicable to the current location or language.
+- `getLocation(): string` — Returns the current location string (executes the provider if it's a function).
+- `getLanguage(): string` — Returns the current language string (executes the provider if it's a function).
+
+### Data Management
+
+- `add(data: TranslateDataFile): void` — Adds a mapping of locales to their respective translation file loaders (functions returning a Promise).
+
+## Types
+
+### `TranslateDataFile`
+A collection of asynchronous loader functions indexed by locale/region strings:
+- **Key**: Locale code (e.g., `'en-US'`, `'ru'`, `'global'`).
+- **Value**: Function returning a `Promise` of `TranslateDataFileList`.
+
+### `TranslateDataFileList`
+A simple key-value record of translations: `Record<string, string>`.
+
+## Examples
+
+### Integration with TranslateInstance
+
+```javascript
+import { TranslateFile, TranslateInstance } from '@dxtmisha/functional-basic'
+
+const translationFiles = new TranslateFile({
+  'en-US': () => Promise.resolve({ hello: 'Hello US' }),
+  'en': () => Promise.resolve({ hello: 'Hello' })
+})
+
+const translate = new TranslateInstance(
+  '/api/translate',
+  'list',
+  translationFiles
+)
+
+const message = await translate.get('hello')
+```

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

@@ -0,0 +1,87 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/TranslateFile - Управление Файлами Перевода'/>
+
+# Класс TranslateFile
+
+Класс для управления данными переводов из внешних файлов. Поддерживает ленивую загрузку (lazy loading) пакетов перевода, автоматическое сопоставление локалей и внутреннее кэширование для оптимизации производительности.
+
+В отличие от статических утилит, `TranslateFile` является экземпляром класса, что позволяет создавать несколько наборов переводов с независимыми настройками локали и местоположения.
+
+## Ключевые особенности
+
+- **Ленивая загрузка** — поддерживает асинхронную загрузку файлов перевода только тогда, когда они необходимы для текущей локали.
+- **Умное кэширование** — автоматически кэширует содержимое загруженных файлов, предотвращая повторное чтение файлов или лишние сетевые запросы.
+- **Приоритизация локалей** — интеллектуально выбирает наиболее подходящий файл на основе местоположения (Местоположение > Язык > Глобальное).
+- **Гибкий контекст** — поддерживает настраиваемые поставщики местоположения и языка, по умолчанию используя глобальные настройки `Geo`.
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `TranslateFile(data, language, location)`.
+
+**Параметры:**
+- `data?: TranslateDataFile` — начальное сопоставление локалей и загрузчиков файлов.
+- `language: string | (() => string) = () => Geo.getLanguage()` — текущий язык или функция, возвращающая его.
+- `location: string | (() => string) = () => Geo.getLocation()` — текущее местоположение или функция, возвращающая его.
+
+```javascript
+import { TranslateFile, Geo } from '@dxtmisha/functional-basic'
+
+// 1. Простая инициализация
+const files = new TranslateFile({
+  'en-US': () => import('./locales/en-US.json'),
+  'en': () => import('./locales/en.json'),
+  'global': () => import('./locales/global.json')
+})
+
+// 2. Использование пользовательских провайдеров контекста
+const customFiles = new TranslateFile(
+  {}, 
+  () => 'fr', 
+  () => 'fr-FR'
+)
+```
+
+## Методы
+
+### Получение данных
+
+- `async getList(): Promise<TranslateDataFileList | undefined>` — Возвращает список переводов для текущего местоположения. Сначала проверяет внутренний кэш, затем пытается загрузить данные через зарегистрированные загрузчики.
+- `isFile(): boolean` — Проверяет, есть ли зарегистрированные загрузчики файлов, применимые к текущему местоположению или языку.
+- `getLocation(): string` — Возвращает текущую строку местоположения (выполняет поставщика, если это функция).
+- `getLanguage(): string` — Возвращает текущую строку языка (выполняет поставщика, если это функция).
+
+### Управление данными
+
+- `add(data: TranslateDataFile): void` — Добавляет сопоставление локалей и соответствующих им функций-загрузчиков (функций, возвращающих Promise).
+
+## Типы
+
+### `TranslateDataFile`
+Коллекция асинхронных функций-загрузчиков, индексированных строками локали/региона:
+- **Ключ**: Код локали (например, `'en-US'`, `'ru'`, `'global'`).
+- **Значение**: Функция, возвращающая `Promise` с `TranslateDataFileList`.
+
+### `TranslateDataFileList`
+Простой объект перевода (ключ-значение): `Record<string, string>`.
+
+## Примеры
+
+### Интеграция с TranslateInstance
+
+```javascript
+import { TranslateFile, TranslateInstance } from '@dxtmisha/functional-basic'
+
+const translationFiles = new TranslateFile({
+  'en-US': () => Promise.resolve({ hello: 'Hello US' }),
+  'en': () => Promise.resolve({ hello: 'Привет' })
+})
+
+const translate = new TranslateInstance(
+  '/api/translate',
+  'list',
+  translationFiles
+)
+
+const message = await translate.get('hello')
+```

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

@@ -0,0 +1,87 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/TranslateFile - Quản Lý Tập Tin Dịch'/>
+
+# Lớp TranslateFile
+
+Lớp dùng để quản lý dữ liệu dịch thuật từ các tập tin bên ngoài. Nó hỗ trợ tải chậm (lazy loading) các bộ dịch, tự động khớp mã vùng và bộ nhớ đệm nội bộ để tối ưu hóa hiệu suất.
+
+Khác với các công cụ tĩnh (static utilities), `TranslateFile` là một lớp có thể khởi tạo (instantiable), cho phép tạo nhiều bộ dịch với các thiết lập ngôn ngữ và khu vực độc lập.
+
+## Các Tính Năng Chính
+
+- **Tải chậm (Lazy Loading)** — Hỗ trợ tải bất đồng bộ các tập tin dịch chỉ khi cần thiết cho mã vùng hiện tại.
+- **Bộ nhớ đệm thông minh** — Tự động lưu trữ nội dung các tập tin đã tải, ngăn chặn việc đọc tập tin lặp lại hoặc các yêu cầu mạng không cần thiết.
+- **Ưu tiên Mã vùng** — Tự động chọn tập tin phù hợp nhất dựa trên vị trí (Vị trí > Ngôn ngữ > Toàn cầu).
+- **Ngữ cảnh Linh hoạt** — Hỗ trợ các trình cung cấp vị trí và ngôn ngữ tùy chỉnh, mặc định sử dụng thiết lập toàn cục của `Geo`.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm tạo `TranslateFile(data, language, location)`.
+
+**Tham số:**
+- `data?: TranslateDataFile` — ánh xạ ban đầu của mã vùng và các trình tải tập tin.
+- `language: string | (() => string) = () => Geo.getLanguage()` — ngôn ngữ hiện tại hoặc một hàm trả về giá trị đó.
+- `location: string | (() => string) = () => Geo.getLocation()` — vị trí hiện tại hoặc một hàm trả về giá trị đó.
+
+```javascript
+import { TranslateFile, Geo } from '@dxtmisha/functional-basic'
+
+// 1. Khởi tạo đơn giản
+const files = new TranslateFile({
+  'en-US': () => import('./locales/en-US.json'),
+  'vi': () => import('./locales/vi.json'),
+  'global': () => import('./locales/global.json')
+})
+
+// 2. Sử dụng các trình cung cấp ngữ cảnh tùy chỉnh
+const customFiles = new TranslateFile(
+  {}, 
+  () => 'fr', 
+  () => 'fr-FR'
+)
+```
+
+## Các Phương thức
+
+### Lấy Dữ liệu
+
+- `async getList(): Promise<TranslateDataFileList | undefined>` — Trả về danh sách các bản dịch cho vị trí hiện tại. Nó kiểm tra bộ nhớ đệm trước, sau đó thử tải từ các trình tải tập tin đã đăng ký.
+- `isFile(): boolean` — Kiểm tra xem có trình tải tập tin nào phù hợp với vị trí hoặc ngôn ngữ hiện tại hay không.
+- `getLocation(): string` — Trả về chuỗi vị trí hiện tại (phụ thuộc vào trình cung cấp nếu nó là một hàm).
+- `getLanguage(): string` — Trả về chuỗi ngôn ngữ hiện tại (phụ thuộc vào trình cung cấp nếu nó là một hàm).
+
+### Quản lý Dữ liệu
+
+- `add(data: TranslateDataFile): void` — Thêm ánh xạ mã vùng vào các trình tải tập tin dịch tương ứng (các hàm trả về Promise).
+
+## Các Kiểu Dữ liệu
+
+### `TranslateDataFile`
+Một tập hợp các hàm tải bất đồng bộ được lập chỉ mục bởi các chuỗi mã vùng/khu vực:
+- **Khóa**: Mã vùng (ví dụ: `'en-US'`, `'vi'`, `'global'`).
+- **Giá trị**: Hàm trả về một `Promise` của `TranslateDataFileList`.
+
+### `TranslateDataFileList`
+Một bản ghi khóa-giá trị đơn giản của các bản dịch: `Record<string, string>`.
+
+## Ví dụ
+
+### Tích hợp với TranslateInstance
+
+```javascript
+import { TranslateFile, TranslateInstance } from '@dxtmisha/functional-basic'
+
+const translationFiles = new TranslateFile({
+  'en-US': () => Promise.resolve({ hello: 'Hello US' }),
+  'vi': () => Promise.resolve({ hello: 'Xin chào' })
+})
+
+const translate = new TranslateInstance(
+  '/api/translate',
+  'list',
+  translationFiles
+)
+
+const message = await translate.get('hello')
+```

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

@@ -0,0 +1,87 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/# Data & Types'/>
+
+# Data & Types
+
+A set of utilities for reliable type checking, safe data conversion, and efficient manipulation of objects and arrays. These functions help avoid `undefined` errors and simplify the processing of complex structures.
+
+## Type Checking (is...)
+
+Functions for determining the type and content of variables.
+
+```javascript
+import { isFilled, isObject, isFunction } from '@dxtmisha/functional-basic'
+
+// 1. Check for content (non-empty string/array/object)
+isFilled('hello') // true
+isFilled([])      // false
+
+// 2. Object check (includes arrays, excludes null)
+isObject({ a: 1 }) // true
+isObject([1, 2])   // true
+
+// 3. Object check excluding arrays
+isObjectNotArray({ a: 1 }) // true
+isObjectNotArray([1, 2])   // false
+
+// 4. Check if value is a function
+isFunction(() => {}) // true
+```
+
+## Conversion (to...)
+
+Utilities for casting data to the desired type or format.
+
+```javascript
+import { toNumber, toArray, toCamelCase, transformation } from '@dxtmisha/functional-basic'
+
+// 1. Cast to number (with string cleaning support)
+toNumber('100.50 px') // 100.5
+
+// 2. Guaranteed array
+toArray('single') // ['single']
+toArray([1, 2])   // [1, 2]
+
+// 3. Automatic type detection from string
+transformation('true')  // true (boolean)
+transformation('12.5')  // 12.5 (number)
+transformation('{"a":1}') // { a: 1 } (object)
+
+// 4. String formatting
+toCamelCase('background-color') // 'backgroundColor'
+```
+
+## Data Manipulation
+
+Methods for deep copying and safe property access.
+
+```javascript
+import { copyObject, getItemByPath, getObjectNoUndefined } from '@dxtmisha/functional-basic'
+
+// 1. Deep object cloning
+const clone = copyObject(original)
+
+// 2. Safe value retrieval by path
+const value = getItemByPath(myData, 'user.profile.name')
+
+// 3. Cleaning an object of empty values
+const cleaned = getObjectNoUndefined({ a: 1, b: undefined, c: null }, null) 
+// { a: 1, b: undefined } (removes only c: null)
+```
+
+## Array Operations
+
+Utilities for filtering and iteration.
+
+```javascript
+import { uniqueArray, forEach } from '@dxtmisha/functional-basic'
+
+// 1. Removing duplicates
+uniqueArray([1, 2, 2, 3, 1]) // [1, 2, 3]
+
+// 2. Universal iterator (for arrays and objects)
+forEach([10, 20], (value, index) => {
+  console.log(`${index}: ${value}`)
+})
+```