cs-element/docs/10-persistence-and-adapters.md

Advanced reactive data management library with state machines, blueprints, persistence, compression, networking, and multithreading support

# Персистентность и адаптеры

CSElement предоставляет мощную систему персистентности с различными адаптерами для разных сред выполнения.

## Обзор адаптеров

### 🔄 MemoryStorageAdapter (Универсальный)
- ✅ **Node.js**: Полная поддержка
- ✅ **Браузер**: Полная поддержка  
- ✅ **SSR**: Полная поддержка
- 📦 **Импорт**: `import { MemoryStorageAdapter } from 'cs-element'`

### 🗄️ IndexedDBAdapter (Только браузер)
- ❌ **Node.js**: Не поддерживается (нет IndexedDB API)
- ✅ **Браузер**: Полная поддержка
- ❌ **SSR**: Не поддерживается (IndexedDB недоступен на сервере)
- 📦 **Импорт**: `import { IndexedDBAdapter } from 'cs-element/browser'` (только в браузере)

### 💾 LocalForageAdapter (Только браузер)
- ❌ **Node.js**: Не поддерживается (нет localStorage/IndexedDB/WebSQL)
- ✅ **Браузер**: Полная поддержка
- ❌ **SSR**: Не поддерживается (браузерные API недоступны на сервере)
- 📦 **Импорт**: `import { LocalForageAdapter } from 'cs-element/browser'` (только в браузере)

## Быстрый старт

### MemoryStorageAdapter (Рекомендуется для начала)

```typescript
import { CSElement, MemoryStorageAdapter, PersistenceManagerImpl } from 'cs-element';

// Создаем адаптер памяти
const memoryAdapter = new MemoryStorageAdapter({ name: 'my-app-storage' });

// Инициализируем
await memoryAdapter.initialize();

// Создаем элемент
const element = new CSElement({ data: { name: 'Test', value: 42 } });

// Сохраняем
const saveResult = await memoryAdapter.save(element.id, element.serialize());
if (saveResult.success) {
  console.log('Элемент сохранен:', saveResult.metadata);
}

// Загружаем
const loadResult = await memoryAdapter.load(element.id);
if (loadResult.success) {
  console.log('Элемент загружен:', loadResult.data);
}
```

### IndexedDBAdapter (Браузер)

```typescript
// Только в браузере!
import { CSElement } from 'cs-element';
import { IndexedDBAdapter } from 'cs-element/browser';

const indexedDBAdapter = new IndexedDBAdapter('my-database');
await indexedDBAdapter.initialize();

const elements = [
  new CSElement({ data: { name: 'Element 1' } }),
  new CSElement({ data: { name: 'Element 2' } })
];

// Сохраняем массив элементов
await indexedDBAdapter.save(elements);

// Загружаем все элементы
const loadedElements = await indexedDBAdapter.load();
console.log('Загружено элементов:', loadedElements.length);

// Загружаем по ID
const element = await indexedDBAdapter.loadById('element-id');
```

### LocalForageAdapter (Браузер)

```typescript
// Только в браузере!
import { CSElement } from 'cs-element';
import { LocalForageAdapter } from 'cs-element/browser';

const localForageAdapter = new LocalForageAdapter({
  name: 'my-app',
  storeName: 'elements',
  driver: 'INDEXEDDB', // или 'WEBSQL', 'LOCALSTORAGE'
  description: 'CSElement storage'
});

await localForageAdapter.initialize();

const elements = [
  new CSElement({ data: { name: 'Element 1' } }),
  new CSElement({ data: { name: 'Element 2' } })
];

// Сохраняем
await localForageAdapter.save(elements);

// Загружаем
const loadedElements = await localForageAdapter.load();
```

## Конфигурация адаптеров

### MemoryStorageAdapter

```typescript
interface StorageConfig {
  name: string;                    // Имя адаптера
  maxSize?: number;               // Максимальный размер (байты)
  ttl?: number;                   // Time to live (мс)
  compression?: boolean;          // Сжатие данных
  encryption?: boolean;           // Шифрование
}

const config: StorageConfig = {
  name: 'my-storage',
  maxSize: 1024 * 1024 * 10,     // 10MB
  ttl: 1000 * 60 * 60,           // 1 час
  compression: true,
  encryption: false
};

const adapter = new MemoryStorageAdapter(config);
```

### IndexedDBAdapter

```typescript
// Простая конфигурация
const adapter = new IndexedDBAdapter('my-database');

// Расширенные возможности
await adapter.query({
  name: 'specific-name',
  index: 1,
  limit: 10,
  offset: 0
});

// Метаданные
await adapter.updateMetadata('version', '1.0.0');
const version = await adapter.getMetadata('version');
```

### LocalForageAdapter

```typescript
const config: LocalForageConfig = {
  name: 'my-app',
  storeName: 'elements',
  driver: 'INDEXEDDB',           // Приоритетный драйвер
  description: 'App storage',
  version: 1.0
};

const adapter = new LocalForageAdapter(config);

// Проверка поддержки драйвера
if (LocalForageAdapter.isDriverSupported('INDEXEDDB')) {
  console.log('IndexedDB поддерживается');
}

// Получение поддерживаемых драйверов
const drivers = LocalForageAdapter.getSupportedDrivers();
console.log('Поддерживаемые драйверы:', drivers);
```

## Работа с PersistenceManager

```typescript
import { PersistenceManagerImpl, MemoryStorageAdapter } from 'cs-element';

// Создаем менеджер персистентности
const persistenceManager = new PersistenceManagerImpl();

// Регистрируем адаптер
const memoryAdapter = new MemoryStorageAdapter({ name: 'main-storage' });
await memoryAdapter.initialize();

// Используем менеджер для управления адаптерами
// (конкретная реализация зависит от интерфейса PersistenceManager)
```

## Обработка ошибок

```typescript
try {
  const result = await adapter.save(element.id, element.serialize());
  
  if (!result.success) {
    console.error('Ошибка сохранения:', result.error);
    return;
  }
  
  console.log('Успешно сохранено:', result.metadata);
} catch (error) {
  console.error('Критическая ошибка:', error);
}
```

## Миграция между адаптерами

```typescript
// Из памяти в IndexedDB (браузер)
async function migrateToIndexedDB(memoryAdapter: MemoryStorageAdapter) {
  const indexedDBAdapter = new IndexedDBAdapter('migrated-db');
  await indexedDBAdapter.initialize();
  
  // Получаем все ID из памяти
  const ids = await memoryAdapter.listIds();
  
  // Переносим данные
  for (const id of ids) {
    const loadResult = await memoryAdapter.load(id);
    if (loadResult.success) {
      // Преобразуем данные для IndexedDB
      const element = /* создаем CSElement из loadResult.data */;
      await indexedDBAdapter.save([element]);
    }
  }
}
```

## Рекомендации по выбору адаптера

### 🎯 Для разработки и тестирования
- **MemoryStorageAdapter**: Быстрый, простой, работает везде

### 🌐 Для веб-приложений
- **IndexedDBAdapter**: Большие объемы данных, сложные запросы
- **LocalForageAdapter**: Простота использования, автоматический выбор драйвера

### 🖥️ Для Node.js приложений
- **MemoryStorageAdapter**: Единственный универсальный вариант
- Кастомные адаптеры для файловой системы или баз данных

### 🔄 Для SSR (Next.js, Nuxt.js)
- **MemoryStorageAdapter**: Единственный безопасный вариант
- Избегайте браузерных адаптеров в серверном коде

## Производительность

| Адаптер | Скорость | Объем данных | Персистентность |
|---------|----------|--------------|-----------------|
| MemoryStorageAdapter | ⚡ Очень высокая | 📊 Ограничена RAM | ❌ Сессия |
| IndexedDBAdapter | 🚀 Высокая | 📈 Очень большие | ✅ Постоянная |
| LocalForageAdapter | 🏃 Средняя | 📊 Большие | ✅ Постоянная |

## Отладка

```typescript
// Включаем логирование для адаптеров
const adapter = new MemoryStorageAdapter({ name: 'debug-storage' });

// Слушаем события
adapter.on('initialized', (data) => console.log('Инициализирован:', data));
adapter.on('saved', (data) => console.log('Сохранен:', data));
adapter.on('loaded', (data) => console.log('Загружен:', data));
adapter.on('save-error', (data) => console.error('Ошибка сохранения:', data));
adapter.on('load-error', (data) => console.error('Ошибка загрузки:', data));
```

## Заключение

Система персистентности CSElement предоставляет гибкие возможности для работы с данными в разных средах. Выбирайте адаптер в зависимости от ваших потребностей:

- **Универсальность**: MemoryStorageAdapter
- **Браузерные приложения**: IndexedDBAdapter или LocalForageAdapter  
- **SSR совместимость**: Только MemoryStorageAdapter

Помните о совместимости со средой выполнения при выборе адаптера!