@pyreon/storage 0.6.0

package/src/indexed-db.ts

@@ -0,0 +1,205 @@
+import { signal } from '@pyreon/reactivity'
+import { getEntry, removeEntry, setEntry } from './registry'
+import type { IndexedDBOptions, StorageSignal } from './types'
+import { deserialize, isBrowser, serialize } from './utils'
+
+// ─── Database management ─────────────────────────────────────────────────────
+
+const dbCache = new Map<string, Promise<IDBDatabase>>()
+
+function openDB(dbName: string, storeName: string): Promise<IDBDatabase> {
+  const cacheKey = `${dbName}:${storeName}`
+  const cached = dbCache.get(cacheKey)
+  if (cached) return cached
+
+  const promise = new Promise<IDBDatabase>((resolve, reject) => {
+    const request = indexedDB.open(dbName, 1)
+
+    request.onupgradeneeded = () => {
+      const db = request.result
+      if (!db.objectStoreNames.contains(storeName)) {
+        db.createObjectStore(storeName)
+      }
+    }
+
+    request.onsuccess = () => resolve(request.result)
+    request.onerror = () => reject(request.error)
+  })
+
+  dbCache.set(cacheKey, promise)
+  return promise
+}
+
+function idbGet(
+  db: IDBDatabase,
+  storeName: string,
+  key: string,
+): Promise<string | null> {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(storeName, 'readonly')
+    const store = tx.objectStore(storeName)
+    const request = store.get(key)
+    request.onsuccess = () =>
+      resolve(request.result !== undefined ? (request.result as string) : null)
+    request.onerror = () => reject(request.error)
+  })
+}
+
+function idbSet(
+  db: IDBDatabase,
+  storeName: string,
+  key: string,
+  value: string,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(storeName, 'readwrite')
+    const store = tx.objectStore(storeName)
+    const request = store.put(value, key)
+    request.onsuccess = () => resolve()
+    request.onerror = () => reject(request.error)
+  })
+}
+
+function idbDelete(
+  db: IDBDatabase,
+  storeName: string,
+  key: string,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(storeName, 'readwrite')
+    const store = tx.objectStore(storeName)
+    const request = store.delete(key)
+    request.onsuccess = () => resolve()
+    request.onerror = () => reject(request.error)
+  })
+}
+
+// ─── useIndexedDB ────────────────────────────────────────────────────────────
+
+/**
+ * Reactive signal backed by IndexedDB. Suitable for large or structured
+ * data that exceeds localStorage limits. Writes are debounced.
+ *
+ * The signal starts with `defaultValue` and updates asynchronously
+ * when the stored value is read from IndexedDB.
+ *
+ * @example
+ * ```ts
+ * const draft = useIndexedDB('article-draft', { title: '', body: '' })
+ * draft()  // { title: '', body: '' } initially, then stored value
+ * draft.set({ title: 'My Post', body: '...' })  // signal updates immediately, IDB write is debounced
+ * ```
+ */
+export function useIndexedDB<T>(
+  key: string,
+  defaultValue: T,
+  options: IndexedDBOptions<T> = {},
+): StorageSignal<T> {
+  // Return existing signal if already registered
+  const existing = getEntry<T>('indexeddb', key)
+  if (existing) return existing.signal
+
+  const dbName = options.dbName ?? 'pyreon-storage'
+  const storeName = options.storeName ?? 'kv'
+  const debounceMs = options.debounceMs ?? 100
+
+  const sig = signal<T>(defaultValue)
+
+  // Async initial load
+  if (isBrowser() && typeof indexedDB !== 'undefined') {
+    openDB(dbName, storeName)
+      .then((db) => idbGet(db, storeName, key))
+      .then((raw) => {
+        if (raw !== null) {
+          const value = deserialize(
+            raw,
+            defaultValue,
+            options.deserializer,
+            options.onError,
+          )
+          sig.set(value)
+        }
+      })
+      .catch(() => {
+        // IndexedDB not available — signal keeps defaultValue
+      })
+  }
+
+  // Debounced write
+  let writeTimer: ReturnType<typeof setTimeout> | null = null
+  let pendingValue: T | undefined
+
+  function flushWrite(): void {
+    if (pendingValue === undefined) return
+    const value = pendingValue
+    pendingValue = undefined
+
+    if (!isBrowser() || typeof indexedDB === 'undefined') return
+
+    openDB(dbName, storeName)
+      .then((db) =>
+        idbSet(db, storeName, key, serialize(value, options.serializer)),
+      )
+      .catch(() => {
+        // Write failed — signal still has the correct value
+      })
+  }
+
+  function scheduleWrite(value: T): void {
+    pendingValue = value
+    if (writeTimer !== null) clearTimeout(writeTimer)
+    writeTimer = setTimeout(flushWrite, debounceMs)
+  }
+
+  // Build the storage signal
+  const storageSig = (() => sig()) as unknown as StorageSignal<T>
+
+  storageSig.peek = () => sig.peek()
+  storageSig.subscribe = (listener: () => void) => sig.subscribe(listener)
+  storageSig.direct = (updater: () => void) => sig.direct(updater)
+  storageSig.debug = () => sig.debug()
+
+  Object.defineProperty(storageSig, 'label', {
+    get: () => sig.label,
+    set: (v: string | undefined) => {
+      sig.label = v
+    },
+  })
+
+  storageSig.set = (value: T) => {
+    sig.set(value)
+    scheduleWrite(value)
+  }
+
+  storageSig.update = (fn: (current: T) => T) => {
+    const newValue = fn(sig.peek())
+    storageSig.set(newValue)
+  }
+
+  storageSig.remove = () => {
+    sig.set(defaultValue)
+    pendingValue = undefined
+    if (writeTimer !== null) clearTimeout(writeTimer)
+
+    if (isBrowser() && typeof indexedDB !== 'undefined') {
+      openDB(dbName, storeName)
+        .then((db) => idbDelete(db, storeName, key))
+        .catch(() => {
+          // Delete failed — signal already reset
+        })
+    }
+
+    removeEntry('indexeddb', key)
+  }
+
+  setEntry('indexeddb', key, storageSig, defaultValue)
+
+  return storageSig
+}
+
+/**
+ * Reset the database cache. For testing only.
+ */
+export function _resetDBCache(): void {
+  dbCache.clear()
+}

package/src/local.ts

@@ -0,0 +1,143 @@
+import { signal } from '@pyreon/reactivity'
+import { getEntry, removeEntry, setEntry } from './registry'
+import type { StorageOptions, StorageSignal } from './types'
+import { deserialize, getWebStorage, isBrowser, serialize } from './utils'
+
+// ─── Cross-tab sync ──────────────────────────────────────────────────────────
+
+let listenerAttached = false
+
+function attachStorageListener(): void {
+  if (listenerAttached || !isBrowser()) return
+  listenerAttached = true
+
+  window.addEventListener('storage', (e) => {
+    if (!e.key) return
+    const entry = getEntry('local', e.key)
+    if (!entry) return
+
+    const newValue =
+      e.newValue !== null
+        ? deserialize(e.newValue, entry.defaultValue)
+        : entry.defaultValue
+
+    entry.signal.set(newValue)
+  })
+}
+
+// ─── useStorage ──────────────────────────────────────────────────────────────
+
+/**
+ * Reactive signal backed by localStorage. Automatically syncs across
+ * browser tabs via the native `storage` event.
+ *
+ * @example
+ * ```ts
+ * const theme = useStorage('theme', 'light')
+ * theme()            // 'light' (or stored value)
+ * theme.set('dark')  // updates signal + localStorage
+ * theme.remove()     // clears storage, resets to default
+ * ```
+ */
+export function useStorage<T>(
+  key: string,
+  defaultValue: T,
+  options?: StorageOptions<T>,
+): StorageSignal<T> {
+  // Return existing signal if already registered
+  const existing = getEntry<T>('local', key)
+  if (existing) return existing.signal
+
+  const storage = getWebStorage('local')
+
+  // Read initial value from storage
+  let initialValue = defaultValue
+  if (storage) {
+    const raw = storage.getItem(key)
+    if (raw !== null) {
+      initialValue = deserialize(
+        raw,
+        defaultValue,
+        options?.deserializer,
+        options?.onError,
+      )
+    }
+  }
+
+  const sig = signal<T>(initialValue)
+
+  // Create the storage signal by extending the base signal
+  const storageSig = createStorageSignal(
+    sig,
+    key,
+    defaultValue,
+    'local',
+    options,
+  )
+
+  setEntry('local', key, storageSig, defaultValue)
+  attachStorageListener()
+
+  return storageSig
+}
+
+// ─── Storage Signal Factory ──────────────────────────────────────────────────
+
+/**
+ * Wraps a base signal with storage persistence behavior.
+ * Used by both useStorage and useSessionStorage.
+ */
+export function createStorageSignal<T>(
+  sig: ReturnType<typeof signal<T>>,
+  key: string,
+  defaultValue: T,
+  backend: 'local' | 'session',
+  options?: StorageOptions<T>,
+): StorageSignal<T> {
+  const storage = getWebStorage(backend)
+
+  // The callable signal function (read)
+  const storageSig = (() => sig()) as unknown as StorageSignal<T>
+
+  // Delegate all signal methods
+  storageSig.peek = () => sig.peek()
+  storageSig.subscribe = (listener: () => void) => sig.subscribe(listener)
+  storageSig.direct = (updater: () => void) => sig.direct(updater)
+  storageSig.debug = () => sig.debug()
+
+  Object.defineProperty(storageSig, 'label', {
+    get: () => sig.label,
+    set: (v: string | undefined) => {
+      sig.label = v
+    },
+  })
+
+  // Override set to persist
+  storageSig.set = (value: T) => {
+    sig.set(value)
+    if (storage) {
+      try {
+        storage.setItem(key, serialize(value, options?.serializer))
+      } catch {
+        // Storage full or blocked — signal still updates
+      }
+    }
+  }
+
+  // Override update to persist
+  storageSig.update = (fn: (current: T) => T) => {
+    const newValue = fn(sig.peek())
+    storageSig.set(newValue)
+  }
+
+  // Add remove method
+  storageSig.remove = () => {
+    sig.set(defaultValue)
+    if (storage) {
+      storage.removeItem(key)
+    }
+    removeEntry(backend, key)
+  }
+
+  return storageSig
+}

package/src/registry.ts

@@ -0,0 +1,66 @@
+import type { StorageSignal } from './types'
+
+// ─── Signal Registry ─────────────────────────────────────────────────────────
+
+interface RegistryEntry<T = unknown> {
+  signal: StorageSignal<T>
+  defaultValue: T
+  backend: string
+}
+
+const registry = new Map<string, RegistryEntry>()
+
+/**
+ * Build a composite key from backend type + storage key to avoid
+ * collisions between different backends using the same key name.
+ */
+function registryKey(backend: string, key: string): string {
+  return `${backend}:${key}`
+}
+
+/**
+ * Get an existing signal from the registry.
+ */
+export function getEntry<T>(
+  backend: string,
+  key: string,
+): RegistryEntry<T> | undefined {
+  return registry.get(registryKey(backend, key)) as RegistryEntry<T> | undefined
+}
+
+/**
+ * Register a new signal in the registry.
+ */
+export function setEntry<T>(
+  backend: string,
+  key: string,
+  signal: StorageSignal<T>,
+  defaultValue: T,
+): void {
+  registry.set(registryKey(backend, key), { signal, defaultValue, backend })
+}
+
+/**
+ * Remove an entry from the registry.
+ */
+export function removeEntry(backend: string, key: string): void {
+  registry.delete(registryKey(backend, key))
+}
+
+/**
+ * Get all entries for a specific backend.
+ */
+export function getEntriesByBackend(backend: string): RegistryEntry[] {
+  const entries: RegistryEntry[] = []
+  for (const entry of registry.values()) {
+    if (entry.backend === backend) entries.push(entry)
+  }
+  return entries
+}
+
+/**
+ * Clear all entries from the registry. Used for testing.
+ */
+export function _resetRegistry(): void {
+  registry.clear()
+}

package/src/session.ts

@@ -0,0 +1,58 @@
+import { signal } from '@pyreon/reactivity'
+import { createStorageSignal } from './local'
+import { getEntry, setEntry } from './registry'
+import type { StorageOptions, StorageSignal } from './types'
+import { deserialize, getWebStorage } from './utils'
+
+// ─── useSessionStorage ───────────────────────────────────────────────────────
+
+/**
+ * Reactive signal backed by sessionStorage. Scoped to the current
+ * browser tab — does not sync across tabs.
+ *
+ * @example
+ * ```ts
+ * const step = useSessionStorage('wizard-step', 0)
+ * step()       // 0 (or stored value)
+ * step.set(3)  // updates signal + sessionStorage
+ * step.remove() // clears storage, resets to default
+ * ```
+ */
+export function useSessionStorage<T>(
+  key: string,
+  defaultValue: T,
+  options?: StorageOptions<T>,
+): StorageSignal<T> {
+  // Return existing signal if already registered
+  const existing = getEntry<T>('session', key)
+  if (existing) return existing.signal
+
+  const storage = getWebStorage('session')
+
+  // Read initial value from storage
+  let initialValue = defaultValue
+  if (storage) {
+    const raw = storage.getItem(key)
+    if (raw !== null) {
+      initialValue = deserialize(
+        raw,
+        defaultValue,
+        options?.deserializer,
+        options?.onError,
+      )
+    }
+  }
+
+  const sig = signal<T>(initialValue)
+  const storageSig = createStorageSignal(
+    sig,
+    key,
+    defaultValue,
+    'session',
+    options,
+  )
+
+  setEntry('session', key, storageSig, defaultValue)
+
+  return storageSig
+}

package/src/tests/clear.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import {
+  _resetRegistry,
+  clearStorage,
+  removeStorage,
+  useSessionStorage,
+  useStorage,
+} from '../index'
+
+describe('removeStorage', () => {
+  beforeEach(() => {
+    localStorage.clear()
+    sessionStorage.clear()
+    _resetRegistry()
+  })
+
+  afterEach(() => {
+    localStorage.clear()
+    sessionStorage.clear()
+    _resetRegistry()
+  })
+
+  it('removes a localStorage entry via signal', () => {
+    const theme = useStorage('theme', 'light')
+    theme.set('dark')
+
+    removeStorage('theme')
+    expect(theme()).toBe('light')
+    expect(localStorage.getItem('theme')).toBeNull()
+  })
+
+  it('removes a sessionStorage entry', () => {
+    const step = useSessionStorage('step', 0)
+    step.set(3)
+
+    removeStorage('step', { type: 'session' })
+    expect(step()).toBe(0)
+    expect(sessionStorage.getItem('step')).toBeNull()
+  })
+
+  it('removes raw localStorage even without a signal', () => {
+    localStorage.setItem('orphan', 'value')
+    removeStorage('orphan')
+    expect(localStorage.getItem('orphan')).toBeNull()
+  })
+
+  it('removes raw sessionStorage even without a signal', () => {
+    sessionStorage.setItem('orphan', 'value')
+    removeStorage('orphan', { type: 'session' })
+    expect(sessionStorage.getItem('orphan')).toBeNull()
+  })
+
+  it('removes cookie without a signal', () => {
+    removeStorage('orphan-cookie', { type: 'cookie' })
+    // Should not throw even when cookie doesn't exist
+  })
+})
+
+describe('clearStorage', () => {
+  beforeEach(() => {
+    localStorage.clear()
+    sessionStorage.clear()
+    _resetRegistry()
+  })
+
+  afterEach(() => {
+    localStorage.clear()
+    sessionStorage.clear()
+    _resetRegistry()
+  })
+
+  it('clears all managed localStorage entries', () => {
+    const a = useStorage('a', 1)
+    const b = useStorage('b', 2)
+    a.set(10)
+    b.set(20)
+
+    clearStorage()
+    expect(a()).toBe(1)
+    expect(b()).toBe(2)
+  })
+
+  it('clears all managed sessionStorage entries', () => {
+    const a = useSessionStorage('a', 'x')
+    const b = useSessionStorage('b', 'y')
+    a.set('modified')
+    b.set('modified')
+
+    clearStorage('session')
+    expect(a()).toBe('x')
+    expect(b()).toBe('y')
+  })
+
+  it('clears all backends with "all"', () => {
+    const local = useStorage('l', 'default')
+    const session = useSessionStorage('s', 'default')
+    local.set('changed')
+    session.set('changed')
+
+    clearStorage('all')
+    expect(local()).toBe('default')
+    expect(session()).toBe('default')
+  })
+})