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

<Meta title='@dxtmisha/ru/functional-basic/Classes/Cookie - Управление Cookie'/>

# Класс Cookie

Удобная обертка для управления браузерными куки. Автоматически синхронизируется между памятью и API DOM `document.cookie`, позволяя реактивно устанавливать, извлекать и удалять куки с гарантией согласованных значений по умолчанию.

Включает тесную интеграцию с `CookieStorage` для низкоуровневого управления и уважает глобальную блокировку через `CookieBlock`.

## Ключевые особенности

- **Синхронизация с памятью** — поддерживает запись куки в памяти для предотвращения ненужных обращений к DOM
- **Понимание окружения** — определяет, выполняется ли код в среде DOM. В SSR или при тестировании элегантно переходит на хранение только в памяти
- **Глобальный контроль блокировки** — безопасно интегрируется с `CookieBlock`. Если запись куки глобально отключена, класс уважает это и приостанавливает все изменения в DOM
- **Логика по умолчанию** — получение значения может лениво инициализировать его стандартом по умолчанию, если оно еще не существует

## Конструктор

Экземпляр `Cookie` может быть создан для управления конкретным cookie. Если экземпляр с таким именем уже существует, будет возвращен существующий.

**Параметры:**
- `name: string` — имя cookie для управления

## Методы

### Действие

#### `get`

Читает значение cookie. Если значение не существует и передано значение по умолчанию, оно будет сохранено и возвращено. Поддерживает функции для ленивого вычисления значения по умолчанию.

**Параметры:**
- `defaultValue?: T | string | (() => T | string)` — значение по умолчанию или функция, возвращающая значение
- `options?: CookieOptions` — параметры cookie (используются при установке значения по умолчанию)

**Возвращает:** `T | string | undefined` — значение из куки или заданное по умолчанию

#### `set`

Сохраняет или обновляет значение cookie с указанными параметрами. Поддерживает функции для динамического вычисления значения. Если активна блокировка через `CookieBlock`, значение сохраняется только в памяти.

**Параметры:**
- `value?: T | string | (() => T | string)` — значение для хранения или функция, возвращающая значение
- `options?: CookieOptions` — параметры cookie (время жизни, SameSite, дополнительные аргументы)

**Возвращает:** `void`

#### `remove`

Удаляет cookie, устанавливая пустое значение и Max-Age в `-1`, что заставляет браузер немедленно удалить запись.

**Возвращает:** `void`

### Статические методы

- `getInstance<T>(name: string): Cookie<T>` — Возвращает существующий экземпляр или создает новый по имени

### Вспомогательные

- `CookieStorage.update()` — Обновляет данные из `document.cookie`

## Типы

### `CookieOptions`

Объект конфигурации для параметров cookie:

- `age?: number` — время жизни в секундах (атрибут Max-Age). По умолчанию: 7 дней (604800 сек)
- `sameSite?: 'strict' | 'lax'` — политика SameSite. По умолчанию: `'strict'`
- `arguments?: string[]` — дополнительные директивы для строки cookie

## Примеры

### Базовое использование

```typescript
import { Cookie } from '@dxtmisha/functional'

// Создание экземпляра для управления cookie 'theme'
const themeCookie = new Cookie('theme')

// Чтение с дефолтным значением
const currentTheme = themeCookie.get('dark')

// Установка значения
themeCookie.set('light')

// Установка с параметрами
themeCookie.set('dark', {
  age: 60 * 60 * 24 * 30, // 30 дней
  sameSite: 'lax'
})

// Удаление
themeCookie.remove()
```

### Использование getInstance

```typescript
import { Cookie } from '@dxtmisha/functional'

// Получение или создание экземпляра
const cookie = Cookie.getInstance<string>('user')

// Все вызовы getInstance с одним именем возвращают один и тот же экземпляр
const sameCookie = Cookie.getInstance<string>('user')

console.log(cookie === sameCookie) // true
```

### Интеграция с CookieBlock

```typescript
import { Cookie, CookieBlock } from '@dxtmisha/functional'

// Блокировка всех операций записи
CookieBlock.set(true)

const cookie = new Cookie('blocked')

// Значение сохраняется в памяти, но не в DOM
cookie.set('value')

// Разблокировка
CookieBlock.set(false)

// Теперь запись работает нормально
cookie.set('newValue')
```
