SmartStore

Продвинутая TypeScript-библиотека для замены localStorage с поддержкой типизации, шифрования и синхронизации.

Преимущества

• TypeScript-типизация - Полная поддержка типов для безопасной работы с данными
• Автоматическая сериализация - Сохраняйте объекты, массивы и любые JSON-совместимые данные
• TTL (Time To Live) - Автоматическое истечение данных через заданное время
• Шифрование - Защита данных на стороне клиента с помощью AES
• Синхронизация - Мгновенное обновление данных между вкладками через BroadcastChannel
• События - Отслеживание изменений в хранилище
• Панель разработчика - Встроенный инструмент для отладки и мониторинга
• Очистка - Автоматическое удаление устаревших данных

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

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

import { SmartStore } from "smartstore";

// Создание экземпляра
const store = new SmartStore({
  prefix: "app",         // Префикс для ключей
  encryption: true,      // Включить шифрование
  encryptionKey: "key",  // Ключ шифрования
  defaultTTL: 3600000,   // TTL по умолчанию (1 час)
  enableBroadcast: true, // Синхронизация между вкладками
  enableDebug: false,    // Режим отладки
});

// Сохранение данных
await store.set("user", { name: "Иван", age: 25 });
await store.set("token", "abc123", 3600000); // С TTL 1 час

// Получение данных
const user = await store.get<User>("user");
const token = await store.get<string>("token");

// Проверка существования
if (await store.has("user")) {
  console.log("Пользователь найден");
}

// Удаление
await store.remove("token");

// Получение всех ключей
const keys = await store.keys();

// Очистка хранилища
await store.clear();

API Reference

Конфигурация

interface SmartStoreConfig {
  prefix?: string;           // Префикс для ключей (по умолчанию 'smartstore')
  encryption?: boolean;      // Включить шифрование (по умолчанию false)
  encryptionKey?: string;    // Ключ шифрования
  defaultTTL?: number;       // TTL по умолчанию в миллисекундах (0 = без TTL)
  enableBroadcast?: boolean; // Синхронизация между вкладками (по умолчанию true)
  enableDebug?: boolean;     // Режим отладки (по умолчанию false)
}

Основные методы

set<T>(key: string, value: T, ttl?: number): Promise<void>

Сохраняет значение с опциональным TTL.

await store.set("data", { key: "value" });
await store.set("temp", "временные данные", 60000); // TTL 1 минута

get<T>(key: string): Promise<T | null>

Получает значение по ключу с типизацией.

const user = await store.get<User>("user");
const count = await store.get<number>("count");

remove(key: string): Promise<void>

Удаляет значение по ключу.

await store.remove("outdated-data");

clear(): Promise<void>

Очищает все данные хранилища.

await store.clear();

has(key: string): Promise<boolean>

Проверяет существование ключа.

if (await store.has("user-settings")) {
  // Настройки существуют
}

keys(): Promise<string[]>

Возвращает все ключи в хранилище.

const allKeys = await store.keys();
console.log("Сохранены:", allKeys);

size(): Promise<number>

Возвращает количество элементов в хранилище.

const count = await store.size();

Дополнительные методы

getInfo(key: string): Promise<StoredItem | null>

Получает метаинформацию о сохраненном элементе.

const info = await store.getInfo("user");
if (info) {
  console.log("Создано:", new Date(info.timestamp));
  console.log("TTL:", info.ttl);
  console.log("Тип:", info.type);
}

cleanup(): Promise<number>

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

const cleaned = await store.cleanup();
console.log(`Очищено ${cleaned} записей`);

События

SmartStore поддерживает систему событий для отслеживания изменений:

// Изменения конкретного ключа
store.on("user", (event) => {
  console.log(`Пользователь ${event.action}:`, event.newValue);
});

// Слушать все изменения
store.on("*", (event) => {
  console.log(`Событие ${event.action} для ${event.key}`);
});

// Отписаться от событий
store.off("user", handler);

Типы событий

interface StorageEvent<T = any> {
  key: string;                        // Ключ который изменился
  oldValue: T | null;                 // Предыдущее значение
  newValue: T | null;                 // Новое значение
  action: "set" | "remove" | "clear"; // Тип действия
  timestamp: number;                  // Время события
}

Шифрование

SmartStore поддерживает AES-шифрование данных:

const store = new SmartStore({
  encryption: true,
  encryptionKey: "secret-key",
});

// Данные автоматически шифруются при сохранении
await store.set("sensitive-data", { secret: "важная информация" });

// И расшифровываются при получении
const data = await store.get("sensitive-data");

Синхронизация между вкладками

Автоматическая синхронизация через BroadcastChannel:

// Во вкладке 1
await store.set("shared-data", "новое значение");

// Во вкладке 2 (автоматически получит обновление)
store.on("shared-data", (event) => {
  console.log("Получено обновление:", event.newValue);
});

Панель разработчика

SmartStore включает встроенную панель разработчика для отладки:

import { DevPanel } from "smartstore";

const devPanel = new DevPanel(store);

// Открыть/закрыть панель: Ctrl + Shift + S

Панель разработчика позволяет:

• Просматривать все сохраненные данные
• Мониторить изменения в реальном времени
• Удалять отдельные записи
• Очищать устаревшие данные
• Просматривать метаинформацию (TTL, время создания, размер)

Тестирование

# Запуск тестов
bun test

# Сборка
bun run build

# Запуск демо
bun run demo

Примеры использования

Кэширование API данных

async function fetchUserData(userId: number) {
  const cacheKey = `user:${userId}`;

  // Проверяем кэш
  let user = await store.get<User>(cacheKey);

  if (!user) {
    // Загружаем с сервера
    user = await api.getUser(userId);

    // Кэшируем на 5 минут
    await store.set(cacheKey, user, 5 * 60 * 1000);
  }

  return user;
}

Сохранение настроек приложения

interface AppSettings {
  theme: "light" | "dark";
  language: string;
  notifications: boolean;
}

class SettingsManager {
  private store = new SmartStore({ prefix: "app-settings" });

  async getSettings(): Promise<AppSettings> {
    return (
      (await this.store.get<AppSettings>("settings")) || {
        theme: "light",
        language: "ru",
        notifications: true,
      }
    );
  }

  async updateSettings(settings: Partial<AppSettings>): Promise<void> {
    const current = await this.getSettings();
    await this.store.set("settings", { ...current, ...settings });
  }
}

Временные токены аутентификации

class AuthManager {
  private store = new SmartStore({
    prefix: "auth",
    encryption: true,
    encryptionKey: "auth-secret-key",
  });

  async setToken(token: string, expiresIn: number): Promise<void> {
    await this.store.set("token", token, expiresIn);
  }

  async getToken(): Promise<string | null> {
    return await this.store.get<string>("token");
  }

  async isAuthenticated(): Promise<boolean> {
    return await this.store.has("token");
  }
}

Преимущества над обычным localStorage

Функция	localStorage	SmartStore
Типизация	❌	✅
Сложные объекты	❌	✅
TTL	❌	✅
Шифрование	❌	✅
Синхронизация	❌	✅
События	❌	✅
Отладка	❌	✅
Автоочистка	❌	✅

Поддержка браузеров

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+

Для полной функциональности требуется поддержка:

• localStorage
• BroadcastChannel (для синхронизации)
• Crypto API (для шифрования)