Справочник API

useStorage

Базовый composable. Работает с localStorage, sessionStorage и in-memory запасным вариантом.

useStorage<T>(key: string, options: StorageOptions<T>): UseStorageReturn<T>

Опции

Опция	Тип	По умолчанию	Описание
defaultValue	T	—	Значение, возвращаемое, когда ключ отсутствует или истёк
target	'local' | 'session' | 'memory' | 'indexeddb'	'local'	Backend хранилища. 'indexeddb' хранит через единственное выделенное object store (БД vue-storage-kit, store kv) — для собственных баз/store или вторичных индексов используйте useIndexedDB() / useIDBRef()
ttl	number	—	Время жизни в миллисекундах; 0 или не задано = без истечения
version	number	1	Версия схемы сохранённых данных
migrations	Migration[]	[]	Функции миграции, запускаемые при несовпадении сохранённой версии с version
encrypt	boolean | EncryptOptions	false	Включить AES-GCM шифрование
compress	boolean | CompressOptions	false	Сжимать сохранённый конверт через Compression Streams API. Применяется до encrypt, так что сжатие всё ещё работает на открытом тексте (сжатый шифротекст не даёт выигрыша в размере)
sign	boolean | SignOptions	false	Проверка HMAC-SHA256, применяется как самый внешний слой (оборачивает и сжатые/зашифрованные данные тоже). Обнаруживает случайное повреждение без требования секретности — не защита от пользователя, редактирующего собственное хранилище (см. Обнаружение повреждения) — комбинируйте с encrypt для обоих
sync	boolean | SyncOptions	false	Включить синхронизацию между вкладками через BroadcastChannel
debounce	number	—	Объединяет записи: сохраняет только через debounce мс после последнего изменения. Взаимоисключающе с throttle (при обоих заданных побеждает throttle)
throttle	number	—	Писать не чаще раза в throttle мс даже при непрерывных изменениях, вместо ожидания их остановки
history	number	—	Хранить в памяти до этого числа прошлых значений для undo()/redo(). Не сохраняется — сбрасывается при перезагрузке
evictOnQuota	boolean | { max?: number }	false	При QuotaExceededError, если зачистки истёкших по TTL записей этого адаптера недостаточно, вытесняет его наименее недавно записанные другие ключи (сначала самые старые, до max, по умолчанию 1) и повторяет попытку. Выключено по умолчанию — удаление несвязанных ключей это реальный побочный эффект
serializer	Serializer<T>	JSON-сериализатор	Кастомная пара сериализации/десериализации
onError	(err: StorageError) => void	—	Вызывается вместо выброса исключения при превышении квоты, ошибках парсинга, ошибках криптографии, неверных подписях или других сбоях записи
onExpire	(key: string) => void	—	Вызывается, когда истёкший по TTL ключ удаляется при чтении
onMigrate	(from: number, to: number) => void	—	Вызывается после успешной миграции

Возвращаемое значение

Свойство	Тип	Описание
value	Ref<T>	Реактивная двусторонняя привязка; присваивание пишет в хранилище
isReady	Ref<boolean>	false, пока не завершится первичное асинхронное чтение (важно для IndexedDB и зашифрованных значений)
error	Ref<StorageError | null>	Последняя ошибка, null, если её нет
expiry	ComputedRef<Date | null>	Когда ключ истекает, null, если TTL не задан
canUndo / canRedo	ComputedRef<boolean>	Есть ли эффект от undo() / redo() прямо сейчас (всегда false, если history не задан)
remove()	void	Удалить ключ из хранилища и сбросить value к defaultValue
refresh()	Promise<void>	Перечитать из хранилища (полезно, если другой процесс мог записать)
undo() / redo()	void	Перемещение по значениям, записанным через history; no-op, если history не задан или соответствующий стек пуст

Примеры

Базовое чтение/запись:

const { value: counter } = useStorage('counter', { defaultValue: 0 })

counter.value++ // немедленно пишет в localStorage

Session storage:

const { value: token } = useStorage('auth-token', {
  defaultValue: '',
  target: 'session',
})

TTL — автоматическое истечение через 30 минут:

const { value: cache, expiry } = useStorage('search-cache', {
  defaultValue: [] as string[],
  ttl: 30 * 60 * 1000,
  onExpire: (key) => console.log(`${key} expired`),
})

console.log(expiry.value) // Date | null

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

const { value, error } = useStorage('data', {
  defaultValue: {},
  onError: (err) => {
    if (err.type === 'quota-exceeded') showToast('Storage is full')
    if (err.type === 'parse-error') console.warn('Corrupted value, reset to default')
  },
})

Кастомный сериализатор:

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

const base64Serializer: Serializer<string> = {
  serialize: (v) => btoa(v),
  deserialize: (raw) => atob(raw),
}

const { value } = useStorage('encoded', {
  defaultValue: '',
  serializer: base64Serializer,
})

useLocalStorage / useSessionStorage

Сокращённые composables — идентичны useStorage, но с предустановленным target и defaultValue в качестве второго аргумента (сигнатура, совместимая с vueuse).

useLocalStorage<T>(key: string, defaultValue: T, opts?): UseStorageReturn<T>
useSessionStorage<T>(key: string, defaultValue: T, opts?): UseStorageReturn<T>

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

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

Это прямые замены useLocalStorage / useSessionStorage из @vueuse/core.