vue-storage-kit — реактивное хранилище для Vue 3 с шифрованием, миграциями и синхронизацией вкладок

npm install vue-storage-kit

import { useStorage } from 'vue-storage-kit'

const { value: theme } = useStorage('theme', { defaultValue: 'light' })

theme.value = 'dark'  // localStorage.setItem('theme', ...) прямо здесь, синхронно

const { value, isReady, error, expiry, remove, refresh } = useStorage<UserProfile>('profile', {
  defaultValue: { name: '', role: 'guest' },
  target: 'local',           // 'local' | 'session' | 'memory'
  ttl: 30 * 60 * 1000,       // время жизни — 30 минут
  version: 3,                 // версия схемы данных
  migrations: [...],          // цепочка up/down миграций
  encrypt: { password: 'secret' },
  sync: true,                 // BroadcastChannel синхронизация вкладок
  onError: (err) => console.error(err),
  onExpire: (key) => router.push('/login'),
  onMigrate: (from, to) => console.log(`Migrated ${from} → ${to}`),
})

<template>
  <SkeletonCard v-if="!isReady" />
  <ProfileCard v-else :profile="value" />
</template>

import { useLocalStorage, useSessionStorage } from 'vue-storage-kit'

const { value: settings } = useLocalStorage('settings', { theme: 'light', lang: 'en' })
const { value: draft }    = useSessionStorage('draft', '')

import type { Serializer } from 'vue-storage-kit'

// Пример: кастомный сериализатор на основе msgpack
const msgpackSerializer: Serializer<unknown> = {
  serialize:   (v) => Buffer.from(encode(v)).toString('base64'),
  deserialize: (s) => decode(Buffer.from(s, 'base64')),
}

const { value } = useStorage('binary-data', {
  defaultValue: null,
  serializer: msgpackSerializer,
})

interface SettingsV3 {
  theme: 'light' | 'dark' | 'system'
  locale: string
}

const { value: settings } = useStorage<SettingsV3>('settings', {
  defaultValue: { theme: 'system', locale: 'en' },
  version: 3,
  migrations: [
    {
      version: 2,
      // v1 хранил { darkMode: boolean } — конвертируем в строковую тему
      up:   (d: any) => ({ ...d, theme: d.darkMode ? 'dark' : 'light' }),
      down: (d: any) => { const { theme, ...rest } = d; return { ...rest, darkMode: theme === 'dark' } },
    },
    {
      version: 3,
      // v2 не имел локали — берём из старого поля lang или ставим дефолт
      up:   (d: any) => ({ ...d, locale: d.lang ?? 'en' }),
      down: (d: any) => { const { locale, ...rest } = d; return { ...rest, lang: locale } },
    },
  ],
  onMigrate: (from, to) => console.log(`Migrated settings ${from} → ${to}`),
})

const { value: otp, expiry, remove } = useStorage('otp-code', {
  defaultValue: '',
  ttl: 5 * 60 * 1000,   // 5 минут
  onExpire: () => {
    toast.warn('Код истёк, запросите новый')
    router.push('/request-otp')
  },
})

// Реактивный обратный отсчёт — expiry обновляется при каждом новом OTP
const timeLeft = computed(() =>
  expiry.value ? Math.max(0, expiry.value.getTime() - Date.now()) : null
)

// Форматируем для отображения: "4:32"
const timeLeftFormatted = computed(() => {
  if (!timeLeft.value) return null
  const sec = Math.floor(timeLeft.value / 1000)
  return `${Math.floor(sec / 60)}:${String(sec % 60).padStart(2, '0')}`
})

import { TTLManager, StorageAdapterFactory } from 'vue-storage-kit'

// Запускаем при старте — удаляет все ключи с префиксом 'myapp:' у которых exp прошёл
const adapter = StorageAdapterFactory.get('local')
TTLManager.cleanExpired(adapter, 'myapp:')

// Посмотреть когда истекает конкретный ключ (без чтения данных)
const exp = TTLManager.getExpiry(adapter, 'myapp:otp-code')
if (exp) console.log(`OTP expires at ${exp.toLocaleTimeString()}`)

const { value: apiKey } = useStorage('api-key', {
  defaultValue: '',
  encrypt: { password: 'user-passphrase', iterations: 100_000 },
})

apiKey.value = 'sk-abc123'
// В localStorage записано что-то вроде:
// "kL9mN2pQr8...очень длинная base64-строка..."
// Прочитать без пароля — невозможно

// Генерируем ключ один раз при входе пользователя
const sessionKey = await crypto.subtle.generateKey(
  { name: 'AES-GCM', length: 256 },
  false,    // не извлекаемый — нельзя утащить через JS
  ['encrypt', 'decrypt'],
)

const { value: sensitiveData } = useStorage('vault', {
  defaultValue: {},
  encrypt: { key: sessionKey },
})

import { encrypt, decrypt } from 'vue-storage-kit/crypto'

// Можно использовать и вне useStorage — для произвольных данных
const ciphertext = await encrypt('sensitive data', { password: 'pass' })
const plaintext  = await decrypt(ciphertext, { password: 'pass' })

const { value: cart } = useStorage('cart', {
  defaultValue: [] as CartItem[],
  sync: true,
})

// Обе вкладки показывают одинаковую корзину.
// Изменение в одной вкладке через BroadcastChannel появляется в другой мгновенно.

const { value: sharedState } = useStorage('shared-state', {
  defaultValue: { count: 0 },
  sync: {
    channel: 'app-sync',
    leader: true,    // navigator.locks: одна вкладка держит named lock
    debounce: 100,   // объединяем частые изменения, не рассылаем каждый tick
  },
})

import { useBroadcastChannel } from 'vue-storage-kit'

interface Notification { type: 'info' | 'warn'; message: string; ts: number }

const { isSupported, post, messages, lastMessage, close } =
  useBroadcastChannel<Notification>('app-notifications')

// Отправить уведомление во все вкладки
function broadcastAlert(message: string) {
  if (isSupported) {
    post({ type: 'warn', message, ts: Date.now() })
  }
}

// Реагировать на входящие
watch(lastMessage, (notification) => {
  if (notification) showToast(notification.message)
})

// messages — Ref<Notification[]>, история всех полученных сообщений

import { useIndexedDB } from 'vue-storage-kit'

interface FileRecord { id: string; name: string; size: number; content: ArrayBuffer }

// Параметры: имя базы, имя стора, обработчик ошибок (опционально), опции
const idb = useIndexedDB<FileRecord>('files-db', 'records', (err) => {
  console.error('IDB error:', err)
})

// Стандартный CRUD
await idb.set('doc-1', { id: 'doc-1', name: 'report.pdf', size: 204800, content: buffer })
const record = await idb.get('doc-1')       // FileRecord | null
const allIds = await idb.keys()             // IDBValidKey[]
const all    = await idb.getAll()           // FileRecord[]
console.log(await idb.count())              // 1
await idb.delete('doc-1')
await idb.clear()                           // удалить всё в сторе

// Сырая транзакция для нестандартных операций
await idb.transaction((store) => store.put({ id: 'doc-2', ... }, 'doc-2'))

import { useIDBRef } from 'vue-storage-kit'

// Реактивный черновик поста
const { value: draft, isReady, error } = useIDBRef('editor-db', 'drafts', 'post-42', '')

// isReady === false пока идёт первое асинхронное чтение из IDB
// Как только isReady === true — draft.value содержит сохранённый черновик

draft.value = 'Начало поста...'  // пишет в IDB через watch автоматически

interface Contact {
  id: number
  email: string
  department: string
  lastName: string
}

const idb = useIndexedDB<Contact>('crm-db', 'contacts', undefined, {
  version: 2,  // увеличиваем версию базы при добавлении новых индексов
  indexes: [
    { name: 'by-email',      keyPath: 'email',      unique: true  },
    { name: 'by-department', keyPath: 'department', unique: false },
    { name: 'by-last-name',  keyPath: 'lastName',   unique: false },
  ],
})

await idb.set(1, { id: 1, email: 'alice@co.com', department: 'engineering', lastName: 'Smith' })
await idb.set(2, { id: 2, email: 'bob@co.com',   department: 'engineering', lastName: 'Jones' })
await idb.set(3, { id: 3, email: 'carol@co.com', department: 'design',      lastName: 'White' })

// Поиск по индексу — быстро, даже на тысячах записей
const alice = await idb.getByIndex('by-email', 'alice@co.com')             // одна запись
const team  = await idb.getAllByIndex('by-department', 'engineering')       // [alice, bob]

import { useCookie } from 'vue-storage-kit'

// Session cookie — удаляется когда закрывается браузер
const consent = useCookie('gdpr-consent', { defaultValue: false })
consent.value = true
// document.cookie теперь: "gdpr-consent=true; path=/"

// Persistent cookie — явно задаём срок
const locale = useCookie('locale', {
  defaultValue: 'ru',
  expires: 30,        // 30 дней, или можно передать Date
  sameSite: 'lax',    // безопасно для большинства случаев
})

// Cookie с полным объектом — JSON-сериализация прозрачна
interface UserPrefs { theme: string; lang: string; lastLogin: Date }
const prefs = useCookie<UserPrefs>('user-prefs', {
  defaultValue: { theme: 'dark', lang: 'ru', lastLogin: new Date() },
  secure: true,
  sameSite: 'strict',
  expires: 365,
})

prefs.value = { ...prefs.value, theme: 'light' }
// В cookie: URL-encoded JSON с корректной сериализацией Date

<script setup lang="ts">
// Этот код работает одинаково при SSR и CSR
const authToken = useCookie('auth-token', {
  defaultValue: '',
  secure: true,
  httpOnly: true,      // на сервере уходит в Set-Cookie заголовок
  sameSite: 'strict',
  expires: 7,          // 7 дней
})
</script>

import { useStorageList } from 'vue-storage-kit'

interface Task {
  id: string
  title: string
  done: boolean
  priority: 'low' | 'medium' | 'high'
  createdAt: Date
}

const { items, add, update, remove, find, findAll, set, clear } = useStorageList<Task>('tasks', {
  keyField: 'id',   // по какому полю идентифицировать элементы (default: 'id')
})

// Добавить
add({
  id: crypto.randomUUID(),
  title: 'Написать тесты',
  done: false,
  priority: 'high',
  createdAt: new Date(),
})

// Обновить по id (патч — только изменённые поля)
update('some-uuid', { done: true })

// Удалить по id
remove('another-uuid')

// Найти один элемент — возвращает ComputedRef, реагирует на изменения
const task = find('some-uuid')      // ComputedRef<Task | undefined>

// Найти несколько — тоже ComputedRef
const urgent = findAll((t) => t.priority === 'high' && !t.done)

// Полностью заменить коллекцию
set(importedTasks)

// Очистить всё (удаляет ключ из storage)
clear()

interface Bookmark { slug: string; url: string; title: string }

const { items: bookmarks, add, remove } = useStorageList<Bookmark>('bookmarks', {
  keyField: 'slug',   // идентифицируем по slug, не по id
})

add({ slug: 'vue-docs', url: 'https://vuejs.org', title: 'Vue.js Docs' })
remove('vue-docs')  // удаляет запись где slug === 'vue-docs'

npm install pinia

// main.ts
import { createPinia } from 'pinia'
import { createPiniaPersist } from 'vue-storage-kit/pinia'

const pinia = createPinia()

// Один вызов — персистирует ВСЕ сторы приложения
pinia.use(createPiniaPersist({ target: 'local' }))

createApp(App).use(pinia).mount('#app')

const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0, username: 'User', tempFlag: false }),
  actions: {
    inc()   { this.count++ },
    dec()   { this.count-- },
    reset() { this.count = 0 },
  },
})

// Перезагружаем страницу — count и username восстанавливаются
// Ключ в localStorage: "counter" → { count: 5, username: 'Alice', tempFlag: false }

pinia.use(createPiniaPersist({
  target: 'local',

  // Кастомное имя ключа (по умолчанию — storeId)
  key: (storeId) => `persist:v2:${storeId}`,

  // Сохранять только нужные поля (whitelist)
  pick: ['count', 'username'],

  // Или исключить ненужные (blacklist)
  // omit: ['tempFlag', 'internalState'],

  // Колбеки жизненного цикла восстановления
  beforeRestore: (ctx) => {
    console.log(`Restoring store "${ctx.store.$id}"`)
  },
  afterRestore: (ctx) => {
    // Например, помечаем стор как гидрированный
    if ('hydrated' in ctx.store) ctx.store.$patch({ hydrated: true })
  },
}))

import { compress, decompress, isCompressed } from 'vue-storage-kit/compress'

const original   = JSON.stringify(largeCatalog)   // ~800 КБ JSON
const compressed = await compress(original, { algorithm: 'gzip' })
// "vsk:gzip:H4sIAAAAAAAA..."  — magic prefix + base64

// Степень сжатия зависит от данных
// JSON с повторяющимися ключами сжимается на 60–80%
// Случайные строки — практически не сжимаются

isCompressed(compressed)                   // true
isCompressed('обычная строка')             // false

const restored = await decompress(compressed)
// decompress сам читает алгоритм из префикса, параметры не нужны

import { CompressAdapter } from 'vue-storage-kit/compress'
import { LocalStorageAdapter } from 'vue-storage-kit'

// Оборачиваем localStorage-адаптер в сжимающую обёртку
const base    = new LocalStorageAdapter()
const adapter = new CompressAdapter(base, { algorithm: 'gzip' })

// Все данные автоматически сжимаются при записи и распаковываются при чтении
await adapter.setCompressed('catalog', JSON.stringify(bigCatalog))
const catalog = JSON.parse(await adapter.getDecompressed('catalog') ?? '{}')

// Можно посмотреть что лежит в сыром виде
const rawValue = base.getItem('catalog')  // "vsk:gzip:H4sI..." — сжатые данные

import { getStorageQuota } from 'vue-storage-kit'

const { used, total, percentage } = await getStorageQuota()
// { used: 1048576, total: 5242880, percentage: 20 }
// used и total — в байтах

if (percentage > 80) {
  showWarning(`Хранилище заполнено на ${percentage}%. Рекомендуем очистить кеш.`)
}

import { exportStorage, importStorage } from 'vue-storage-kit'

// Снапшот всех ключей с префиксом 'myapp:' из localStorage
// Возвращает простой объект { ключ: сериализованное_значение }
const snapshot = exportStorage('myapp:', 'local')
const json = JSON.stringify(snapshot, null, 2)

// Сохранить в файл
const blob = new Blob([json], { type: 'application/json' })
const url  = URL.createObjectURL(blob)
// <a :href="url" download="my-settings-backup.json">Скачать настройки</a>

// Восстановить из файла
async function restore(file: File) {
  const text     = await file.text()
  const snapshot = JSON.parse(text)
  importStorage(snapshot, 'local')   // пишет все ключи обратно в localStorage
  location.reload()                   // перезагружаем чтобы composables подхватили новые данные
}

import { clearStorage } from 'vue-storage-kit'

// Удалить только данные приложения, не трогая ключи сторонних скриптов
clearStorage('myapp:', 'local')

// Или очистить конкретный модуль
clearStorage('myapp:cache:', 'local')   // только кеш
clearStorage('myapp:prefs:', 'local')   // только настройки

import { createApp } from 'vue'
import { VueStoragePlugin } from 'vue-storage-kit'

const app = createApp(App)

app.use(VueStoragePlugin, {
  // Все ключи автоматически получают этот префикс.
  // useStorage('profile', ...) реально пишет в 'myapp:profile'
  prefix: 'myapp:',

  defaultTarget: 'local',

  // Глобальное шифрование — все ключи будут шифроваться если не переопределено
  defaultEncrypt: { password: import.meta.env.VITE_STORAGE_SECRET },

  // Один обработчик ошибок на всё приложение
  onError: (err) => {
    if (err.type === 'quota-exceeded') {
      toast.error('Браузерное хранилище заполнено. Зайдите в настройки и очистите кеш.')
      analytics.track('storage_quota_exceeded', { key: err.key })
    }
    if (err.type === 'parse-error') {
      // Повреждённые данные — логируем, но не падаем
      console.warn(`[storage] Parse error for key "${err.key}", resetting to default`)
    }
  },
})

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['vue-storage-kit/nuxt'],

  storageKit: {
    prefix:      'myapp_',
    autoImports: true,    // по умолчанию true
  },
})

interface CartItem { id: string; sku: string; title: string; qty: number; price: number }

const { value: cart, expiry } = useStorage<CartItem[]>('cart', {
  defaultValue: [],
  ttl: 24 * 60 * 60 * 1000,  // 24 часа — потом корзина автоматически очищается
  sync: true,                  // мгновенная синхронизация между всеми открытыми вкладками
  onExpire: () => {
    // Пользователь пришёл через сутки — предупреждаем
    showModal({
      title: 'Корзина устарела',
      message: 'Товары в вашей корзине больше не зарезервированы. Проверьте наличие.',
    })
  },
})

function addToCart(product: Product) {
  const existing = cart.value.find((i) => i.sku === product.sku)
  if (existing) {
    // Увеличиваем количество если уже в корзине
    cart.value = cart.value.map((i) =>
      i.sku === product.sku ? { ...i, qty: i.qty + 1 } : i
    )
  } else {
    cart.value = [
      ...cart.value,
      { id: crypto.randomUUID(), sku: product.sku, title: product.title, qty: 1, price: product.price },
    ]
  }
}

function updateQty(sku: string, qty: number) {
  if (qty <= 0) {
    removeFromCart(sku)
    return
  }
  cart.value = cart.value.map((i) => i.sku === sku ? { ...i, qty } : i)
}

function removeFromCart(sku: string) {
  cart.value = cart.value.filter((i) => i.sku !== sku)
}

const itemCount = computed(() => cart.value.reduce((n, i) => n + i.qty, 0))
const total     = computed(() => cart.value.reduce((sum, i) => sum + i.price * i.qty, 0))

<template>
  <div class="cart">
    <p v-if="expiry" class="cart__expires">
      Корзина действует до {{ expiry.toLocaleString('ru', { day: 'numeric', month: 'short', hour: '2-digit', minute: '2-digit' }) }}
    </p>

    <p v-if="cart.length === 0" class="cart__empty">Корзина пуста</p>

    <CartItemRow
      v-for="item in cart"
      :key="item.sku"
      :item="item"
      @change-qty="updateQty(item.sku, $event)"
      @remove="removeFromCart(item.sku)"
    />

    <div class="cart__footer">
      <span>{{ itemCount }} товара на сумму</span>
      <strong>{{ total.toLocaleString('ru') }} ₽</strong>
    </div>
  </div>
</template>

interface NoteMeta { id: string; title: string; updatedAt: Date; size: number }

// Индекс заметок — быстрый реактивный список в localStorage
const { items: notes, add: addMeta, update: updateMeta, remove: removeMeta, find } =
  useStorageList<NoteMeta>('notes-index', { keyField: 'id' })

// IDB для контента — без лимита объёма
const idb = useIndexedDB<string>('notes-db', 'content')

// Пароль пользователя — в памяти сессии, не хранится в storage
const sessionPassword = ref('')   // вводится в диалоге при открытии приложения
const isUnlocked      = computed(() => sessionPassword.value.length > 0)

// Активная заметка
const activeNoteId = ref<string | null>(null)
const activeContent = ref('')
const isSaving      = ref(false)

async function openNote(id: string) {
  activeNoteId.value = id
  activeContent.value = ''

  const raw = await idb.get(id)
  if (!raw) return

  // Расшифровываем — если пароль неверный, decrypt выбросит ошибку
  try {
    const { decrypt } = await import('vue-storage-kit/crypto')
    activeContent.value = await decrypt(raw, { password: sessionPassword.value })
  } catch {
    toast.error('Неверный пароль')
    sessionPassword.value = ''
  }
}

async function saveNote() {
  if (!activeNoteId.value || !isUnlocked.value) return
  isSaving.value = true

  try {
    const { encrypt } = await import('vue-storage-kit/crypto')
    const encrypted = await encrypt(activeContent.value, { password: sessionPassword.value })

    await idb.set(activeNoteId.value, encrypted)

    // Обновляем метаданные в индексе
    updateMeta(activeNoteId.value, {
      updatedAt: new Date(),
      size: activeContent.value.length,
    })
  } finally {
    isSaving.value = false
  }
}

async function createNote(title: string) {
  const id = crypto.randomUUID()
  addMeta({ id, title, updatedAt: new Date(), size: 0 })
  await openNote(id)
}

async function deleteNote(id: string) {
  removeMeta(id)
  await idb.delete(id)
  if (activeNoteId.value === id) {
    activeNoteId.value = null
    activeContent.value = ''
  }
}

// Автосохранение с debounce
const debouncedSave = useDebounceFn(saveNote, 1000)
watch(activeContent, debouncedSave)

interface DashboardSettings {
  theme: 'light' | 'dark' | 'system'
  locale: string
  sidebarCollapsed: boolean
  pinnedWidgets: string[]
  dataRefreshInterval: number   // миллисекунды
}

const { value: settings } = useStorage<DashboardSettings>('dashboard-settings', {
  defaultValue: {
    theme: 'system',
    locale: navigator.language.slice(0, 2) || 'en',
    sidebarCollapsed: false,
    pinnedWidgets: [],
    dataRefreshInterval: 30_000,
  },
  version: 4,
  migrations: [
    {
      version: 2,
      // v1 → v2: boolean-тема заменена на строку, добавлен sidebarCollapsed
      up: (d: any) => ({
        ...d,
        theme: d.darkMode ? 'dark' : 'light',
        sidebarCollapsed: false,
      }),
      down: (d: any) => {
        const { theme, sidebarCollapsed, ...rest } = d
        return { ...rest, darkMode: theme === 'dark' }
      },
    },
    {
      version: 3,
      // v2 → v3: добавили locale и pinnedWidgets, locale берём из старого поля lang
      up: (d: any) => ({
        ...d,
        locale: d.lang ?? navigator.language.slice(0, 2) ?? 'en',
        pinnedWidgets: d.pinnedWidgets ?? [],
      }),
      down: (d: any) => {
        const { locale, pinnedWidgets, ...rest } = d
        return { ...rest, lang: locale }
      },
    },
    {
      version: 4,
      // v3 → v4: refreshInterval (секунды) → dataRefreshInterval (миллисекунды)
      up: (d: any) => ({
        ...d,
        dataRefreshInterval: (d.refreshInterval ?? 30) * 1000,
      }),
      down: (d: any) => {
        const { dataRefreshInterval, ...rest } = d
        return { ...rest, refreshInterval: Math.round(dataRefreshInterval / 1000) }
      },
    },
  ],

  // Синхронизируем между вкладками — изменил тему в одной вкладке,
  // в остальных тема тоже переключилась
  sync: true,

  onMigrate: (from, to) => {
    // Отправляем в аналитику — можно отслеживать сколько пользователей ещё на старых версиях
    analytics.track('settings_migrated', { from, to, userId: currentUser.id })
  },

  onError: (err) => {
    if (err.type === 'migration-failed') {
      // Сброс к дефолту — лучше потерять настройки, чем сломать приложение
      console.warn(`[settings] Migration failed (${err.from} → ${err.to}), resetting defaults`)
      analytics.track('settings_migration_failed', { from: err.from, to: err.to })
    }
  },
})

// Экспорт данных пользователя — GDPR compliance или перенос на другое устройство
function exportMyData() {
  const snapshot = exportStorage('myapp:', 'local')
  const payload = {
    exportedAt: new Date().toISOString(),
    version: 4,
    data: snapshot,
  }
  const blob = new Blob([JSON.stringify(payload, null, 2)], { type: 'application/json' })
  const url  = URL.createObjectURL(blob)
  const a    = document.createElement('a')
  a.href     = url
  a.download = `my-data-${new Date().toISOString().slice(0, 10)}.json`
  a.click()
  URL.revokeObjectURL(url)
}

// Импорт на новом устройстве
async function importMyData(file: File) {
  const payload = JSON.parse(await file.text())

  if (payload.version !== 4) {
    toast.error('Файл от неподдерживаемой версии приложения')
    return
  }

  importStorage(payload.data, 'local')
  toast.success('Данные восстановлены. Перезагружаем приложение...')
  setTimeout(() => location.reload(), 1500)
}