@pyreon/storage 0.6.0

package/src/tests/session.test.ts

@@ -0,0 +1,67 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { _resetRegistry, useSessionStorage } from '../index'
+
+describe('useSessionStorage', () => {
+  beforeEach(() => {
+    sessionStorage.clear()
+    _resetRegistry()
+  })
+
+  afterEach(() => {
+    sessionStorage.clear()
+    _resetRegistry()
+  })
+
+  it('returns default value when key is not in storage', () => {
+    const step = useSessionStorage('step', 0)
+    expect(step()).toBe(0)
+  })
+
+  it('reads existing value from sessionStorage', () => {
+    sessionStorage.setItem('step', JSON.stringify(3))
+    const step = useSessionStorage('step', 0)
+    expect(step()).toBe(3)
+  })
+
+  it('.set() updates signal and sessionStorage', () => {
+    const step = useSessionStorage('step', 0)
+    step.set(5)
+    expect(step()).toBe(5)
+    expect(JSON.parse(sessionStorage.getItem('step')!)).toBe(5)
+  })
+
+  it('.remove() clears from storage and resets to default', () => {
+    const step = useSessionStorage('step', 0)
+    step.set(5)
+    step.remove()
+    expect(step()).toBe(0)
+    expect(sessionStorage.getItem('step')).toBeNull()
+  })
+
+  it('returns same signal instance for same key', () => {
+    const a = useSessionStorage('step', 0)
+    const b = useSessionStorage('step', 0)
+    expect(a).toBe(b)
+  })
+
+  it('works with objects', () => {
+    const form = useSessionStorage('form-draft', { name: '', email: '' })
+    form.set({ name: 'Alice', email: 'alice@example.com' })
+    expect(form()).toEqual({ name: 'Alice', email: 'alice@example.com' })
+  })
+
+  it('handles corrupt storage values gracefully', () => {
+    sessionStorage.setItem('broken', '{{invalid')
+    const value = useSessionStorage('broken', 'default')
+    expect(value()).toBe('default')
+  })
+
+  it('does not share signals with localStorage', async () => {
+    const { useStorage } = await import('../local')
+    const local = useStorage('key', 'local-default')
+    const session = useSessionStorage('key', 'session-default')
+    expect(local).not.toBe(session)
+    expect(local()).toBe('local-default')
+    expect(session()).toBe('session-default')
+  })
+})

package/src/types.ts

@@ -0,0 +1,86 @@
+import type { Signal } from '@pyreon/reactivity'
+
+// ─── Storage Signal ──────────────────────────────────────────────────────────
+
+/**
+ * A signal backed by a storage backend. Behaves like a normal signal
+ * but persists writes to the underlying storage mechanism.
+ */
+export interface StorageSignal<T> extends Signal<T> {
+  /** Remove the value from storage and reset to the default value */
+  remove(): void
+}
+
+// ─── Shared Options ──────────────────────────────────────────────────────────
+
+/**
+ * Base options shared by all storage hooks.
+ */
+export interface StorageOptions<T> {
+  /** Custom serializer — default: JSON.stringify */
+  serializer?: (value: T) => string
+  /** Custom deserializer — default: JSON.parse */
+  deserializer?: (raw: string) => T
+  /** Called when deserialization fails — returns fallback or void for default */
+  onError?: (error: Error) => T | undefined
+}
+
+// ─── Cookie Options ──────────────────────────────────────────────────────────
+
+/**
+ * Options for the useCookie hook.
+ */
+export interface CookieOptions<T> extends StorageOptions<T> {
+  /** Max age in seconds */
+  maxAge?: number
+  /** Expiry date (alternative to maxAge) */
+  expires?: Date
+  /** Cookie path — default: '/' */
+  path?: string
+  /** Cookie domain */
+  domain?: string
+  /** HTTPS only — default: false */
+  secure?: boolean
+  /** SameSite policy — default: 'lax' */
+  sameSite?: 'strict' | 'lax' | 'none'
+}
+
+// ─── IndexedDB Options ───────────────────────────────────────────────────────
+
+/**
+ * Options for the useIndexedDB hook.
+ */
+export interface IndexedDBOptions<T> extends StorageOptions<T> {
+  /** Database name — default: 'pyreon-storage' */
+  dbName?: string
+  /** Object store name — default: 'kv' */
+  storeName?: string
+  /** Write debounce in ms — default: 100 */
+  debounceMs?: number
+}
+
+// ─── Custom Storage Backend ──────────────────────────────────────────────────
+
+/**
+ * Interface for a custom storage backend used with createStorage.
+ */
+export interface StorageBackend {
+  /** Read a raw string value by key. Return null if not found. */
+  get(key: string): string | null
+  /** Write a raw string value by key */
+  set(key: string, value: string): void
+  /** Remove a value by key */
+  remove(key: string): void
+}
+
+/**
+ * Async variant for backends like IndexedDB.
+ */
+export interface AsyncStorageBackend {
+  /** Read a raw string value by key */
+  get(key: string): Promise<string | null>
+  /** Write a raw string value by key */
+  set(key: string, value: string): Promise<void>
+  /** Remove a value by key */
+  remove(key: string): Promise<void>
+}

package/src/utils.ts

@@ -0,0 +1,66 @@
+import type { StorageOptions } from './types'
+
+// ─── SSR Detection ───────────────────────────────────────────────────────────
+
+/**
+ * Check if we're running in a browser environment.
+ */
+export function isBrowser(): boolean {
+  return typeof window !== 'undefined' && typeof document !== 'undefined'
+}
+
+// ─── Serialization ───────────────────────────────────────────────────────────
+
+/**
+ * Serialize a value to a string for storage.
+ */
+export function serialize<T>(
+  value: T,
+  serializer?: StorageOptions<T>['serializer'],
+): string {
+  if (serializer) return serializer(value)
+  return JSON.stringify(value)
+}
+
+/**
+ * Deserialize a raw string from storage back to a typed value.
+ * Returns the default value if deserialization fails.
+ */
+export function deserialize<T>(
+  raw: string,
+  defaultValue: T,
+  deserializer?: StorageOptions<T>['deserializer'],
+  onError?: StorageOptions<T>['onError'],
+): T {
+  try {
+    if (deserializer) return deserializer(raw)
+    return JSON.parse(raw) as T
+  } catch (e) {
+    if (onError) {
+      const result = onError(e as Error)
+      return result !== undefined ? result : defaultValue
+    }
+    return defaultValue
+  }
+}
+
+// ─── Safe Storage Access ─────────────────────────────────────────────────────
+
+/**
+ * Safely get a Web Storage instance (localStorage or sessionStorage).
+ * Returns null if not available (SSR, security restrictions, etc.).
+ */
+export function getWebStorage(type: 'local' | 'session'): Storage | null {
+  if (!isBrowser()) return null
+  try {
+    const storage =
+      type === 'local' ? window.localStorage : window.sessionStorage
+    // Test that it actually works (can throw in private browsing)
+    const testKey = '__pyreon_storage_test__'
+    storage.setItem(testKey, '1')
+    storage.removeItem(testKey)
+    return storage
+  } catch {
+    return null
+  }
+}