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