@dxtmisha/wiki 0.39.6 → 0.39.8

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'
 ```

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

@@ -4,136 +4,87 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 # Класс GeoPhone
 
-Специализированный класс для хранения и обработки масок международных телефонных номеров. Обеспечивает мощный механизм идентификации географической информации о стране по строке номера, форматирование необработанных чисел в локализованные маски и управление комплексной картой телефонных кодов на базе префиксного дерева.
-
-Класс тесно интегрирован с гео-данными `Geo`, что позволяет автоматически определять маску на основе текущей локали пользователя или переданных кодов стран.
+Специализированный класс для хранения и обработки масок международных телефонных номеров. Обеспечивает механизм идентификации страны по строке номера, форматирование необработанных чисел в локализованные маски и управление комплексной картой телефонных кодов на базе префиксного дерева. Класс тесно интегрирован с гео-данными `Geo`, что позволяет автоматически определять маску на основе текущей локали пользователя или переданных кодов стран.
 
 ## Ключевые особенности
 
 - **Автоматическое сопоставление** — динамически определяет подходящую страну и паттерн маски через рекурсивный поиск по префиксному дереву.
-- **Оптимизация дерева префиксов** — использует специализированную структуру `map` (Trie/Prefix Tree) для высокопроизводительного поиска по международным планам нумерации.
-- **Интеллектуальная нормализация** — автоматически обрабатывает региональные вариации набора, такие как ведущие нули или национальные префиксы (например, российская «8»).
-- **Стандартизированное форматирование** — преобразует сырые числовые строки в читаемые форматы, соответствующие международным стандартам телефонии.
-
-## Методы поиска
-
-### `getByPhone`
-
-Основной метод идентификации, который анализирует строку номера телефона для извлечения географической информации и наиболее подходящей маски нумерации.
+- **Оптимизация дерева префиксов** — использует специализированную структуру `map` (Trie) для высокопроизводительного поиска.
+- **Интеллектуальная нормализация** — автоматически обрабатывает региональные вариации набора, такие как ведущие нули или национальные префиксы.
+- **Стандартизированное форматирование** — преобразует сырые числовые строки в читаемые форматы.
 
-**Параметры:**
-- `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'`).
+console.log(info.item?.value) // 'RU'
 
-**Возвращает:** `GeoPhoneValue | undefined` — сырые метаданные для страны или `undefined`, если код не найден в базе.
-
-```javascript
-GeoPhone.get('RU') 
-// { phone: 7, within: 8, mask: ['* (***) ***-**-**'], value: 'RU' }
+// Форматирование по маске
+const formatted = GeoPhone.toMask('9001234567', ['+* (***) ***-**-**'])
+console.log(formatted) // '+7 (900) 123-45-67'
 ```
 
-### `getByCode`
-
-Расширенный метод получения данных, который возвращает полную информацию о маске, включая узел дерева поиска для заданного кода страны.
-
-**Параметры:**
-- `code: string` — строка целевого кода страны.
-
-**Возвращает:** `GeoPhoneMap | undefined` — объект узла карты для запрошенного кода.
-
-```javascript
-GeoPhone.getByCode('US')
-// { info: { phone: 1, ... }, mask: ['1 (***) ***-****'], ... }
-```
+## Методы
 
-## Методы доступа к данным
+### Информация
 
-- `getList(): GeoPhoneValue[]` — возвращает полный отсортированный плоский список всех зарегистрированных метаданных международных телефонов.
-- `getMap(): Record<string, GeoPhoneMap>` — возвращает корневой узел внутреннего префиксного дерева, используемого для высокоскоростной идентификации номеров.
+- `getList(): GeoPhoneValue[]` — Возвращает полный отсортированный плоский список всех зарегистрированных метаданных международных телефонов.
+- `getMap(): Record<string, GeoPhoneMap>` — Возвращает корневой узел внутреннего префиксного дерева для поиска.
 
-## Форматирование и утилиты
+### Выбор
 
-### `toMask`
+- `get(code: string): GeoPhoneValue | undefined` — Извлекает метаданные телефона, связанные с конкретным кодом страны.
+- `getByPhone(phone: string): GeoPhoneMapInfo` — Анализирует строку номера телефона для извлечения информации и подходящей маски.
+- `getByCode(code: string): GeoPhoneMap | undefined` — Возвращает полную информацию о маске, включая узел дерева поиска для заданного кода.
 
-Преобразует сырую числовую строку телефона в отформатированную версию на основе заданного набора масок.
+### Вспомогательные методы
 
-**Параметры:**
-- `phone: string` — необработанный числовой ввод.
-- `masks?: string[]` — массив строк допустимых масок для сопоставления.
+- `toMask(phone: string, masks?: string[]): string | undefined` — Преобразует сырую числовую строку телефона в отформатированную версию.
+- `removeZero(phone: string): 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` — идентификатор страны.
+- `phone: number` — Телефонный код страны (например, `7`).
+- `within: number` — Код внутреннего правила набора (используется для выбора спецсимвола в маске).
+- `mask: string[]` — Массив паттернов масок, закрепленных за страной.
+- `value: string` — Идентификатор страны (ISO 3166).
 
 ### `GeoPhoneMap`
-Узел внутреннего префиксного дерева:
-- `items: GeoPhoneValue[]` — список элементов в этой ветви.
-- `info: GeoPhoneValue | undefined` — найденное значение в данном конкретном числовом узле.
-- `next: Record<string, GeoPhoneMap>` — указатели на следующие цифры номера в дереве.
+Узел внутреннего префиксного дерева (Trie), используемый для поиска:
+- `items: GeoPhoneValue[]` — Список всех элементов, доступных в данной ветви дерева.
+- `info: GeoPhoneValue | undefined` — Метаданные телефона, если текущий узел является завершенным кодом.
+- `value: string | undefined` — Идентификатор страны для данного узла.
+- `mask: string[]` — Массив масок с подставленными спецсимволами (`~`, `=`, `$`).
+- `maskFull: string[]` — Полные маски, включая международный код.
+- `next: Record<string, GeoPhoneMap>` — Указатели на следующие цифры номера в дереве поиска.
+
+### `GeoPhoneMapInfo`
+Результат выполнения метода поиска `getByPhone`:
+- `item?: GeoPhoneMap` — Найденный узел дерева с информацией о стране и масках.
+- `phone?: string` — Оставшаяся часть номера после отделения кода страны.
 
 ## Примеры
 
+### Работа со спецсимволами (Within)
+Внутренняя логика класса заменяет первую "звездочку" в маске на спецсимвол в зависимости от региональных правил:
+- `~` — для России (код внутри страны 8).
+- `$` — для некоторых других регионов.
+
+```javascript
+const mapInfo = GeoPhone.getByCode('RU')
+console.log(mapInfo.mask[0]) // '~ (***) ***-**-**'
+```
+
+### Множественные маски
 ```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'
+const masks = ['+* (***) ***-**-**', '+* (***) ***-***']
+console.log(GeoPhone.toMask('79991234567', masks)) // 11 цифр -> '+7 (999) 123-45-67'
+console.log(GeoPhone.toMask('7999123456', masks))  // 10 цифр -> '+7 (999) 123-456'
 ```