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

<Meta title='@dxtmisha/ru/figma-code/Classes/FigmaStorageData - Контейнер данных хранилища'/>

# Класс `FigmaStorageData`

Низкоуровневый контейнер для управления отдельными записями данных в системах хранения Figma (Client Storage или Plugin Data). Он отслеживает значения вместе с временем их обновления (возрастом) и обрабатывает логику истечения срока действия кэша.

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

- **Отслеживание кэша** — Автоматически определяет, актуальны ли данные на основе настраиваемого времени жизни (TTL).
- **Мониторинг обновлений** — Сохраняет метку времени последнего обновления для облегчения проверки свежести данных.
- **Готовность к сериализации** — Предоставляет методы для преобразования данных в стандартный формат хранения (`FigmaStorageDataValue`) и обратно.

## Инициализация

Инициализируется именем ключа и опциональным временем кэширования в секундах.

```typescript
import { FigmaStorageData } from '@dxtmisha/figma-code'

// Кэш на 1 час (3600 секунд)
const dataContainer = new FigmaStorageData<string>('user-name', 3600)
```

## Методы

### Проверка состояния

- `isNull(): boolean` — Проверяет, является ли текущее значение null или undefined.
- `isCache(): boolean` — Проверяет, находятся ли данные в пределах разрешенного времени жизни кэша.
- `isValue(): boolean` — Возвращает true, если значение определено и кэш валиден.

### Аксессоры

- `get(): T | undefined` — Возвращает текущее значение.
- `getAge(): number | undefined` — Возвращает метку времени последнего обновления.
- `getName(): string` — Возвращает уникальное имя ключа хранилища (с префиксом).
- `getCache(): number | undefined` — Возвращает настроенное время кэширования.

### Модификаторы

- `set(value?: T, age?: number): this` — Вручную устанавливает значение и время.
- `setByObject(value?: FigmaStorageDataValue<T>): this` — Устанавливает данные из объекта хранилища.
- `update(value?: T): this` — Обновляет значение и устанавливает текущую метку времени.
- `remove(): this` — Очищает значение и время.

### Преобразование

- `toValue(): FigmaStorageDataValue<T>` — Преобразует текущее состояние в объект, совместимый с хранилищем.

## Типы данных

#### `FigmaStorageDataValue<T>`
Структура, используемая для постоянного хранения.
- `value: T` — Фактические данные.
- `age: number` — Метка времени (мс) момента сохранения данных.
