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

<Meta title='@dxtmisha/ru/figma-code/Classes/FigmaStorage - Менеджер хранилища'/>

# Класс FigmaStorage

Класс для управления `PluginData` в Figma. Предоставляет высокоуровневый API для сохранения, получения и контроля срока жизни данных на узлах Figma (по умолчанию — корень документа), с поддержкой кэширования в памяти и значений по умолчанию.

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

- **Персистентность** — Обертка над `getPluginData` и `setPluginData` для удобного хранения данных.
- **Кэширование в памяти** — Сохраняет значения в экземпляре для быстрого доступа во время выполнения.
- **Логика истечения срока** — Поддержка кэширования на основе времени для инвалидации устаревших данных.
- **Функциональные значения** — Поддержка передачи функций в качестве значений или значений по умолчанию для динамической генерации данных.

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

Для инициализации объекта вызовите конструктор `FigmaStorage(name, item, cache)`.

### Параметры универсального типа (Generics)

Класс поддерживает параметр универсального типа для типизированного управления данными:
- `T` — Тип сохраняемого и получаемого значения.

**Параметры:**
- `name: string` — Уникальное имя ключа для элемента хранилища.
- `item: PluginDataMixin = figma.root` — Узел Figma, в котором будут храниться данные. По умолчанию — `figma.root`.
- `cache: number` — (Опционально) Время жизни (TTL) данных в секундах.

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

// 1. Инициализация с неявной типизацией
const settings = new FigmaStorage('plugin-settings')

// 2. Использование дженериков для строгой типизации
interface MyData { theme: string; version: number }
const typedSettings = new FigmaStorage<MyData>('app-data')

// 3. Инициализация с кэшированием на 1 час
const cacheSettings = new FigmaStorage('cache', figma.root, 3600)
```

## Методы

### `get`

Получает данные из хранилища с поддержкой значений по умолчанию и проверки кэша.

**Параметры:**
- `defaultValue: T | (() => T)` — (Опционально) Значение, которое возвращается (и сохраняется), если хранилище пустое или срок действия данных истек.

**Возвращает:** `T | undefined`

```javascript
const val = settings.get('default_val')
```

### `set`

Обновляет данные как в кэше в памяти, так и в `PluginData` узла Figma.

**Параметры:**
- `value: T | (() => T)` — (Опционально) Новое значение или функция, возвращающая новое значение.

**Возвращает:** `T | undefined`

```javascript
settings.set({ theme: 'dark' })
```

### `remove`

Очищает данные как из кэша в памяти, так и из `PluginData` узла Figma.

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

```javascript
settings.remove()
```

### `getName`

Возвращает имя ключа, используемое этим экземпляром хранилища.

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

```javascript
console.log(settings.getName())
```
