@dxtmisha/wiki 0.39.7 → 0.56.0

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

@@ -1,79 +1,122 @@
 import {Meta} from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/vi/functional-basic/Classes/GeoFlag - Cờ Quốc gia'/>
+<Meta title='@dxtmisha/vi/functional-basic/Classes/GeoFlag - Cờ các quốc gia'/>
 
 # Lớp GeoFlag
 
-Một lớp dành cho việc làm việc với cờ quốc gia. Cung cấp giao diện thuận tiện để truy xuất biểu tượng cờ, tên quốc gia và ngôn ngữ đã được bản địa hóa dựa trên mã quốc gia hoặc ngôn ngữ. Sử dụng `Geo` và `GeoIntl` để phân giải các tên gọi đã được bản địa hóa.
+Một lớp để làm việc với cờ các quốc gia và thông tin địa lý. Nó cung cấp một giao diện thuận tiện để lấy các biểu tượng cờ, tên quốc gia và ngôn ngữ đã được bản địa hóa. Nó sử dụng các singleton `Geo` và `GeoIntl` để giải quyết dữ liệu một cách chính xác dựa trên ngôn ngữ hiện tại.
 
-## Tính năng chính
+## Các tính năng chính
 
-- **Từ điển cờ** — Từ điển tĩnh (`flags`) tích hợp sẵn, ánh xạ mã quốc gia ISO 3166-1 alpha-2 tới tên biểu tượng.
-- **Tên gọi đã bản địa hóa** — Trả về tên quốc gia và ngôn ngữ theo ngôn ngữ giao diện hiện tại.
-- **Tên gọi dân tộc** — Phương thức `getNational` trả về tên quốc gia theo ngôn ngữ của chính nước đó.
-- **Lọc linh hoạt** — Các phương thức danh sách hỗ trợ lọc theo mảng mã quốc gia.
+- **Từ điển cờ** — danh sách `flags` tĩnh tích hợp ánh xạ mã ISO 3166-1 alpha-2 với tên biểu tượng.
+- **Dữ liệu được bản địa hóa** — tự động dịch tên quốc gia và ngôn ngữ sang ngôn ngữ giao diện hiện tại.
+- **Hỗ trợ quốc gia** — khả năng lấy tên quốc gia bằng ngôn ngữ "gốc" của họ (ví dụ: "Nhật Bản" và "日本" đồng thời).
+- **Khả năng mở rộng** — hỗ trợ lọc và lấy danh sách đầy đủ cho các bộ chọn quốc gia.
 
 ## Khởi tạo
 
-Tạo một thực thể `GeoFlag` mới với mã quốc gia hoặc ngôn ngữ tùy chọn.
+Để tạo một thực thể, hãy sử dụng constructor `GeoFlag(code)`.
 
 **Tham số:**
-- `code?: string` — Mã quốc gia hoặc ngôn ngữ (ví dụ: `'VN'`, `'vi-VN'`). Mặc định sử dụng ngôn ngữ hiện tại từ `Geo`.
+- `code?: string` — mã quốc gia hoặc ngôn ngữ (ví dụ: `'VN'`, `'vi-VN'`). Nếu không được chỉ định, ngôn ngữ hiện tại từ hệ thống `Geo` sẽ được sử dụng.
 
 ```javascript
 import { GeoFlag } from '@dxtmisha/functional-basic'
 
-// Tạo với ngôn ngữ hiện tại
+// Với ngôn ngữ hiện tại
 const flag = new GeoFlag()
 
-// Tạo cho một quốc gia cụ thể
+// Cho một quốc gia cụ thể
 const vnFlag = new GeoFlag('vi-VN')
 ```
 
-## Phương thức
+## Các phương thức
 
-### Truy xuất dữ liệu
+### Lấy dữ liệu
+- `get(code?: string): GeoFlagItem | undefined` — Trả về một đối tượng dữ liệu đầy đủ về một quốc gia.
+- `getFlag(code?: string): string | undefined` — Trả về chỉ định danh biểu tượng cờ (ví dụ: `'f-vn'`).
 
-- `get(code?: string): GeoFlagItem | undefined` — Trả về đối tượng dữ liệu đầy đủ về một quốc gia: ngôn ngữ, mã quốc gia, tiêu chuẩn và tên biểu tượng cờ. Nếu không có mã, sử dụng mã từ constructor.
-- `getFlag(code?: string): string | undefined` — Chỉ trả về tên biểu tượng cờ của quốc gia được chỉ định.
-- `getList(codes?: string[]): GeoFlagItem[]` — Trả về mảng các đối tượng dữ liệu cờ. Nếu `codes` không được cung cấp, trả về tất cả các quốc gia từ từ điển.
-- `getNational(codes?: string[]): GeoFlagNational[]` — Tương tự `getList`, nhưng bổ sung tên quốc gia theo ngôn ngữ của chính nước đó.
+### Danh sách
+- `getList(codes?: string[]): GeoFlagItem[]` — Trả về một mảng dữ liệu quốc gia.
+- `getNational(codes?: string[]): GeoFlagNational[]` — Trả về danh sách các quốc gia với tên quốc gia gốc.
 
-### Thay đổi dữ liệu
+### Cấu hình
+- `setCode(code: string): this` — Thay đổi ngôn ngữ cơ sở cho thực thể hiện tại.
 
-- `setCode(code: string): this` — Thay đổi mã quốc gia cho thực thể hiện tại.
+## Các phương thức danh sách
 
-## Ví dụ
+Sự khác biệt chính giữa các phương thức nằm ở ngôn ngữ mà tên quốc gia và ngôn ngữ được trả về:
 
-### Hiển thị cờ cho quốc gia hiện tại
-```javascript
-import { GeoFlag } from '@dxtmisha/functional-basic'
+*   **`getList`** — trả về tên chỉ bằng ngôn ngữ được thiết lập trong thực thể lớp (ví dụ: tất cả bằng tiếng Việt).
+*   **`getNational`** — trả về tên bằng ngôn ngữ giao diện của bạn + thêm tên gốc bằng ngôn ngữ của chính quốc gia đó (ví dụ: "Nhật Bản" và "日本").
 
-const flag = new GeoFlag()
-const item = flag.get()
+### Ví dụ về sự khác biệt trong kết quả:
 
-console.log(item?.icon)    // 'f-vn'
-console.log(item?.country) // 'Việt Nam'
+```javascript
+const geo = new GeoFlag('vi-VN') // Ngôn ngữ tiếng Việt được thiết lập
+
+// 1. getList chỉ trả về bản dịch
+const list = geo.getList(['JP']) 
+/* 
+[{ country: 'Nhật Bản', ... }] 
+*/
+
+// 2. getNational trả về bản dịch + tên gốc
+const national = geo.getNational(['JP']) 
+/* 
+[{ 
+  country: 'Nhật Bản', 
+  nationalCountry: '日本', 
+  ... 
+}] 
+*/
 ```
 
-### Danh sách tất cả quốc gia với cờ
-```javascript
-const flag = new GeoFlag('vi-VN')
-const countries = flag.getList()
+## Các kiểu dữ liệu
 
-countries.forEach(item => {
-  console.log(`${item.icon}: ${item.country}`)
-})
-// 'f-us: Hoa Kỳ', 'f-fr: Pháp', ...
-```
+### `GeoFlagItem`
+Đối tượng thông tin cờ cơ bản.
+- `country`: string — Tên quốc gia đã được bản địa hóa.
+- `language`: string — Tên ngôn ngữ đã được bản địa hóa.
+- `standard`: string — Tiêu chuẩn ngôn ngữ đầy đủ (ví dụ: `vi-VN`).
+- `icon`: string — Tên biểu tượng cờ (tiền tố `f-`).
+- `label`: string — Nhãn hiển thị (mặc định khớp với `country`).
+- `value`: string — Mã quốc gia (ISO alpha-2).
 
-### Danh sách với tên gọi dân tộc
-```javascript
-// Trả về tên quốc gia bằng cả ngôn ngữ của bạn và ngôn ngữ của chính nước đó
-const national = new GeoFlag('vi-VN').getNational(['US', 'JP', 'RU'])
+### `GeoFlagNational`
+Mở rộng `GeoFlagItem` với các trường bổ sung:
+- `nationalCountry`: string — Tên quốc gia bằng ngôn ngữ gốc.
+- `nationalLanguage`: string — Tên ngôn ngữ bằng ngôn ngữ gốc.
+- `description`: string — Mô tả ngắn gọn (sao chép `nationalCountry`).
 
-national.forEach(item => {
-  console.log(`${item.country} (${item.nationalCountry})`)
-})
-// Hoa Kỳ (United States), Nhật Bản (日本), Nga (Россия)
+## Ví dụ
+
+### Danh sách các quốc gia phổ biến với tên quốc gia gốc
+```javascript
+const geo = new GeoFlag('vi-VN')
+const list = geo.getNational(['VN', 'CN', 'JP'])
+
+/* 
+Kết quả:
+[
+  { 
+    country: 'Việt Nam', 
+    nationalCountry: 'Việt Nam', 
+    icon: 'f-vn', 
+    ... 
+  },
+  { 
+    country: 'Trung Quốc', 
+    nationalCountry: '中国', 
+    icon: 'f-cn', 
+    ... 
+  },
+  { 
+    country: 'Nhật Bản', 
+    nationalCountry: '日本', 
+    icon: 'f-jp', 
+    ... 
+  }
+]
+*/
 ```

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

@@ -0,0 +1,81 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/GeoInstance - Geographic Data Instance'/>
+
+# GeoInstance Class
+
+An instance-based class for managing geographical data. It handles language codes (ISO 639-1), country codes (ISO 3166-1 alpha-2), time zones, and localization. Unlike the static `Geo` class, `GeoInstance` allows creating independent objects with their own state, which is particularly useful for request isolation in SSR or multi-context environments.
+
+## Key Features
+
+- **Object-Oriented** — allows creating multiple instances with different configurations.
+- **Auto-Detection** — intelligently identifies the locale via storage or environment defaults during initialization.
+- **Media Database Integration** — provides access to a comprehensive database of countries and languages from the `@dxtmisha/media` library.
+- **Dynamic Time Management** — instance-level setting and retrieval of time zone offsets.
+
+## Basic Usage
+
+You can create a new instance of the class to manage a specific geographic context.
+
+```javascript
+import { GeoInstance } from '@dxtmisha/functional-basic'
+
+const geo = new GeoInstance()
+
+// Get the current language code
+console.log(geo.getLanguage()) // e.g., 'en'
+
+// Set a new locale for this instance
+geo.set('fr-FR')
+
+// Get the formatted time zone
+console.log(geo.getTimezoneFormat()) // e.g., '+00:00'
+```
+
+## Methods
+
+### Information
+
+- `get(): GeoItemFull` — Returns the full data object for the current country and language.
+- `getItem(): GeoItemFull` — Returns a copy of the current settings object, accounting for the dynamic language.
+- `getCountry(): string` — Returns the 2-letter code of the current country (uppercase).
+- `getLanguage(): string` — Returns the 2-letter code of the current language (lowercase).
+- `getStandard(): string` — Returns the combined locale string based on current settings (e.g., `'en-VN'`).
+- `getLocation(): string` — Returns the currently set raw locale string.
+- `getFirstDay(): string` — Returns the code for the first day of the week (e.g., `'Mo'`).
+- `getTimezone(): number` — Returns the time zone offset in minutes.
+- `getTimezoneFormat(): string` — Returns the time zone offset in string format (e.g., `'+03:00'`).
+
+### Selection
+
+- `getList(): GeoItem[]` — Returns the full list of available countries and languages.
+- `find(code: string): GeoItemFull` — An alias for the `getByCode` method.
+- `getByCode(code?: string): GeoItemFull` — Searches for data by code. **Priority: Language first**, then Country. If `en-VN` is provided, it will return the record for English (`en-US`).
+- `getByCodeFull(code: string): GeoItem | undefined` — Searches for an exact match by full locale code (e.g., `ru-RU`).
+- `getByCountry(country: string): GeoItem | undefined` — Searches for data specifically by country code.
+- `getByLanguage(language: string): GeoItem | undefined` — Searches for data specifically by language code.
+
+### Configuration
+
+- `set(code: string, save?: boolean): void` — Sets the locale for the current instance.
+- `setTimezone(timezone: number): void` — Sets a custom time zone offset in minutes.
+
+### Auxiliary
+
+- `toStandard(item: GeoItem): string` — Generates a standard `'language-country'` string from a `GeoItem` object.
+
+## Examples
+
+### Isolated Contexts
+```javascript
+import { GeoInstance } from '@dxtmisha/functional-basic'
+
+const geoEN = new GeoInstance()
+geoEN.set('en-US')
+
+const geoRU = new GeoInstance()
+geoRU.set('ru-RU')
+
+console.log(geoEN.getLanguage()) // 'en'
+console.log(geoRU.getLanguage()) // 'ru'
+```

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

@@ -0,0 +1,81 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/GeoInstance - Экземпляр Географических Данных'/>
+
+# Класс GeoInstance
+
+Класс для работы с географическими данными на уровне экземпляра. Он отвечает за обработку кодов языков (ISO 639-1), стран (ISO 3166-1 alpha-2), временных зон и локализации. В отличие от статического класса `Geo`, `GeoInstance` позволяет создавать независимые объекты со своим состоянием, что особенно важно для изоляции запросов в SSR или в приложениях с несколькими контекстами локализации.
+
+## Ключевые особенности
+
+- **Объектно-ориентированность** — позволяет создавать несколько экземпляров с разными конфигурациями.
+- **Автоматическое определение** — интеллектуально определяет локаль через хранилище или настройки окружения при инициализации.
+- **Интеграция с медиа-базой** — предоставляет доступ к полной базе данных стран и языков из библиотеки `@dxtmisha/media`.
+- **Динамическое управление временем** — установка и получение смещения часового пояса на уровне конкретного экземпляра.
+
+## Базовое использование
+
+Вы можете создать новый экземпляр класса для управления специфическим географическим контекстом.
+
+```javascript
+import { GeoInstance } from '@dxtmisha/functional-basic'
+
+const geo = new GeoInstance()
+
+// Получаем текущий код языка
+console.log(geo.getLanguage()) // например, 'ru'
+
+// Устанавливаем новую локаль для этого экземпляра
+geo.set('en-US')
+
+// Получаем форматированную временную зону
+console.log(geo.getTimezoneFormat()) // например, '+03:00'
+```
+
+## Методы
+
+### Информация
+
+- `get(): GeoItemFull` — Возвращает полный объект данных о текущей стране и языке.
+- `getItem(): GeoItemFull` — Возвращает копию объекта текущих настроек с учетом динамически установленного языка.
+- `getCountry(): string` — Возвращает 2-буквенный код текущей страны (в верхнем регистре).
+- `getLanguage(): string` — Возвращает 2-буквенный код текущего языка (в нижнем регистре).
+- `getStandard(): string` — Возвращает комбинированную строку локали на основе текущих настроек (например, `'en-VN'`).
+- `getLocation(): string` — Возвращает текущую установленную локаль в виде "сырой" строки.
+- `getFirstDay(): string` — Возвращает код первого дня недели для текущей локали (например, `'Mo'`).
+- `getTimezone(): number` — Возвращает смещение часового пояса в минутах.
+- `getTimezoneFormat(): string` — Возвращает смещение часового пояса в строковом формате (например, `'+03:00'`).
+
+### Выбор
+
+- `getList(): GeoItem[]` — Возвращает полный список доступных стран и языков.
+- `find(code: string): GeoItemFull` — Алиас для метода `getByCode`.
+- `getByCode(code?: string): GeoItemFull` — Ищет данные по коду. **Приоритет: сначала язык**, затем страна. Если передан код `en-VN`, будет возвращена запись для английского языка (`en-US`).
+- `getByCodeFull(code: string): GeoItem | undefined` — Ищет точное совпадение по полному коду локали (например, `ru-RU`).
+- `getByCountry(country: string): GeoItem | undefined` — Ищет данные конкретно по коду страны.
+- `getByLanguage(language: string): GeoItem | undefined` — Ищет данные конкретно по коду языка.
+
+### Конфигурация
+
+- `set(code: string, save?: boolean): void` — Устанавливает локаль для текущего экземпляра.
+- `setTimezone(timezone: number): void` — Устанавливает кастомное смещение часового пояса в минутах.
+
+### Вспомогательные методы
+
+- `toStandard(item: GeoItem): string` — Метод для формирования стандартной строки `'язык-страна'` из объекта `GeoItem`.
+
+## Примеры
+
+### Изолированные контексты
+```javascript
+import { GeoInstance } from '@dxtmisha/functional-basic'
+
+const geoRU = new GeoInstance()
+geoRU.set('ru-RU')
+
+const geoEN = new GeoInstance()
+geoEN.set('en-US')
+
+console.log(geoRU.getLanguage()) // 'ru'
+console.log(geoEN.getLanguage()) // 'en'
+```

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

@@ -0,0 +1,81 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/GeoInstance - Đối Tượng Dữ Liệu Địa Lý'/>
+
+# Lớp GeoInstance
+
+Một lớp dựa trên đối tượng (instance-based) để quản lý dữ liệu địa lý. Nó xử lý các mã ngôn ngữ (ISO 639-1), mã quốc gia (ISO 3166-1 alpha-2), múi giờ và địa phương hóa. Khác với lớp tĩnh `Geo`, `GeoInstance` cho phép tạo các đối tượng độc lập với trạng thái riêng, điều này đặc biệt hữu ích cho việc cô lập yêu cầu (request isolation) trong môi trường SSR hoặc các ứng dụng đa ngữ cảnh.
+
+## Tính năng chính
+
+- **Hướng đối tượng** — cho phép tạo nhiều phiên bản (instances) with các cấu hình khác nhau.
+- **Tự động phát hiện** — xác định thông minh địa phương (locale) thông qua bộ nhớ lưu trữ hoặc các mặc định của môi trường khi khởi tạo.
+- **Tích hợp cơ sở dữ liệu truyền thông** — cung cấp quyền truy cập vào cơ sở dữ liệu toàn diện về các quốc gia và ngôn ngữ từ thư viện `@dxtmisha/media`.
+- **Quản lý thời gian linh hoạt** — thiết lập và truy xuất độ lệch múi giờ ở cấp độ đối tượng.
+
+## Cách sử dụng cơ bản
+
+Bạn có thể tạo một đối tượng mới của lớp để quản lý một ngữ cảnh địa lý cụ thể.
+
+```javascript
+import { GeoInstance } from '@dxtmisha/functional-basic'
+
+const geo = new GeoInstance()
+
+// Lấy mã ngôn ngữ hiện tại
+console.log(geo.getLanguage()) // ví dụ: 'vi'
+
+// Thiết lập địa phương mới cho đối tượng này
+geo.set('en-US')
+
+// Lấy múi giờ đã định dạng
+console.log(geo.getTimezoneFormat()) // ví dụ: '+07:00'
+```
+
+## Các phương thức
+
+### Thông tin
+
+- `get(): GeoItemFull` — Trả về đối tượng dữ liệu đầy đủ cho quốc gia và ngôn ngữ hiện tại.
+- `getItem(): GeoItemFull` — Trả về một bản sao của đối tượng cài đặt hiện tại, có tính đến ngôn ngữ động.
+- `getCountry(): string` — Trả về mã 2 chữ cái của quốc gia hiện tại (viết hoa).
+- `getLanguage(): string` — Trả về mã 2 chữ cái của ngôn ngữ hiện tại (viết thường).
+- `getStandard(): string` — Trả về chuỗi địa phương kết hợp dựa trên cài đặt hiện tại (ví dụ: `'en-VN'`).
+- `getLocation(): string` — Trả về chuỗi địa phương thô hiện đang được thiết lập.
+- `getFirstDay(): string` — Trả về mã cho ngày đầu tiên của tuần của địa phương hiện tại (ví dụ: `'Mo'`).
+- `getTimezone(): number` — Trả về độ lệch múi giờ tính bằng phút.
+- `getTimezoneFormat(): string` — Trả về độ lệch múi giờ ở định dạng chuỗi (ví dụ: `'+07:00'`).
+
+### Lựa chọn
+
+- `getList(): GeoItem[]` — Trả về danh sách đầy đủ các quốc gia và ngôn ngữ có sẵn.
+- `find(code: string): GeoItemFull` — Một bí danh cho phương thức `getByCode`.
+- `getByCode(code?: string): GeoItemFull` — Tìm kiếm dữ liệu theo mã. **Ưu tiên: Ngôn ngữ trước**, sau đó đến Quốc gia. Nếu cung cấp mã `en-VN`, nó sẽ trả về bản ghi cho tiếng Anh (`en-US`).
+- `getByCodeFull(code: string): GeoItem | undefined` — Tìm kiếm kết quả khớp chính xác theo mã địa phương đầy đủ (ví dụ: `vi-VN`).
+- `getByCountry(country: string): GeoItem | undefined` — Tìm kiếm dữ liệu cụ thể theo mã quốc gia.
+- `getByLanguage(language: string): GeoItem | undefined` — Tìm kiếm dữ liệu cụ thể theo mã ngôn ngữ.
+
+### Cấu hình
+
+- `set(code: string, save?: boolean): void` — Thiết lập địa phương cho đối tượng hiện tại.
+- `setTimezone(timezone: number): void` — Thiết lập độ lệch múi giờ tùy chỉnh tính bằng phút.
+
+### Phụ trợ
+
+- `toStandard(item: GeoItem): string` — Tạo chuỗi `'ngôn ngữ-quốc gia'` tiêu chuẩn từ đối tượng `GeoItem`.
+
+## Ví dụ
+
+### Ngữ cảnh độc lập
+```javascript
+import { GeoInstance } from '@dxtmisha/functional-basic'
+
+const geoVI = new GeoInstance()
+geoVI.set('vi-VN')
+
+const geoEN = new GeoInstance()
+geoEN.set('en-US')
+
+console.log(geoVI.getLanguage()) // 'vi'
+console.log(geoEN.getLanguage()) // 'en'
+```

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

@@ -1,139 +1,90 @@
 import {Meta} from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/en/functional-basic/Classes/GeoPhone - Phone Number Masks'/>
+<Meta title='@dxtmisha/en/functional-basic/Classes/GeoPhone - Phone 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.
+A specialized class for storing and processing international phone number masks. It provides a mechanism for identifying a country by a phone number string, formatting raw numbers into localized masks, and managing a complex map of phone codes based on a prefix tree. The class is closely integrated with `Geo` data, allowing for automatic mask determination based on the user's current locale or provided 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.
+- **Automatic Matching** — Dynamically determines the appropriate country and mask pattern through recursive searching in a prefix tree.
+- **Prefix Tree Optimization** — Uses a specialized `map` structure (Trie) for high-performance searching.
+- **Intelligent Normalization** — Automatically handles regional dialing variations such as leading zeros or national prefixes.
+- **Standardized Formatting** — Converts raw numeric strings into readable formats.
 
-**Parameters:**
-- `phone: string` — The target phone number to analyze (accepts raw or partially formatted strings).
+## Basic Usage
 
-**Returns:** `GeoPhoneMapInfo` — A structured payload containing the matched `GeoPhoneMap` item and the normalized numeric portion of the phone.
+You can use the static methods of the class for rapid country identification by phone number or formatting.
 
 ```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'`).
+// Identify country by phone number
+const info = GeoPhone.getByPhone('79001234567')
+console.log(info.item?.value) // 'RU'
 
-**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' }
+// Formatting by mask
+const formatted = GeoPhone.toMask('9001234567', ['+* (***) ***-**-**'])
+console.log(formatted) // '+7 (900) 123-45-67'
 ```
 
-### `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.
+## Methods
 
-**Returns:** `GeoPhoneMap | undefined` — The full map node object for the requested code.
-
-```javascript
-GeoPhone.getByCode('RU')
-// { info: { phone: 7, ... }, mask: ['7 (***) ***-**-**'], ... }
-```
+### Information
 
-## Data Access Methods
+- `getList(): GeoPhoneValue[]` — Returns a 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 searching.
 
-- `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.
+### Selection
 
-## Formatting & Utility Methods
+- `get(code: string): GeoPhoneValue | undefined` — Retrieves phone metadata associated with a specific country code.
+- `getByPhone(phone: string): GeoPhoneMapInfo` — Analyzes a phone number string to extract information and the suitable mask.
+- `getByCode(code: string): GeoPhoneMap | undefined` — Returns complete mask information, including the search tree node for a given code.
 
-### `toMask`
+### Auxiliary
 
-Transforms a raw numeric phone string into a formatted version based on a specified set of masks.
+- `toMask(phone: string, masks?: string[]): string | undefined` — Converts a raw numeric phone string into a formatted version.
+- `removeZero(phone: string): string` — Standardizes the internal representation of a number by removing leading zeros or adjusting regional prefixes.
 
-**Parameters:**
-- `phone: string` — The raw numeric input.
-- `masks?: string[]` — An array of valid mask strings to iterate through for property matching.
+## Data Types
 
-**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`
+### `GeoPhoneValue`
+Basic metadata structure for each country's phone configuration:
+- `phone: number` — Phone country code (e.g., `7`).
+- `within: number` — Internal dialing rule code (used to select the special symbol in the mask).
+- `mask: string[]` — Array of mask patterns assigned to the country.
+- `value: string` — Country identifier (ISO 3166).
 
-Standardizes internal number representation by stripping leading trunk zeros or correcting regional dialing prefixes to ensure consistent search logic.
+### `GeoPhoneMap`
+A node in the internal prefix tree (Trie) used for searching:
+- `items: GeoPhoneValue[]` — List of all items available in this branch of the tree.
+- `info: GeoPhoneValue | undefined` — Phone metadata if the current node is a complete code.
+- `value: string | undefined` — Country identifier for this node.
+- `mask: string[]` — Array of masks with substituted internal symbols (`~`, `=`, `$`).
+- `maskFull: string[]` — Full masks including the international code.
+- `next: Record<string, GeoPhoneMap>` — Pointers to the next digits in the search tree.
+
+### `GeoPhoneMapInfo`
+Result of the `getByPhone` search method:
+- `item?: GeoPhoneMap` — The found tree node with country and mask information.
+- `phone?: string` — The remaining part of the number after separating the country code.
 
-**Parameters:**
-- `phone: string` — The input phone number string.
+## Examples
 
-**Returns:** `string` — The normalized numeric string.
+### Internal Symbols (Within Logic)
+The class's internal logic replaces the first "asterisk" in the mask with a special symbol depending on regional rules:
+- `~` — for Russia (internal code 8).
+- `=` — for default/other regions (e.g., USA).
 
 ```javascript
-GeoPhone.removeZero('0671234567')  // '671234567'
-GeoPhone.removeZero('89001234567') // '9001234567'
+const mapInfo = GeoPhone.getByCode('RU')
+console.log(mapInfo.mask[0]) // '~ (***) ***-**-**'
 ```
 
-## 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
-
+### Multiple Masks
 ```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'
+const masks = ['+* (***) ***-**-**', '+* (***) ***-***']
+console.log(GeoPhone.toMask('79991234567', masks)) // 11 digits -> '+7 (999) 123-45-67'
+console.log(GeoPhone.toMask('7999123456', masks))  // 10 digits -> '+7 (999) 123-456'
 ```