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

<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesCache - Оркестратор постоянного кэша'/>

# Класс PropertiesCache

Класс `PropertiesCache` — это высокопроизводительная статическая утилита, предназначенная для управления постоянным файловым кэшированием в инструментарии дизайн-системы. Он гарантирует, что сложные трансформации токенов выполняются только при необходимости, значительно сокращая время сборки для крупных проектов за счет отслеживания зависимостей файлов и поддержки структурированной иерархии кэша.

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

- **Отслеживание зависимостей** — автоматически отслеживает изменения исходных файлов и аннулирует кэш, если любая зависимость была изменена.
- **Иерархическое хранение** — организует кэшированные данные в скрытой директории `.cache` со специализированными подпапками для различных этапов обработки.
- **Инкрементальные сборки** — позволяет выполнять частичное перевычисление за счет хранения промежуточных результатов трансформации.
- **Целостность системы** — ведет реестр `system.json` для отслеживания временных меток кэша и метаданных файлов.
- **Поддержка Generic** — обеспечивает полную поддержку TypeScript для типобезопасного извлечения кэшированных структур данных.

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

Являясь статическим классом, `PropertiesCache` не требует создания экземпляра. Доступ к его методам осуществляется напрямую.

```typescript
import { PropertiesCache } from '@dxtmisha/scripts'

// Извлечение данных с автоматическим управлением кэшем
const data = PropertiesCache.get(
  ['tokens', 'color'], 
  'palette-cache', 
  () => transformPaletteLogic()
)

// Очистка всех кэшированных данных
PropertiesCache.clear()
```

## Методы

### Операции с кэшем

- `get<T>(path, name, callback, extension): T` — извлекает данные из кэша или регенерирует их через функцию обратного вызова.
- `read<R>(path): R | undefined` — читает файл и регистрирует его как зависимость кэша.
- `write<T>(name, value): void` — сохраняет промежуточные результаты обработки во временный кэш.
- `clear(): void` — рекурсивно удаляет всю директорию кэша.

## Операции

### Поток синхронизации кэша

`PropertiesCache` работает через сложный внутренний жизненный цикл для обеспечения согласованности данных:
1. **Запрос (`get`)**: При запросе данных класс сначала проверяет наличие физического файла кэша.
2. **Системная валидация**: Он обращается к внутреннему реестру `system`, чтобы сравнить временную метку создания кэша с временем изменения всех зарегистрированных файлов зависимостей.
3. **Регенерация**: Если файл отсутствует или устарел:
    - Класс помещает текущее имя кэша `name` во внутренний стек `listenerName`.
    - Любое последующее чтение файла через `PropertiesCache.read()` во время выполнения callback автоматически регистрируется как зависимость для этой конкретной записи кэша.
    - Результат callback записывается на диск.
4. **Завершение**: После завершения callback обновляется `system.json` с новой временной меткой и списком зависимостей, гарантируя, что следующий запрос останется валидным, пока не изменится исходный файл.

