@vobs/storage 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vobs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @vobs/storage
+
+Versioned key-value storage for vobs with a JSON envelope, cross-tab change events, migration, and automatic memory fallback.
+
+## Install
+
+```bash
+npm install @vobs/storage
+```
+
+## Quick start
+
+```ts
+import { createStorage } from '@vobs/storage'
+
+const storage = createStorage({
+  storage: 'local', // 'local', 'session', 'memory', or a custom StorageLike
+  prefix: 'myapp:',
+  version: 2,
+  migrate: (value, from, to) => (to === 2 ? { theme: value } : value)
+})
+
+storage.set('settings', { theme: 'dark' })
+storage.get<{ theme: string }>('settings') // { theme: 'dark' }
+
+const unsubscribe = storage.subscribe(change => {
+  change.source // 'local' for own writes, 'external' for other tabs
+})
+```
+
+Every value is written as an envelope carrying its version, so reads of older data run through `migrate` and are persisted back at the new version. Invalid JSON is reported as `CORRUPT_DATA`, removed, and reads return null. If the backend throws, the context degrades to the memory fallback and reports `STORAGE_UNAVAILABLE`. Writes from other tabs arrive through browser `storage` events with `source: 'external'`.
+
+## API
+
+| Signature | Description |
+| --- | --- |
+| `createStorage(options?: StorageOptions): StorageContext` | Options: backend, `fallback`, `prefix` (default `vobs:`), `version`, `migrate`, `onError`. |
+| `storage.get(key) / set(key, value) / remove(key)` | JSON round-trip under the configured prefix. |
+| `storage.has(key) / keys() / clear()` | Prefix-scoped inspection and cleanup. |
+| `storage.subscribe(listener)` | Receives `{ key, value, source }`; returns an unsubscribe function. |
+| `storage.kind / persistent / prefix / version` | Current backend kind (`local`, `session`, `memory`, `custom`) and configuration. |
+| `storage.dispose()` | Stops listeners; further use of the context throws. |
+| `createMemoryStorage() / memoryStorage` | In-memory `StorageLike` for tests and SSR. |
+| `storagePlugin(options?)` | Provide the context as `STORAGE_KEY`; disposes it on uninstall. |
+| `useStorage()` | Inject the context installed by `storagePlugin`. |
+| `StorageError` | Error with `code` (`STORAGE_UNAVAILABLE`, `CORRUPT_DATA`, `SERIALIZATION_FAILED`, `MIGRATION_FAILED`), `key`, and `cause`. |
+
+## Types
+
+StorageType, StorageKind, StorageLike, StorageMigration, StorageOptions, StorageChange, StorageContext, StoragePluginOptions, StorageErrorCode

package/package.json

@@ -0,0 +1,20 @@
+{
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "name": "@vobs/storage",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@vobs/reactivity": "1.0.0",
+    "@vobs/vobs": "1.0.0"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,160 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createText, createVobs, createDOMRenderer, setRenderer } from '@vobs/vobs'
+import {
+  STORAGE_KEY,
+  StorageError,
+  createMemoryStorage,
+  createStorage,
+  storagePlugin,
+  useStorage
+} from './index'
+
+describe('@vobs/storage', () => {
+  beforeEach(() => {
+    setRenderer(createDOMRenderer())
+    window.localStorage.clear()
+    window.sessionStorage.clear()
+  })
+
+  it('支持 JSON set/get、has、keys、remove 和 prefix 隔离', () => {
+    const storage = createStorage({ storage: 'memory', prefix: 'test:' })
+    storage.set('user', { id: '1', roles: ['admin'] })
+    storage.set('count', 2)
+
+    expect(storage.get('user')).toEqual({ id: '1', roles: ['admin'] })
+    expect(storage.has('count')).toBe(true)
+    expect(storage.keys()).toEqual(['user', 'count'])
+    expect(storage.get('missing')).toBeNull()
+    storage.remove('count')
+    expect(storage.has('count')).toBe(false)
+    expect(storage.keys()).toEqual(['user'])
+    storage.dispose()
+  })
+
+  it('优先使用 localStorage/sessionStorage，并在 SSR 或不可用时使用内存 fallback', () => {
+    const local = createStorage({ prefix: 'local:' })
+    const session = createStorage({ storage: 'session', prefix: 'session:' })
+    local.set('value', 'local')
+    session.set('value', 'session')
+    expect(window.localStorage.getItem('local:value')).toContain('local')
+    expect(window.sessionStorage.getItem('session:value')).toContain('session')
+    expect(local.kind).toBe('local')
+    expect(session.kind).toBe('session')
+
+    const broken: Storage = {
+      get length(): number { throw new Error('blocked') },
+      getItem(): string | null { throw new Error('blocked') },
+      setItem(): void { throw new Error('blocked') },
+      removeItem(): void { throw new Error('blocked') },
+      key(): string | null { throw new Error('blocked') },
+      clear(): void { throw new Error('blocked') }
+    }
+    const onError = vi.fn()
+    const fallback = createMemoryStorage()
+    const degraded = createStorage({ storage: broken, fallback, onError })
+    degraded.set('value', 'memory')
+    expect(degraded.kind).toBe('memory')
+    expect(degraded.get('value')).toBe('memory')
+    expect(onError).toHaveBeenCalledWith(expect.objectContaining({ code: 'STORAGE_UNAVAILABLE' }))
+    local.dispose()
+    session.dispose()
+    degraded.dispose()
+  })
+
+  it('损坏 JSON 会报告错误、删除坏值并返回 null', () => {
+    const backend = createMemoryStorage()
+    backend.setItem('vobs:broken', '{not-json')
+    const onError = vi.fn()
+    const storage = createStorage({ storage: backend, onError })
+
+    expect(storage.get('broken')).toBeNull()
+    expect(backend.getItem('vobs:broken')).toBeNull()
+    expect(onError).toHaveBeenCalledWith(expect.objectContaining({ code: 'CORRUPT_DATA' }))
+    storage.dispose()
+  })
+
+  it('读取旧版本时执行迁移并保存新 envelope', () => {
+    const backend = createMemoryStorage()
+    backend.setItem('vobs:settings', JSON.stringify({ __vobsStorage: true, version: 1, value: { compact: true } }))
+    const migrate = vi.fn((value: unknown, from: number, to: number) => ({
+      density: (value as { compact: boolean }).compact ? 'compact' : 'comfortable',
+      migrated: `${from}->${to}`
+    }))
+    const storage = createStorage({ storage: backend, version: 2, migrate })
+
+    expect(storage.get('settings')).toEqual({ density: 'compact', migrated: '1->2' })
+    expect(migrate).toHaveBeenCalledWith({ compact: true }, 1, 2)
+    expect(backend.getItem('vobs:settings')).toContain('"version":2')
+    storage.dispose()
+  })
+
+  it('迁移失败返回 null 且保留旧数据', () => {
+    const backend = createMemoryStorage()
+    const oldValue = JSON.stringify({ __vobsStorage: true, version: 1, value: { old: true } })
+    backend.setItem('vobs:settings', oldValue)
+    const onError = vi.fn()
+    const storage = createStorage({
+      storage: backend,
+      version: 2,
+      migrate: () => { throw new Error('cannot migrate') },
+      onError
+    })
+
+    expect(storage.get('settings')).toBeNull()
+    expect(backend.getItem('vobs:settings')).toBe(oldValue)
+    expect(onError).toHaveBeenCalledWith(expect.objectContaining({ code: 'MIGRATION_FAILED' }))
+    storage.dispose()
+  })
+
+  it('订阅本实例写入、删除、清空和浏览器跨标签页变化', () => {
+    const storage = createStorage({ prefix: 'events:' })
+    const changes: string[] = []
+    storage.subscribe(change => changes.push(`${change.source}:${change.key}:${String(change.value)}`))
+    storage.set('one', 1)
+    storage.remove('one')
+    storage.set('two', 2)
+    storage.clear()
+    window.dispatchEvent(new StorageEvent('storage', {
+      key: 'events:remote',
+      newValue: JSON.stringify({ __vobsStorage: true, version: 1, value: 'yes' }),
+      storageArea: window.localStorage
+    }))
+
+    expect(changes).toEqual([
+      'local:one:1',
+      'local:one:null',
+      'local:two:2',
+      'local:two:null',
+      'external:remote:yes'
+    ])
+    storage.dispose()
+  })
+
+  it('插件注入 StorageContext，应用销毁后上下文不可用', () => {
+    let injected: ReturnType<typeof createStorage> | undefined
+    const app = createVobs({
+      render: () => createText('app'),
+      plugins: [{
+        name: 'consumer',
+        requires: [storagePlugin({ storage: 'memory' })],
+        install(context) { injected = context.inject(STORAGE_KEY) }
+      }]
+    })
+    expect(injected).toBeDefined()
+    injected?.set('answer', 42)
+    expect(injected?.get('answer')).toBe(42)
+    app.destroy()
+    expect(() => injected?.get('answer')).toThrow('已销毁')
+  })
+
+  it('未安装插件时 useStorage 给出明确错误', () => {
+    const app = createVobs({ render: () => {
+      useStorage()
+      return createText('')
+    } })
+    expect(() => app.mount(document.createElement('div'))).toThrowError(
+      expect.objectContaining({ code: 'STORAGE_UNAVAILABLE' })
+    )
+    expect(StorageError).toBeDefined()
+  })
+})

package/src/index.ts

@@ -0,0 +1,391 @@
+import { getCurrentOwner, onDispose } from '@vobs/reactivity'
+import { createInjectionKey, inject, type InjectionKey, type VobsPlugin } from '@vobs/vobs'
+
+export type StorageType = 'local' | 'session' | 'memory'
+export type StorageKind = StorageType | 'custom'
+
+export interface StorageLike {
+  readonly length: number
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+  removeItem(key: string): void
+  key(index: number): string | null
+}
+
+export type StorageMigration = (
+  value: unknown,
+  fromVersion: number,
+  toVersion: number
+) => unknown
+
+export interface StorageOptions {
+  readonly storage?: StorageLike | StorageType
+  readonly fallback?: StorageLike
+  readonly prefix?: string
+  readonly version?: number
+  readonly migrate?: StorageMigration
+  readonly onError?: (error: StorageError) => void
+}
+
+export interface StorageChange {
+  readonly key: string
+  readonly value: unknown | null
+  readonly source: 'local' | 'external'
+}
+
+export interface StorageContext {
+  readonly kind: StorageKind
+  readonly persistent: boolean
+  readonly prefix: string
+  readonly version: number
+  get<T>(key: string): T | null
+  set<T>(key: string, value: T): void
+  remove(key: string): void
+  clear(): void
+  has(key: string): boolean
+  keys(): readonly string[]
+  subscribe(listener: (change: StorageChange) => void): () => void
+  dispose(): void
+}
+
+export type StorageErrorCode =
+  | 'STORAGE_UNAVAILABLE'
+  | 'CORRUPT_DATA'
+  | 'SERIALIZATION_FAILED'
+  | 'MIGRATION_FAILED'
+
+export class StorageError extends Error {
+  readonly code: StorageErrorCode
+  readonly key: string | undefined
+  readonly cause: unknown
+
+  constructor(code: StorageErrorCode, message: string, key?: string, cause?: unknown) {
+    super(message)
+    this.name = 'StorageError'
+    this.code = code
+    this.key = key
+    this.cause = cause
+  }
+}
+
+export const STORAGE_KEY: InjectionKey<StorageContext> = createInjectionKey<StorageContext>('vobs.storage')
+
+export interface StoragePluginOptions extends StorageOptions {
+  readonly context?: StorageContext
+}
+
+interface Envelope {
+  readonly __vobsStorage: true
+  readonly version: number
+  readonly value: unknown
+}
+
+export function createMemoryStorage(): StorageLike {
+  const values = new Map<string, string>()
+  return {
+    get length(): number {
+      return values.size
+    },
+    getItem(key): string | null {
+      return values.get(key) ?? null
+    },
+    setItem(key, value): void {
+      values.set(key, value)
+    },
+    removeItem(key): void {
+      values.delete(key)
+    },
+    key(index): string | null {
+      return [...values.keys()][index] ?? null
+    }
+  }
+}
+
+export const memoryStorage = createMemoryStorage()
+
+export function createStorage(options: StorageOptions = {}): StorageContext {
+  const prefix = options.prefix ?? 'vobs:'
+  const version = validateVersion(options.version ?? 1)
+  const fallback = options.fallback ?? createMemoryStorage()
+  const selected = resolveStorage(options.storage)
+  let backend = selected.backend ?? fallback
+  let kind: StorageKind = selected.kind
+  let disposed = false
+  let stopBrowserListener: (() => void) | undefined
+  const listeners = new Set<(change: StorageChange) => void>()
+
+  const context: StorageContext = {
+    get kind(): StorageKind {
+      return kind
+    },
+
+    get persistent(): boolean {
+      return kind !== 'memory'
+    },
+
+    prefix,
+    version,
+
+    get<T>(key: string): T | null {
+      ensureActive()
+      const normalizedKey = validateKey(key)
+      const raw = read(normalizedKey)
+      if (raw === null) return null
+      return decode<T>(normalizedKey, raw)
+    },
+
+    set<T>(key: string, value: T): void {
+      ensureActive()
+      const normalizedKey = validateKey(key)
+      let raw: string
+      try {
+        raw = JSON.stringify({ __vobsStorage: true, version, value } satisfies Envelope)
+      } catch (error) {
+        const storageError = new StorageError(
+          'SERIALIZATION_FAILED',
+          `Vobs Storage: 无法序列化键 ${normalizedKey}`,
+          normalizedKey,
+          error
+        )
+        report(storageError)
+        throw storageError
+      }
+      write(normalizedKey, raw)
+      emit({ key: normalizedKey, value, source: 'local' })
+    },
+
+    remove(key: string): void {
+      ensureActive()
+      const normalizedKey = validateKey(key)
+      withBackend(normalizedKey, () => backend.removeItem(toPhysicalKey(normalizedKey)))
+      emit({ key: normalizedKey, value: null, source: 'local' })
+    },
+
+    clear(): void {
+      ensureActive()
+      const physicalKeys = listPhysicalKeys()
+      for (const physicalKey of physicalKeys) {
+        withBackend(physicalKey, () => backend.removeItem(physicalKey))
+      }
+      for (const physicalKey of physicalKeys) {
+        emit({ key: physicalKey.slice(prefix.length), value: null, source: 'local' })
+      }
+    },
+
+    has(key: string): boolean {
+      return context.get(key) !== null
+    },
+
+    keys(): readonly string[] {
+      ensureActive()
+      return listPhysicalKeys().map(key => key.slice(prefix.length))
+    },
+
+    subscribe(listener): () => void {
+      ensureActive()
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+
+    dispose(): void {
+      if (disposed) return
+      disposed = true
+      stopBrowserListener?.()
+      stopBrowserListener = undefined
+      listeners.clear()
+    }
+  }
+
+  if (selected.browserStorage && typeof window !== 'undefined') {
+    const onStorage = (event: StorageEvent): void => {
+      if (event.storageArea && event.storageArea !== backend) return
+      if (!event.key || !event.key.startsWith(prefix)) return
+      const key = event.key.slice(prefix.length)
+      emit({ key, value: event.newValue === null ? null : decodeExternal(key, event.newValue), source: 'external' })
+    }
+    window.addEventListener('storage', onStorage)
+    stopBrowserListener = () => window.removeEventListener('storage', onStorage)
+  }
+
+  if (getCurrentOwner()) onDispose(context.dispose)
+  return context
+
+  function read(key: string): string | null {
+    return withBackend(key, () => backend.getItem(toPhysicalKey(key)))
+  }
+
+  function write(key: string, value: string): void {
+    withBackend(key, () => backend.setItem(toPhysicalKey(key), value))
+  }
+
+  function decode<T>(key: string, raw: string): T | null {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(raw)
+    } catch (error) {
+      handleCorrupt(key, error)
+      return null
+    }
+
+    const envelope = isEnvelope(parsed) ? parsed : { version: 0, value: parsed }
+    if (envelope.version >= version || !options.migrate) return envelope.value as T | null
+
+    try {
+      const migrated = options.migrate(envelope.value, envelope.version, version)
+      write(key, JSON.stringify({ __vobsStorage: true, version, value: migrated } satisfies Envelope))
+      return migrated as T | null
+    } catch (error) {
+      const storageError = new StorageError(
+        'MIGRATION_FAILED',
+        `Vobs Storage: 键 ${key} 迁移失败`,
+        key,
+        error
+      )
+      report(storageError)
+      return null
+    }
+  }
+
+  function decodeExternal(key: string, raw: string): unknown | null {
+    try {
+      const parsed = JSON.parse(raw)
+      return isEnvelope(parsed) ? parsed.value : parsed
+    } catch (error) {
+      handleCorrupt(key, error)
+      return null
+    }
+  }
+
+  function handleCorrupt(key: string, cause: unknown): void {
+    const storageError = new StorageError(
+      'CORRUPT_DATA',
+      `Vobs Storage: 键 ${key} 的数据已损坏`,
+      key,
+      cause
+    )
+    report(storageError)
+    withBackend(key, () => backend.removeItem(toPhysicalKey(key)))
+  }
+
+  function withBackend<T>(key: string, operation: () => T): T {
+    try {
+      return operation()
+    } catch (error) {
+      if (backend === fallback) {
+        const storageError = new StorageError(
+          'STORAGE_UNAVAILABLE',
+          'Vobs Storage: 存储不可用',
+          key,
+          error
+        )
+        report(storageError)
+        throw storageError
+      }
+      const storageError = new StorageError(
+        'STORAGE_UNAVAILABLE',
+        'Vobs Storage: 存储不可用，已切换到内存 fallback',
+        key,
+        error
+      )
+      report(storageError)
+      backend = fallback
+      kind = 'memory'
+      return operation()
+    }
+  }
+
+  function listPhysicalKeys(): string[] {
+    const keys: string[] = []
+    for (let index = 0; index < backend.length; index++) {
+      const key = backend.key(index)
+      if (key?.startsWith(prefix)) keys.push(key)
+    }
+    return keys
+  }
+
+  function emit(change: StorageChange): void {
+    for (const listener of [...listeners]) {
+      try {
+        listener(change)
+      } catch {
+        // 订阅者错误不能阻止其他订阅者接收变化。
+      }
+    }
+  }
+
+  function report(error: StorageError): void {
+    try {
+      options.onError?.(error)
+    } catch {
+      // 错误回调不能覆盖存储操作的原始结果。
+    }
+  }
+
+  function ensureActive(): void {
+    if (disposed) throw new Error('Vobs Storage: 已销毁的上下文不能继续使用')
+  }
+
+  function toPhysicalKey(key: string): string {
+    return `${prefix}${key}`
+  }
+}
+
+export function storagePlugin(options: StoragePluginOptions = {}): VobsPlugin {
+  return {
+    name: '@vobs/storage',
+    version: '0.1.0',
+    install(context) {
+      const ownedStorage = options.context ? undefined : createStorage(options)
+      context.provide(STORAGE_KEY, options.context ?? ownedStorage!)
+      return () => ownedStorage?.dispose()
+    }
+  }
+}
+
+export function useStorage(): StorageContext {
+  const storage = inject(STORAGE_KEY)
+  if (!storage) throw new StorageError('STORAGE_UNAVAILABLE', 'Vobs Storage: 找不到上下文，请安装 storagePlugin')
+  return storage
+}
+
+function resolveStorage(input: StorageLike | StorageType | undefined): {
+  backend: StorageLike | undefined
+  kind: StorageKind
+  browserStorage: boolean
+} {
+  if (input && typeof input !== 'string') return { backend: input, kind: 'custom', browserStorage: false }
+  const type = input ?? 'local'
+  if (type === 'memory') return { backend: memoryStorage, kind: 'memory', browserStorage: false }
+  const backend = getBrowserStorage(type)
+  return { backend, kind: backend ? type : 'memory', browserStorage: Boolean(backend) }
+}
+
+function getBrowserStorage(type: Exclude<StorageType, 'memory'>): StorageLike | undefined {
+  if (typeof window === 'undefined') return undefined
+  try {
+    return type === 'local' ? window.localStorage : window.sessionStorage
+  } catch {
+    return undefined
+  }
+}
+
+function isEnvelope(value: unknown): value is Envelope {
+  return Boolean(value)
+    && typeof value === 'object'
+    && value !== null
+    && (value as { __vobsStorage?: unknown }).__vobsStorage === true
+    && Number.isInteger((value as { version?: unknown }).version)
+    && 'value' in value
+}
+
+function validateKey(key: string): string {
+  if (typeof key !== 'string' || !key.trim()) throw new Error('Vobs Storage: key 不能为空')
+  return key
+}
+
+function validateVersion(version: number): number {
+  if (!Number.isInteger(version) || version < 0) {
+    throw new Error('Vobs Storage: version 必须是大于等于 0 的整数')
+  }
+  return version
+}