Продвинутое использование

Типы TypeScript

Все публичные типы экспортируются из корня пакета:

import type {
  // Цели хранилища
  StorageTarget, // 'local' | 'session' | 'memory' | 'indexeddb'

  // Базовые опции
  StorageOptions,
  CookieOptions,
  EncryptOptions,
  SignOptions,
  CompressOptions,
  SyncOptions,

  // Миграции
  Migration,

  // Интерфейс сериализатора
  Serializer,

  // Внутренняя структура конверта
  StorageEnvelope,

  // Объединение ошибок
  StorageError,
  // { type: 'quota-exceeded'; key }
  // { type: 'parse-error'; key; raw }
  // { type: 'migration-failed'; from; to; error }
  // { type: 'crypto-error'; operation; error }
  // { type: 'write-failed'; key; error }
  // { type: 'signature-invalid'; key }
  // { type: 'read-failed'; key; error }

  // Низкоуровневый интерфейс адаптера (все методы возвращают Promise)
  StorageAdapter,

  // Возвращаемые типы
  UseStorageReturn,
  UseIndexedDBReturn,
  UseIDBRefReturn,

  // Опции плагина
  VueStoragePluginOptions,
} from 'vue-storage-kit'

Дискриминированное объединение StorageError:

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

function handleError(err: StorageError) {
  switch (err.type) {
    case 'quota-exceeded':
      console.error('Storage full, key:', err.key)
      break
    case 'parse-error':
      console.error('Could not parse', err.key, '— raw:', err.raw)
      break
    case 'migration-failed':
      console.error(`Migration ${err.from} → ${err.to} failed:`, err.error)
      break
    case 'crypto-error':
      console.error(`Crypto ${err.operation} failed:`, err.error)
      break
    case 'signature-invalid':
      console.error('Tampered or corrupted signed value:', err.key)
      break
    case 'write-failed':
      console.error('Non-quota write failure:', err.key, err.error)
      break
    case 'read-failed':
      console.error('Could not read from storage:', err.key, err.error)
      break
  }
}

Тип кастомного сериализатора:

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

const msgpack: Serializer<unknown> = {
  serialize: (v) => Buffer.from(encode(v)).toString('base64'),
  deserialize: (s) => decode(Buffer.from(s, 'base64')),
}

Совместимость с SSR

Сценарий	Поведение
typeof window === 'undefined'	Все адаптеры откатываются на MemoryStorageAdapter (в рамках процесса, не сохраняется)
isReady.value === false	Composable ещё не прочитал из хранилища; покажите скелетон или v-if="isReady"
useCookie на сервере (Nuxt)	Модуль vue-storage-kit/nuxt автоимпортирует SSR-совместимый useCookie(), который читает из event.node.req.headers.cookie и пишет httpOnly cookies через setCookie() из H3. Базовый useCookie, экспортируемый напрямую из vue-storage-kit (используется вне Nuxt или без модуля), — клиентский; document.cookie недоступен на сервере, поэтому он возвращает defaultValue при SSR
Несовпадение при гидратации	useStorage перечитывает реальное клиентское значение после монтирования — значение, отрисованное на сервере, на клиенте никогда не используется

<script setup lang="ts">
const { value: prefs, isReady } = useLocalStorage('prefs', { theme: 'light' })
</script>

<template>
  <SkeletonCard v-if="!isReady" />
  <UserPrefs v-else :prefs="prefs" />
</template>