import {Meta} from '@storybook/addon-docs/blocks'

<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 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 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.

## Basic Usage

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'

// Identify country by phone number
const info = GeoPhone.getByPhone('79001234567')
console.log(info.item?.value) // 'RU'

// Formatting by mask
const formatted = GeoPhone.toMask('9001234567', ['+* (***) ***-**-**'])
console.log(formatted) // '+7 (900) 123-45-67'
```

## Methods

### Information

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

### Selection

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

### Auxiliary

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

## Data Types

### `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).

### `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.

## Examples

### 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
const mapInfo = GeoPhone.getByCode('RU')
console.log(mapInfo.mask[0]) // '~ (***) ***-**-**'
```

### Multiple Masks
```javascript
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'
```
