VueCraft NPM

Тема

vue-storage-kit

vue-virtual-scroller-kit

Реактивные localStorage, sessionStorage, IndexedDB и cookies для Vue 3 (и React) — TTL, AES-GCM шифрование, HMAC-подписи, миграции схемы с функциями up/down, undo/redo и синхронизация между вкладками — построено на фреймворк-агностичном ядре, где Vue и React — тонкие обёртки над ним.

Возможности ​

  • useStorage — единое реактивное состояние поверх localStorage, sessionStorage, IndexedDB или in-memory хранилища; прямая замена useLocalStorage / useSessionStorage из vueuse. Доступно для Vue (Ref) и React (хук на основе useSyncExternalStore) — оба являются тонкими обёртками над одним и тем же фреймворк-агностичным движком
  • Миграции схемы — версионированные данные с цепочками миграций up / down; запускается автоматически при несовпадении версии, записывает мигрированное значение обратно
  • TTL — опциональное время жизни для каждого ключа; ленивая проверка истечения при каждом чтении, без таймеров; ручная зачистка cleanExpired() для очистки при старте
  • AES-GCM шифрование — Web Crypto API (crypto.subtle), ключ выводится из пароля через PBKDF2 либо передаётся как CryptoKey; salt + IV + шифротекст упакованы в одну base64-строку; выведенный ключ кэшируется в памяти сессии; reencrypt()/rotateEncryptedKey() для смены пароля без потери данных
  • HMAC-подписи — лёгкое обнаружение случайного повреждения (sign: { password }) для данных, которым не нужна секретность; не защита от пользователя, редактирующего хранилище своего же браузера (см. Обнаружение повреждения) — комбинируйте с encrypt для конфиденциальности + целостности
  • Undo / redo — history: n хранит последние n значений в памяти; undo() / redo() перемещаются по ним (не сохраняется между перезагрузками)
  • Debounce и throttle — debounce объединяет записи после паузы; throttle гарантирует запись не чаще, чем раз в n мс при непрерывных изменениях (слайдер, перетаскивание)
  • Устойчивые записи — при QuotaExceededError зачищает истёкшие по TTL записи этого адаптера и повторяет попытку один раз; опция evictOnQuota дополнительно вытесняет наименее недавно записанные другие ключи. Ошибки записи, не связанные с квотой, сообщаются через onError, а не выбрасываются изнутри реактивного колбэка
  • Синхронизация между вкладками — BroadcastChannel с запасным вариантом через событие storage; разрешение конфликтов по принципу «последняя запись побеждает» по временной метке; опциональные выборы лидера через navigator.locks
  • useIndexedDB — promise-based API ключ-значение плюс реактивный useIDBRef для одного ключа; либо просто передайте target: 'indexeddb' в useStorage() для того же конвейера TTL/миграций/шифрования/сжатия/синхронизации, что и у любой другой цели
  • useCookie — реактивные cookies с expires, sameSite, secure; клиентский вариант из корня пакета либо SSR-совместимый (на сервере через H3, поддерживает httpOnly) при автоимпорте внутри модуля Nuxt
  • Vue-плагин — глобальный префикс, цель/сериализатор/шифрование по умолчанию и глобальный обработчик ошибок, применяемые к каждому вызову useStorage()
  • Модуль Nuxt — автоимпорт всех composables; подключает плагин с runtime-конфигом
  • Сериализатор — JSON с поддержкой round-trip для Date, Map, Set и undefined; подключите свой сериализатор через интерфейс Serializer<T>
  • SSR-безопасность — откатывается на in-memory хранилище, когда window недоступен; ref isReady позволяет компонентам показывать скелетон до гидратации
  • Devtools — кастомный инспектор Vue Devtools и таймлайн по каждому живому экземпляру useStorage() (Vue или React) — текущее значение, цель, TTL, состояние undo/redo, плюс лог событий write/expire/migrate/sync; точка входа /devtools, опционально через setupDevtools(app)
  • Утилиты для тестов — точка входа /testing: mockStorage(), resetStorageState(), seedEnvelope()/seedExpiredEnvelope(), flushAsync() — паттерны, которые использует собственный тестовый набор пакета, упакованные для ваших тестов
  • Vue и React — опциональные peer-зависимости — @vue/devtools-api единственная обязательная runtime-зависимость (используется только при вызове setupDevtools); ни vue, ни react не требуются самим пакетом, только той точкой входа, которую вы реально импортируете. /crypto, /sync, /compress, /pinia, /devtools, /react, /testing — отдельные tree-shakeable точки входа

Установка ​

bash
npm install vue-storage-kit

Для Vue установите сам Vue (опциональная peer-зависимость — нужна только если вы импортируете из корня пакета или любой Vue-специфичный composable):

bash
npm install vue@>=3.3

Для React (vue-storage-kit/react) установите вместо этого React — vue вообще не понадобится:

bash
npm install react@>=18

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

vue
<script setup lang="ts">
import { useLocalStorage } from 'vue-storage-kit'

const { value: theme } = useLocalStorage('theme', 'light')
</script>

<template>
  <button @click="theme = theme === 'light' ? 'dark' : 'light'">
    Current theme: {{ theme }}
  </button>
</template>

Значение сохраняется в localStorage и реактивно — изменение theme.value немедленно записывается в хранилище.