@dxtmisha/wiki 0.39.1 → 0.39.2

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

@@ -0,0 +1,183 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/GeoIntl - Quốc tế hóa (Intl)'/>
+
+# Lớp GeoIntl
+
+Lớp `GeoIntl` là một lớp bao đóng (wrapper) cao cấp, được tối ưu hóa dựa trên API `Intl` gốc của trình duyệt, được thiết kế đặc biệt để tích hợp mượt mà với các tính năng định vị địa lý của `Geo`. Nó cung cấp một giao diện thống nhất, nhận biết vùng locale để định dạng số, tiền tệ, đơn vị, ngày tháng, thời gian và tên địa lý, đồng thời tự động xử lý việc nhận diện locale và quản lý instance.
+
+Lớp này triển khai mẫu **Per-locale Singleton (Singleton theo vùng locale)**, đảm bảo rằng chỉ có một instance được tạo và lưu vào bộ nhớ đệm cho mỗi mã locale duy nhất, giúp giảm đáng kể chi phí khởi tạo lặp lại các đối tượng `Intl`.
+
+## Các tính năng chính
+
+- **Bộ nhớ đệm Instance** — Tự động quản lý và tái sử dụng các instance dựa trên chuỗi locale chuẩn.
+- **API định dạng thống nhất** — Đơn giản hóa các cấu hình `Intl` phức tạp thành các phương thức cấp cao, dễ sử dụng.
+- **Định vị thích ứng** — Tự động lấy các giá trị mặc định từ trạng thái `Geo` toàn cầu nếu không có locale rõ ràng nào được cung cấp.
+- **Nhận thức văn hóa** — Xử lý chính xác các quy ước đặt tên đa dạng, ngày bắt đầu của tuần trong lịch và các quy tắc số nhiều trên các nền văn hóa khác nhau.
+
+## Khởi tạo
+
+### `getInstance`
+
+Truy xuất một instance từ bộ nhớ đệm hoặc tạo một instance mới cho mã locale được chỉ định.
+
+**Tham số:**
+- `code?: string` — Chuỗi locale chuẩn (ví dụ: `'vi-VN'`, `'en-US'`). Mặc định là `Geo.getLocation()`.
+
+**Trả về:** `GeoIntl` — Instance singleton cho vùng locale được yêu cầu.
+
+```javascript
+import { GeoIntl } from '@dxtmisha/functional-basic'
+
+const intl = GeoIntl.getInstance('vi-VN')
+const currentIntl = new GeoIntl() // Cũng sử dụng bộ nhớ đệm singleton nội bộ
+```
+
+## Các phương thức Địa lý & Địa phương hóa
+
+- `getLocation(): string` — Trả về chuỗi locale chuẩn đã chuẩn hóa (ví dụ: `'vi-VN'`).
+- `getFirstDay(): string` — Trả về chỉ định ngày đầu tiên trong tuần của vùng locale (ví dụ: `'Mon'`, `'Sun'`).
+
+## Tên & Vùng
+
+### `display`
+
+Cung cấp các bản dịch đã được địa phương hóa cho ngôn ngữ, vùng và chữ viết bằng công cụ `Intl.DisplayNames`.
+
+**Tham số:**
+- `value?: string` — Mã định danh (ví dụ: `'en'`, `'VN'`).
+- `typeOptions?` — Một chuỗi đại diện cho kiểu hiển thị (`'language'`, `'region'`, `'script'`) hoặc một đối tượng `Intl.DisplayNamesOptions` đầy đủ.
+
+**Trả về:** `string` — Tên hiển thị đã được địa phương hóa.
+
+```javascript
+intl.display('en', 'language') // 'Tiếng Anh'
+intl.display('US', 'region')   // 'Hoa Kỳ'
+```
+
+### `languageName` / `countryName`
+
+Các phương thức rút gọn để lấy tên ngôn ngữ và quốc gia đã được địa phương hóa.
+
+**Tham số:**
+- `value?: string` — Mã ngôn ngữ hoặc quốc gia.
+- `style?` — Kiểu định dạng: `'long'`, `'short'`, hoặc `'narrow'`.
+
+**Trả về:** `string`
+
+### `fullName`
+
+Định dạng họ tên đầy đủ của một người theo quy ước văn hóa của vùng locale hiện tại. Thứ tự các thành phần (Họ-Tên-Đệm hoặc Tên-Đệm-Họ) được xác định bởi `nameFormat` trong dữ liệu địa lý.
+
+**Tham số:**
+- `last: string` — Họ.
+- `first: string` — Tên.
+- `surname?: string` — Tên đệm hoặc tên phụ (tùy chọn).
+- `short?: boolean` — Nếu là `true`, viết tắt các phần sau phần đầu tiên thành chữ cái đầu (ví dụ: `Nguyễn V. A.`).
+
+**Trả về:** `string`
+
+## Định dạng Số
+
+### `number`
+
+Định dạng một số bằng cách sử dụng các khả năng của `Intl.NumberFormat`.
+
+**Tham số:**
+- `value: NumberOrString` — Giá trị số cần định dạng.
+- `options?: Intl.NumberFormatOptions` — Cấu hình cho phần thập phân, nhóm số, v.v.
+
+**Trả về:** `string`
+
+### `currency`
+
+Trình định dạng tiền tệ chuyên dụng với vị trí ký hiệu tự động.
+
+**Tham số:**
+- `value: NumberOrString` — Số tiền. Cũng chấp nhận các chuỗi có hậu tố tiền tệ (ví dụ: `'100 USD'`).
+- `currencyOptions?: string | Intl.NumberFormatOptions` — Mã tiền tệ (`'VND'`) hoặc các tùy chọn định dạng chi tiết.
+- `numberOnly?: boolean` — Nếu là `true`, chỉ trả về các chữ số đã định dạng mà không có ký hiệu tiền tệ.
+
+**Trả về:** `string`
+
+```javascript
+intl.currency(1500, 'VND') // '1.500 ₫'
+intl.currency('1500 USD')  // '$1,500.00'
+```
+
+### `unit` / `sizeFile`
+
+Định dạng các số với đơn vị đo lường. `sizeFile` cung cấp khả năng tự động điều chỉnh tỷ lệ cho các giá trị byte (tự động chuyển sang KB, MB, GB).
+
+**Tham số (`sizeFile`):**
+- `value: NumberOrString` — Kích thước tính bằng byte.
+- `unitOptions?` — Đơn vị bắt đầu (mặc định là `'byte'`).
+
+**Trả về:** `string`
+
+### `plural`
+
+Áp dụng các quy tắc số nhiều nhận biết locale.
+
+**Tham số:**
+- `value: NumberOrString` — Số lượng.
+- `words: string` — Các dạng từ cách nhau bằng dấu `|`: `one|two|few|many|other|zero`.
+- `options?` — `Intl.PluralRulesOptions`.
+
+**Trả về:** `string` — Số đã định dạng kèm theo dạng từ chính xác.
+
+## Ngày & Giờ
+
+### `date` / `time`
+
+Công cụ định dạng ngày chính cung cấp các biểu diễn địa phương hóa dựa trên các tùy chỉnh `GeoDate` định sẵn.
+
+**Tham số:**
+- `value: NumberOrStringOrDate` — Đầu vào ngày.
+- `type?: GeoDate` — Mã định danh định sẵn: `'date'`, `'time'`, `'datetime'`, `'full'`, v.v.
+- `styleOptions?` — Tùy chọn `Intl.DateTimeFormatOptions` tùy chỉnh hoặc chuỗi kiểu tháng.
+- `hour24?: boolean` — Ép buộc biểu diễn thời gian 24 giờ.
+
+**Trả về:** `string`
+
+### `months` / `weekdays`
+
+Trả về các mảng nhãn đã được địa phương hóa cho tháng hoặc các ngày trong tuần, lý tưởng để đưa vào các thành phần lựa chọn trên UI.
+
+**Trả về:** `ItemValue<number>[]` — Mảng các đối tượng có trường `label` và `value`.
+
+## Thời gian Tương đối
+
+### `relative`
+
+Tính toán và định dạng sự khác biệt thời gian tương đối so với một điểm tham chiếu (hiện tại), tự động chọn đơn vị thời gian phù hợp nhất.
+
+**Tham số:**
+- `value: NumberOrStringOrDate` — Ngày trong quá khứ hoặc tương lai.
+- `styleOptions?` — Kiểu định dạng (ví dụ: `'long'`, `'short'`).
+- `todayValue?: Date` — Điểm tham chiếu rõ ràng (mặc định là `new Date()`).
+
+**Trả về:** `string` (ví dụ: `'2 giờ trước'`, `'sau 3 ngày'`)
+
+### `relativeLimit`
+
+Trình định dạng có điều kiện kết nối giữa thời gian tương đối và tuyệt đối. Nếu ngày nằm trong một `limit` ngày nhất định, nó sẽ trả về thời gian tương đối; nếu không, nó sẽ chuyển sang định dạng ngày tuyệt đối tiêu chuẩn.
+
+**Trả về:** `string`
+
+## Sắp xếp
+
+### `sort`
+
+Sắp xếp một mảng các phần tử bằng cách sử dụng so sánh nhận biết locale thông qua `Intl.Collator`.
+
+**Tham số:**
+- `data: T[]` — Mảng mục tiêu.
+- `compareFn?` — Một hàm chuyển đổi tùy chọn để trích xuất các khóa sắp xếp từ các đối tượng phức tạp.
+
+**Trả về:** `T[]` — Mảng đã sắp xếp.
+
+```javascript
+intl.sort(['chuối', 'táo', 'cam'])
+// ['cam', 'chuối', 'táo']
+```

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

@@ -0,0 +1,139 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/GeoPhone - Phone Number Masks'/>
+
+# GeoPhone Class
+
+A specialized class for storing and processing international phone number masks. It provides a robust engine for identifying geographic country information by phone number strings, formatting raw numbers into localized mask specifications, and managing a comprehensive prefix-tree based map of international phone codes.
+
+It integrates deeply with `Geo` geolocation data to provide automatic mask resolution based on the current user locale or explicit country codes.
+
+## Key Features
+
+- **Automatic Mapping** — Resolves the appropriate country and mask pattern dynamically through a recursive prefix-tree lookup.
+- **Prefix Tree Optimization** — Uses a specialized `map` structure (Prefix Tree) for efficient, high-performance search across international numbering plans.
+- **Intelligent Normalization** — Automatically handles regional dialing variations, such as leading trunk zeros or national prefixes (e.g., Russian '8').
+- **Standardized Formatting** — Converts raw numeric strings into human-readable phone formats matching international telephony standards.
+
+## Search Methods
+
+### `getByPhone`
+
+Primary identification method that analyzes a phone number string to extract geographic information and the most suitable numbering mask.
+
+**Parameters:**
+- `phone: string` — The target phone number to analyze (accepts raw or partially formatted strings).
+
+**Returns:** `GeoPhoneMapInfo` — A structured payload containing the matched `GeoPhoneMap` item and the normalized numeric portion of the phone.
+
+```javascript
+import { GeoPhone } from '@dxtmisha/functional-basic'
+
+const info = GeoPhone.getByPhone('12025550123')
+// returns:
+// { 
+//   item: { info: { phone: 1, ... }, mask: ['1 (***) ***-****'], ... },
+//   phone: '2025550123' 
+// }
+```
+
+### `get`
+
+Retrieves localized phone metadata associated with a specific country code.
+
+**Parameters:**
+- `code: string` — Standard ISO 3166 country code (e.g., `'US'`, `'RU'`, `'VN'`).
+
+**Returns:** `GeoPhoneValue | undefined` — The raw metadata for the country, or `undefined` if not found in the dataset.
+
+```javascript
+GeoPhone.get('US') 
+// { phone: 1, within: 1, mask: ['* (***) ***-****'], value: 'US' }
+```
+
+### `getByCode`
+
+Extended retrieval method that returns complete mask data including the search tree node for a given country code.
+
+**Parameters:**
+- `code: string` — Target country code string.
+
+**Returns:** `GeoPhoneMap | undefined` — The full map node object for the requested code.
+
+```javascript
+GeoPhone.getByCode('RU')
+// { info: { phone: 7, ... }, mask: ['7 (***) ***-**-**'], ... }
+```
+
+## Data Access Methods
+
+- `getList(): GeoPhoneValue[]` — Returns the complete, sorted flat list of all registered international phone metadata.
+- `getMap(): Record<string, GeoPhoneMap>` — Returns the root node of the internal prefix-tree used for high-speed number identification.
+
+## Formatting & Utility Methods
+
+### `toMask`
+
+Transforms a raw numeric phone string into a formatted version based on a specified set of masks.
+
+**Parameters:**
+- `phone: string` — The raw numeric input.
+- `masks?: string[]` — An array of valid mask strings to iterate through for property matching.
+
+**Returns:** `string | undefined` — The human-formatted string, or `undefined` if no mask length matches the input.
+
+```javascript
+GeoPhone.toMask('2025550123', ['* (***) ***-****']) 
+// '1 (202) 555-0123'
+```
+
+### `removeZero`
+
+Standardizes internal number representation by stripping leading trunk zeros or correcting regional dialing prefixes to ensure consistent search logic.
+
+**Parameters:**
+- `phone: string` — The input phone number string.
+
+**Returns:** `string` — The normalized numeric string.
+
+```javascript
+GeoPhone.removeZero('0671234567')  // '671234567'
+GeoPhone.removeZero('89001234567') // '9001234567'
+```
+
+## GeoPhone Objects
+
+### `GeoPhoneValue`
+The basic metadata structure for each country's phone configuration:
+- `phone: number` — Dialing code (e.g., `7`).
+- `within: number` — Internal dialing rule code.
+- `mask: string[]` — Array of mask patterns.
+- `value: string` — Country identifier.
+
+### `GeoPhoneMap`
+A node within the internal prefix-tree:
+- `items: GeoPhoneValue[]` — List of items under this branch.
+- `info: GeoPhoneValue | undefined` — The matched value at this specific numeric node.
+- `next: Record<string, GeoPhoneMap>` — Pointers to the next numeric digits in the tree.
+
+## Examples
+
+```javascript
+import { GeoPhone } from '@dxtmisha/functional'
+
+// 1. Identify country by phone number
+const lookup = GeoPhone.getByPhone('+79001234567')
+if (lookup.item) {
+    console.log('Country:', lookup.item.value) // 'RU'
+    console.log('Main Mask:', lookup.item.mask[0])
+}
+
+// 2. Manual formatting
+const formatted = GeoPhone.toMask('442071234567', ['+** (**) **** ****'])
+console.log(formatted) // '+44 (20) 7123 4567'
+
+// 3. Normalizing input for search
+const rawInput = '0084901234567'
+const normalized = GeoPhone.removeZero(rawInput.replace(/^00/, ''))
+console.log(normalized) // '84901234567'
+```

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

@@ -0,0 +1,139 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/GeoPhone - Маски телефонов'/>
+
+# Класс GeoPhone
+
+Специализированный класс для хранения и обработки масок международных телефонных номеров. Обеспечивает мощный механизм идентификации географической информации о стране по строке номера, форматирование необработанных чисел в локализованные маски и управление комплексной картой телефонных кодов на базе префиксного дерева.
+
+Класс тесно интегрирован с гео-данными `Geo`, что позволяет автоматически определять маску на основе текущей локали пользователя или переданных кодов стран.
+
+## Ключевые особенности
+
+- **Автоматическое сопоставление** — динамически определяет подходящую страну и паттерн маски через рекурсивный поиск по префиксному дереву.
+- **Оптимизация дерева префиксов** — использует специализированную структуру `map` (Trie/Prefix Tree) для высокопроизводительного поиска по международным планам нумерации.
+- **Интеллектуальная нормализация** — автоматически обрабатывает региональные вариации набора, такие как ведущие нули или национальные префиксы (например, российская «8»).
+- **Стандартизированное форматирование** — преобразует сырые числовые строки в читаемые форматы, соответствующие международным стандартам телефонии.
+
+## Методы поиска
+
+### `getByPhone`
+
+Основной метод идентификации, который анализирует строку номера телефона для извлечения географической информации и наиболее подходящей маски нумерации.
+
+**Параметры:**
+- `phone: string` — целевой номер телефона для анализа (принимает как сырые, так и частично отформатированные строки).
+
+**Возвращает:** `GeoPhoneMapInfo` — структурированный объект, содержащий найденный элемент `GeoPhoneMap` и нормализованную числовую часть номера.
+
+```javascript
+import { GeoPhone } from '@dxtmisha/functional-basic'
+
+const info = GeoPhone.getByPhone('79001234567')
+// возвращает:
+// { 
+//   item: { info: { phone: 7, ... }, mask: ['7 (***) ***-**-**'], ... },
+//   phone: '9001234567' 
+// }
+```
+
+### `get`
+
+Извлекает локализованные метаданные телефона, связанные с конкретным кодом страны.
+
+**Параметры:**
+- `code: string` — стандартный код страны ISO 3166 (например, `'RU'`, `'US'`, `'VN'`).
+
+**Возвращает:** `GeoPhoneValue | undefined` — сырые метаданные для страны или `undefined`, если код не найден в базе.
+
+```javascript
+GeoPhone.get('RU') 
+// { phone: 7, within: 8, mask: ['* (***) ***-**-**'], value: 'RU' }
+```
+
+### `getByCode`
+
+Расширенный метод получения данных, который возвращает полную информацию о маске, включая узел дерева поиска для заданного кода страны.
+
+**Параметры:**
+- `code: string` — строка целевого кода страны.
+
+**Возвращает:** `GeoPhoneMap | undefined` — объект узла карты для запрошенного кода.
+
+```javascript
+GeoPhone.getByCode('US')
+// { info: { phone: 1, ... }, mask: ['1 (***) ***-****'], ... }
+```
+
+## Методы доступа к данным
+
+- `getList(): GeoPhoneValue[]` — возвращает полный отсортированный плоский список всех зарегистрированных метаданных международных телефонов.
+- `getMap(): Record<string, GeoPhoneMap>` — возвращает корневой узел внутреннего префиксного дерева, используемого для высокоскоростной идентификации номеров.
+
+## Форматирование и утилиты
+
+### `toMask`
+
+Преобразует сырую числовую строку телефона в отформатированную версию на основе заданного набора масок.
+
+**Параметры:**
+- `phone: string` — необработанный числовой ввод.
+- `masks?: string[]` — массив строк допустимых масок для сопоставления.
+
+**Возвращает:** `string | undefined` — отформатированная строка или `undefined`, если длина ввода не соответствует ни одной маске.
+
+```javascript
+GeoPhone.toMask('9001234567', ['* (***) ***-**-**']) 
+// '7 (900) 123-45-67'
+```
+
+### `removeZero`
+
+Стандартизирует внутреннее представление номера, удаляя ведущие нули или корректируя региональные префиксы для обеспечения согласованной логики поиска.
+
+**Параметры:**
+- `phone: string` — строка входящего номера телефона.
+
+**Возвращает:** `string` — нормализованная числовая строка.
+
+```javascript
+GeoPhone.removeZero('0671234567')  // '671234567'
+GeoPhone.removeZero('89001234567') // '9001234567'
+```
+
+## Объекты GeoPhone
+
+### `GeoPhoneValue`
+Базовая структура метаданных для конфигурации телефона каждой страны:
+- `phone: number` — телефонный код (например, `7`).
+- `within: number` — код внутреннего правила набора.
+- `mask: string[]` — массив паттернов масок.
+- `value: string` — идентификатор страны.
+
+### `GeoPhoneMap`
+Узел внутреннего префиксного дерева:
+- `items: GeoPhoneValue[]` — список элементов в этой ветви.
+- `info: GeoPhoneValue | undefined` — найденное значение в данном конкретном числовом узле.
+- `next: Record<string, GeoPhoneMap>` — указатели на следующие цифры номера в дереве.
+
+## Примеры
+
+```javascript
+import { GeoPhone } from '@dxtmisha/functional'
+
+// 1. Идентификация страны по номеру телефона
+const lookup = GeoPhone.getByPhone('+79001234567')
+if (lookup.item) {
+    console.log('Страна:', lookup.item.value) // 'RU'
+    console.log('Основная маска:', lookup.item.mask[0])
+}
+
+// 2. Ручное форматирование
+const formatted = GeoPhone.toMask('442071234567', ['+** (**) **** ****'])
+console.log(formatted) // '+44 (20) 7123 4567'
+
+// 3. Нормализация ввода для поиска
+const rawInput = '0084901234567'
+const normalized = GeoPhone.removeZero(rawInput.replace(/^00/, ''))
+console.log(normalized) // '84901234567'
+```

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

@@ -0,0 +1,139 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/GeoPhone - Mặt nạ số điện thoại'/>
+
+# Lớp GeoPhone
+
+Lớp chuyên biệt để lưu trữ và xử lý các mặt nạ số điện thoại quốc tế. Nó cung cấp một hệ thống mạnh mẽ để xác định thông tin vị trí địa lý của quốc gia từ các chuỗi số điện thoại, định dạng số thô thành các đặc tả mặt nạ địa phương và quản lý bản đồ mã điện thoại quốc tế dựa trên cấu trúc cây tiền tố (prefix-tree).
+
+Lớp này tích hợp sâu với dữ liệu địa lý `Geo` để cung cấp khả năng tự động phân giải mặt nạ dựa trên vùng locale hiện tại của người dùng hoặc các mã quốc gia cụ thể.
+
+## Các tính năng chính
+
+- **Tự động khớp (Auto Mapping)** — Tự động phân giải quốc gia và mẫu mặt nạ phù hợp một cách động thông qua tra cứu cây tiền tố đệ quy.
+- **Tối ưu hóa Cây Tiền tố (Prefix Tree)** — Sử dụng cấu trúc `map` chuyên biệt (Prefix Tree) để tìm kiếm hiệu quả và hiệu suất cao trên các kế hoạch đánh số quốc tế.
+- **Chuẩn hóa Thông minh** — Tự động xử lý các biến thể quay số theo vùng, chẳng hạn như số 0 ở đầu hoặc các tiền tố quốc gia (ví dụ: số '8' của Nga).
+- **Định dạng Chuẩn hóa** — Chuyển đổi các chuỗi số thô thành các định dạng điện thoại dễ đọc, phù hợp với các tiêu chuẩn viễn thông quốc tế.
+
+## Các phương thức Tìm kiếm
+
+### `getByPhone`
+
+Phương thức định danh chính phân tích một chuỗi số điện thoại để trích xuất thông tin địa lý và mặt nạ đánh số phù hợp nhất.
+
+**Tham số:**
+- `phone: string` — Số điện thoại mục tiêu cần phân tích (chấp nhận các chuỗi thô hoặc đã được định dạng một phần).
+
+**Trả về:** `GeoPhoneMapInfo` — Một đối tượng cấu trúc chứa mục `GeoPhoneMap` khớp được và phần số đã được chuẩn hóa của điện thoại.
+
+```javascript
+import { GeoPhone } from '@dxtmisha/functional-basic'
+
+const info = GeoPhone.getByPhone('84901234567')
+// trả về:
+// { 
+//   item: { info: { phone: 84, ... }, mask: ['+84 ** **** ****'], ... },
+//   phone: '901234567' 
+// }
+```
+
+### `get`
+
+Truy xuất siêu dữ liệu điện thoại đã địa phương hóa được liên kết với một mã quốc gia cụ thể.
+
+**Tham số:**
+- `code: string` — Mã quốc gia tiêu chuẩn ISO 3166 (ví dụ: `'VN'`, `'RU'`, `'US'`).
+
+**Trả về:** `GeoPhoneValue | undefined` — Siêu dữ liệu thô của quốc gia, hoặc `undefined` nếu không tìm thấy trong bộ dữ liệu.
+
+```javascript
+GeoPhone.get('VN') 
+// { phone: 84, within: 0, mask: ['+** ** **** ****'], value: 'VN' }
+```
+
+### `getByCode`
+
+Phương thức truy xuất mở rộng trả về dữ liệu mặt nạ đầy đủ bao gồm cả nút cây tìm kiếm cho một mã quốc gia nhất định.
+
+**Tham số:**
+- `code: string` — Chuỗi mã quốc gia mục tiêu.
+
+**Trả về:** `GeoPhoneMap | undefined` — Đối tượng nút bản đồ đầy đủ cho mã được yêu cầu.
+
+```javascript
+GeoPhone.getByCode('US')
+// { info: { phone: 1, ... }, mask: ['1 (***) ***-****'], ... }
+```
+
+## Các phương thức Truy cập Dữ liệu
+
+- `getList(): GeoPhoneValue[]` — Trả về danh sách phẳng đầy đủ, đã được sắp xếp của tất cả siêu dữ liệu điện thoại quốc tế đã đăng ký.
+- `getMap(): Record<string, GeoPhoneMap>` — Trả về nút gốc của cây tiền tố nội bộ được sử dụng để định danh số điện thoại tốc độ cao.
+
+## Các phương thức Định dạng & Tiện ích
+
+### `toMask`
+
+Chuyển đổi một chuỗi số điện thoại thô thành phiên bản đã được định dạng dựa trên một tập hợp các mặt nạ cụ thể.
+
+**Tham số:**
+- `phone: string` — Đầu vào số thô.
+- `masks?: string[]` — Một mảng các chuỗi mặt nạ hợp lệ để lặp qua nhằm tìm kiếm sự phù hợp.
+
+**Trả về:** `string | undefined` — Chuỗi đã được định dạng cho người dùng, hoặc `undefined` nếu không có độ dài mặt nạ nào khớp với đầu vào.
+
+```javascript
+GeoPhone.toMask('901234567', ['+** ** **** ****']) 
+// '+84 90 1234 567'
+```
+
+### `removeZero`
+
+Chuẩn hóa biểu diễn số nội bộ bằng cách loại bỏ các số 0 ở đầu hoặc sửa các tiền tố quay số vùng để đảm bảo logic tìm kiếm nhất quán.
+
+**Tham số:**
+- `phone: string` — Chuỗi số điện thoại đầu vào.
+
+**Trả về:** `string` — Chuỗi số đã được chuẩn hóa.
+
+```javascript
+GeoPhone.removeZero('0901234567')  // '901234567'
+GeoPhone.removeZero('89001234567') // '9001234567'
+```
+
+## Các đối tượng GeoPhone
+
+### `GeoPhoneValue`
+Cấu trúc siêu dữ liệu cơ bản cho cấu hình điện thoại của mỗi quốc gia:
+- `phone: number` — Mã quay số (ví dụ: `84`).
+- `within: number` — Mã quy tắc quay số nội bộ.
+- `mask: string[]` — Mảng các mẫu mặt nạ.
+- `value: string` — Định danh quốc gia.
+
+### `GeoPhoneMap`
+Một nút trong cây tiền tố nội bộ:
+- `items: GeoPhoneValue[]` — Danh sách các mục thuộc nhánh này.
+- `info: GeoPhoneValue | undefined` — Giá trị khớp tại nút số cụ thể này.
+- `next: Record<string, GeoPhoneMap>` — Con trỏ đến các chữ số tiếp theo trong cây.
+
+## Ví dụ
+
+```javascript
+import { GeoPhone } from '@dxtmisha/functional'
+
+// 1. Định danh quốc gia bằng số điện thoại
+const lookup = GeoPhone.getByPhone('+84901234567')
+if (lookup.item) {
+    console.log('Quốc gia:', lookup.item.value) // 'VN'
+    console.log('Mặt nạ chính:', lookup.item.mask[0])
+}
+
+// 2. Định dạng thủ công
+const formatted = GeoPhone.toMask('442071234567', ['+** (**) **** ****'])
+console.log(formatted) // '+44 (20) 7123 4567'
+
+// 3. Chuẩn hóa đầu vào để tìm kiếm
+const rawInput = '0084901234567'
+const normalized = GeoPhone.removeZero(rawInput.replace(/^00/, ''))
+console.log(normalized) // '84901234567'
+```

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

@@ -0,0 +1,58 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/Global - Global Data'/>
+
+# Global Class
+
+A static utility class for storing and retrieving application-wide global data. Data is written **once** during initialization and is thereafter available as read-only. Used to pass server-side configuration or data to the client-side application.
+
+## Key Features
+
+- **One-time initialization** — The `add` method only works on the first call; subsequent calls are ignored.
+- **Deep copy** — Data is copied via `copyObjectLite`, isolating it from external mutations.
+- **No state management** — Intended purely for static configuration.
+- **Static Access** — all methods are static, eliminating the need for instantiation (`new Global()`).
+
+## Basic Usage
+
+Since the class is static, its methods can be called directly.
+
+```javascript
+import { Global } from '@dxtmisha/functional-basic'
+
+// Set once (e.g., on application load)
+Global.add({
+  apiUrl: 'https://api.myapp.com',
+  appName: 'My Application'
+})
+
+// Retrieve value by key
+console.log(Global.get('apiUrl')) // 'https://api.myapp.com'
+```
+
+## Methods
+
+- `add(data: Record<string, any>): void` — Saves the global data. Only works **on the first call**. Subsequent calls are silently ignored.
+- `get<R>(name: string): R` — Returns the value for a given key from the stored global data.
+
+## Examples
+
+### Retrieving Data
+```javascript
+import { Global } from '@dxtmisha/functional-basic'
+
+const apiUrl = Global.get<string>('apiUrl')
+console.log(apiUrl) // 'https://api.myapp.com'
+
+const flags = Global.get<Record<string, boolean>>('featureFlags')
+console.log(flags.darkMode) // true
+```
+
+### Initialization on App Start
+```javascript
+// main.ts (executed once before mounting the app)
+Global.add(window.__SERVER_DATA__ ?? {})
+
+// Anywhere else in the code
+const serverId = Global.get('serverId')
+```