@pyreon/storage 0.6.0

package/lib/types/index2.d.ts

@@ -0,0 +1,220 @@
+import { Signal, signal } from "@pyreon/reactivity";
+
+//#region src/types.d.ts
+/**
+ * A signal backed by a storage backend. Behaves like a normal signal
+ * but persists writes to the underlying storage mechanism.
+ */
+interface StorageSignal<T> extends Signal<T> {
+  /** Remove the value from storage and reset to the default value */
+  remove(): void;
+}
+/**
+ * Base options shared by all storage hooks.
+ */
+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;
+}
+/**
+ * Options for the useCookie hook.
+ */
+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';
+}
+/**
+ * Options for the useIndexedDB hook.
+ */
+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;
+}
+/**
+ * Interface for a custom storage backend used with createStorage.
+ */
+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.
+ */
+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>;
+}
+//#endregion
+//#region src/cookie.d.ts
+/**
+ * Set the cookie source string for SSR. Call this once per request
+ * with the raw Cookie header value.
+ *
+ * @example
+ * ```ts
+ * // In your SSR request handler
+ * setCookieSource(request.headers.get('cookie') ?? '')
+ * ```
+ */
+declare function setCookieSource(cookieHeader: string): void;
+/**
+ * Reactive signal backed by a browser cookie. SSR-compatible when
+ * used with setCookieSource().
+ *
+ * @example
+ * ```ts
+ * const locale = useCookie('locale', 'en', {
+ *   maxAge: 60 * 60 * 24 * 365, // 1 year
+ *   path: '/',
+ *   sameSite: 'lax',
+ * })
+ * locale()          // 'en'
+ * locale.set('de')  // sets cookie + updates signal
+ * locale.remove()   // deletes cookie, resets to default
+ * ```
+ */
+declare function useCookie<T>(key: string, defaultValue: T, options?: CookieOptions<T>): StorageSignal<T>;
+//#endregion
+//#region src/custom.d.ts
+/**
+ * Create a custom storage hook backed by any synchronous storage backend.
+ * Useful for encrypted storage, in-memory storage, or custom adapters.
+ *
+ * @example
+ * ```ts
+ * const useEncrypted = createStorage({
+ *   get: (key) => decrypt(localStorage.getItem(key)),
+ *   set: (key, value) => localStorage.setItem(key, encrypt(value)),
+ *   remove: (key) => localStorage.removeItem(key),
+ * })
+ *
+ * const secret = useEncrypted('api-key', '')
+ * ```
+ */
+declare function createStorage(backend: StorageBackend, backendName?: string): <T>(key: string, defaultValue: T, options?: StorageOptions<T>) => StorageSignal<T>;
+/**
+ * In-memory storage backend. Useful for SSR, testing, or ephemeral state.
+ * Values are lost on page unload.
+ *
+ * @example
+ * ```ts
+ * import { useMemoryStorage } from '@pyreon/storage'
+ *
+ * const temp = useMemoryStorage('key', 'default')
+ * ```
+ */
+declare const useMemoryStorage: <T>(key: string, defaultValue: T, options?: StorageOptions<T>) => StorageSignal<T>;
+//#endregion
+//#region src/indexed-db.d.ts
+/**
+ * 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
+ * ```
+ */
+declare function useIndexedDB<T>(key: string, defaultValue: T, options?: IndexedDBOptions<T>): StorageSignal<T>;
+/**
+ * Reset the database cache. For testing only.
+ */
+declare function _resetDBCache(): void;
+//#endregion
+//#region src/local.d.ts
+/**
+ * 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
+ * ```
+ */
+declare function useStorage<T>(key: string, defaultValue: T, options?: StorageOptions<T>): StorageSignal<T>;
+//#endregion
+//#region src/session.d.ts
+/**
+ * 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
+ * ```
+ */
+declare function useSessionStorage<T>(key: string, defaultValue: T, options?: StorageOptions<T>): StorageSignal<T>;
+//#endregion
+//#region src/clear.d.ts
+type StorageType = 'local' | 'session' | 'cookie' | 'indexeddb' | 'all';
+/**
+ * Remove a specific key from storage and reset its signal to the default value.
+ *
+ * @example
+ * ```ts
+ * removeStorage('theme')                        // from localStorage
+ * removeStorage('step', { type: 'session' })    // from sessionStorage
+ * removeStorage('locale', { type: 'cookie' })   // deletes cookie
+ * ```
+ */
+declare function removeStorage(key: string, options?: {
+  type?: 'local' | 'session' | 'cookie' | 'indexeddb';
+}): void;
+/**
+ * Clear all managed storage entries for a specific backend, or all backends.
+ *
+ * @example
+ * ```ts
+ * clearStorage()           // clear all localStorage entries managed by @pyreon/storage
+ * clearStorage('session')  // clear all sessionStorage entries
+ * clearStorage('cookie')   // clear all managed cookies
+ * clearStorage('all')      // clear everything
+ * ```
+ */
+declare function clearStorage(type?: StorageType): void;
+//#endregion
+//#region src/registry.d.ts
+/**
+ * Clear all entries from the registry. Used for testing.
+ */
+declare function _resetRegistry(): void;
+//#endregion
+export { type AsyncStorageBackend, type CookieOptions, type IndexedDBOptions, type StorageBackend, type StorageOptions, type StorageSignal, _resetDBCache, _resetRegistry, clearStorage, createStorage, removeStorage, setCookieSource, useCookie, useIndexedDB, useMemoryStorage, useSessionStorage, useStorage };
+//# sourceMappingURL=index2.d.ts.map

package/lib/types/index2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../src/types.ts","../../src/cookie.ts","../../src/custom.ts","../../src/indexed-db.ts","../../src/local.ts","../../src/session.ts","../../src/clear.ts","../../src/registry.ts"],"mappings":";;;;;AAQA;;UAAiB,aAAA,YAAyB,MAAA,CAAO,CAAA;EAAD;EAE9C,MAAA;AAAA;;;;UAQe,cAAA;EAAA;EAEf,UAAA,IAAc,KAAA,EAAO,CAAA;EAFQ;EAI7B,YAAA,IAAgB,GAAA,aAAgB,CAAA;EAAA;EAEhC,OAAA,IAAW,KAAA,EAAO,KAAA,KAAU,CAAA;AAAA;;;;UAQb,aAAA,YAAyB,cAAA,CAAe,CAAA;EAZlC;EAcrB,MAAA;EAZA;EAcA,OAAA,GAAU,IAAA;EAdsB;EAgBhC,IAAA;EAdkB;EAgBlB,MAAA;EAhB4B;EAkB5B,MAAA;EAlB6B;EAoB7B,QAAA;AAAA;;;;UAQe,gBAAA,YAA4B,cAAA,CAAe,CAAA;EApBJ;EAsBtD,MAAA;EAtB6B;EAwB7B,SAAA;EAxBuD;EA0BvD,UAAA;AAAA;;;;UAQe,cAAA;EAtBf;EAwBA,GAAA,CAAI,GAAA;EAxBI;EA0BR,GAAA,CAAI,GAAA,UAAa,KAAA;EAlBc;EAoB/B,MAAA,CAAO,GAAA;AAAA;;;;UAMQ,mBAAA;EAtBf;EAwBA,GAAA,CAAI,GAAA,WAAc,OAAA;EAtBR;EAwBV,GAAA,CAAI,GAAA,UAAa,KAAA,WAAgB,OAAA;EAhBlB;EAkBf,MAAA,CAAO,GAAA,WAAc,OAAA;AAAA;;;;;AA5EvB;;;;;;;;iBCWgB,eAAA,CAAgB,YAAA;;ADDhC;;;;;;;;;;;;;;;iBC8FgB,SAAA,GAAA,CACd,GAAA,UACA,YAAA,EAAc,CAAA,EACd,OAAA,GAAS,aAAA,CAAc,CAAA,IACtB,aAAA,CAAc,CAAA;;;;;AD5GjB;;;;;;;;;;AAUA;;;iBEIgB,aAAA,CACd,OAAA,EAAS,cAAA,EACT,WAAA,gBAEA,GAAA,UACA,YAAA,EAAc,CAAA,EACd,OAAA,GAAU,cAAA,CAAe,CAAA,MACtB,aAAA,CAAc,CAAA;;;;;;;;;;;;cAwFN,gBAAA,MA5FR,GAAA,UACQ,YAAA,EACG,CAAA,EAAC,OAAA,GACL,cAAA,CAAe,CAAA,MACtB,aAAA,CAAc,CAAA;;;;;AFrBnB;;;;;;;;;;AAUA;;iBG0EgB,YAAA,GAAA,CACd,GAAA,UACA,YAAA,EAAc,CAAA,EACd,OAAA,GAAS,gBAAA,CAAiB,CAAA,IACzB,aAAA,CAAc,CAAA;;;;iBA0GD,aAAA,CAAA;;;;AHlMhB;;;;;;;;;;AAUA;iBIuBgB,UAAA,GAAA,CACd,GAAA,UACA,YAAA,EAAc,CAAA,EACd,OAAA,GAAU,cAAA,CAAe,CAAA,IACxB,aAAA,CAAc,CAAA;;;;;AJrCjB;;;;;;;;;;iBKYgB,iBAAA,GAAA,CACd,GAAA,UACA,YAAA,EAAc,CAAA,EACd,OAAA,GAAU,cAAA,CAAe,CAAA,IACxB,aAAA,CAAc,CAAA;;;KCnBZ,WAAA;;;ANGL;;;;;;;;iBMWgB,aAAA,CACd,GAAA,UACA,OAAA;EAAY,IAAA;AAAA;;;;;;;;;;;;iBAiCE,YAAA,CAAa,IAAA,GAAM,WAAA;;;;;;iBCSnB,cAAA,CAAA"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@pyreon/storage",
+  "version": "0.6.0",
+  "description": "Reactive client-side storage for Pyreon — localStorage, sessionStorage, cookies, IndexedDB",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pyreon/fundamentals.git",
+    "directory": "packages/storage"
+  },
+  "homepage": "https://github.com/pyreon/fundamentals/tree/main/packages/storage#readme",
+  "bugs": {
+    "url": "https://github.com/pyreon/fundamentals/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./lib/index.js",
+      "types": "./lib/types/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "vl_rolldown_build",
+    "dev": "vl_rolldown_build-watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@pyreon/reactivity": ">=0.5.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.8.3",
+    "@pyreon/reactivity": ">=0.5.0 <1.0.0",
+    "@vitus-labs/tools-lint": "^1.11.0"
+  }
+}

package/src/clear.ts

@@ -0,0 +1,72 @@
+import { getEntriesByBackend, getEntry, removeEntry } from './registry'
+import { getWebStorage, isBrowser } from './utils'
+
+// ─── Storage type mapping ────────────────────────────────────────────────────
+
+type StorageType = 'local' | 'session' | 'cookie' | 'indexeddb' | 'all'
+
+// ─── removeStorage ───────────────────────────────────────────────────────────
+
+/**
+ * Remove a specific key from storage and reset its signal to the default value.
+ *
+ * @example
+ * ```ts
+ * removeStorage('theme')                        // from localStorage
+ * removeStorage('step', { type: 'session' })    // from sessionStorage
+ * removeStorage('locale', { type: 'cookie' })   // deletes cookie
+ * ```
+ */
+export function removeStorage(
+  key: string,
+  options?: { type?: 'local' | 'session' | 'cookie' | 'indexeddb' },
+): void {
+  const type = options?.type ?? 'local'
+  const entry = getEntry(type, key)
+
+  if (entry) {
+    entry.signal.remove()
+  } else {
+    // No signal registered — still try to clear the raw storage
+    if (type === 'local' || type === 'session') {
+      const storage = getWebStorage(type)
+      if (storage) storage.removeItem(key)
+    } else if (type === 'cookie' && isBrowser()) {
+      // biome-ignore lint/suspicious/noDocumentCookie: standard cookie deletion API
+      document.cookie = `${encodeURIComponent(key)}=; max-age=0; path=/`
+    }
+    removeEntry(type, key)
+  }
+}
+
+// ─── clearStorage ────────────────────────────────────────────────────────────
+
+/**
+ * Clear all managed storage entries for a specific backend, or all backends.
+ *
+ * @example
+ * ```ts
+ * clearStorage()           // clear all localStorage entries managed by @pyreon/storage
+ * clearStorage('session')  // clear all sessionStorage entries
+ * clearStorage('cookie')   // clear all managed cookies
+ * clearStorage('all')      // clear everything
+ * ```
+ */
+export function clearStorage(type: StorageType = 'local'): void {
+  if (type === 'all') {
+    clearBackend('local')
+    clearBackend('session')
+    clearBackend('cookie')
+    clearBackend('indexeddb')
+    return
+  }
+
+  clearBackend(type)
+}
+
+function clearBackend(type: string): void {
+  const entries = getEntriesByBackend(type)
+  for (const entry of entries) {
+    entry.signal.remove()
+  }
+}

package/src/cookie.ts

@@ -0,0 +1,165 @@
+import { signal } from '@pyreon/reactivity'
+import { getEntry, removeEntry, setEntry } from './registry'
+import type { CookieOptions, StorageSignal } from './types'
+import { deserialize, isBrowser, serialize } from './utils'
+
+// ─── Server-side cookie source ───────────────────────────────────────────────
+
+let serverCookieString = ''
+
+/**
+ * Set the cookie source string for SSR. Call this once per request
+ * with the raw Cookie header value.
+ *
+ * @example
+ * ```ts
+ * // In your SSR request handler
+ * setCookieSource(request.headers.get('cookie') ?? '')
+ * ```
+ */
+export function setCookieSource(cookieHeader: string): void {
+  serverCookieString = cookieHeader
+}
+
+// ─── Cookie parsing ──────────────────────────────────────────────────────────
+
+function parseCookies(cookieString: string): Map<string, string> {
+  const cookies = new Map<string, string>()
+  if (!cookieString) return cookies
+
+  for (const pair of cookieString.split(';')) {
+    const eqIndex = pair.indexOf('=')
+    if (eqIndex === -1) continue
+    const name = pair.slice(0, eqIndex).trim()
+    const value = pair.slice(eqIndex + 1).trim()
+    if (name) cookies.set(name, decodeURIComponent(value))
+  }
+
+  return cookies
+}
+
+function getCookieString(): string {
+  if (isBrowser()) return document.cookie
+  return serverCookieString
+}
+
+function readCookie(key: string): string | null {
+  const cookies = parseCookies(getCookieString())
+  return cookies.get(key) ?? null
+}
+
+// ─── Cookie writing ──────────────────────────────────────────────────────────
+
+function writeCookie<T>(
+  key: string,
+  value: T,
+  options: CookieOptions<T>,
+): void {
+  if (!isBrowser()) return
+
+  const serialized = serialize(value, options.serializer)
+  let cookie = `${encodeURIComponent(key)}=${encodeURIComponent(serialized)}`
+
+  if (options.maxAge !== undefined) {
+    cookie += `; max-age=${options.maxAge}`
+  }
+  if (options.expires) {
+    cookie += `; expires=${options.expires.toUTCString()}`
+  }
+  cookie += `; path=${options.path ?? '/'}`
+  if (options.domain) {
+    cookie += `; domain=${options.domain}`
+  }
+  if (options.secure) {
+    cookie += '; secure'
+  }
+  cookie += `; samesite=${options.sameSite ?? 'lax'}`
+
+  // biome-ignore lint/suspicious/noDocumentCookie: document.cookie is the standard cookie write API
+  document.cookie = cookie
+}
+
+function deleteCookie<T>(key: string, options: CookieOptions<T>): void {
+  if (!isBrowser()) return
+
+  let cookie = `${encodeURIComponent(key)}=; max-age=0`
+  cookie += `; path=${options.path ?? '/'}`
+  if (options.domain) {
+    cookie += `; domain=${options.domain}`
+  }
+
+  // biome-ignore lint/suspicious/noDocumentCookie: document.cookie is the standard cookie write API
+  document.cookie = cookie
+}
+
+// ─── useCookie ───────────────────────────────────────────────────────────────
+
+/**
+ * Reactive signal backed by a browser cookie. SSR-compatible when
+ * used with setCookieSource().
+ *
+ * @example
+ * ```ts
+ * const locale = useCookie('locale', 'en', {
+ *   maxAge: 60 * 60 * 24 * 365, // 1 year
+ *   path: '/',
+ *   sameSite: 'lax',
+ * })
+ * locale()          // 'en'
+ * locale.set('de')  // sets cookie + updates signal
+ * locale.remove()   // deletes cookie, resets to default
+ * ```
+ */
+export function useCookie<T>(
+  key: string,
+  defaultValue: T,
+  options: CookieOptions<T> = {},
+): StorageSignal<T> {
+  // Return existing signal if already registered
+  const existing = getEntry<T>('cookie', key)
+  if (existing) return existing.signal
+
+  // Read initial value from cookie
+  const raw = readCookie(key)
+  const initialValue =
+    raw !== null
+      ? deserialize(raw, defaultValue, options.deserializer, options.onError)
+      : defaultValue
+
+  const sig = signal<T>(initialValue)
+
+  // 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)
+    writeCookie(key, value, options)
+  }
+
+  storageSig.update = (fn: (current: T) => T) => {
+    const newValue = fn(sig.peek())
+    storageSig.set(newValue)
+  }
+
+  storageSig.remove = () => {
+    sig.set(defaultValue)
+    deleteCookie(key, options)
+    removeEntry('cookie', key)
+  }
+
+  setEntry('cookie', key, storageSig, defaultValue)
+
+  return storageSig
+}

package/src/custom.ts

@@ -0,0 +1,128 @@
+import { signal } from '@pyreon/reactivity'
+import { getEntry, removeEntry, setEntry } from './registry'
+import type { StorageBackend, StorageOptions, StorageSignal } from './types'
+import { deserialize, serialize } from './utils'
+
+// ─── createStorage ───────────────────────────────────────────────────────────
+
+/**
+ * Create a custom storage hook backed by any synchronous storage backend.
+ * Useful for encrypted storage, in-memory storage, or custom adapters.
+ *
+ * @example
+ * ```ts
+ * const useEncrypted = createStorage({
+ *   get: (key) => decrypt(localStorage.getItem(key)),
+ *   set: (key, value) => localStorage.setItem(key, encrypt(value)),
+ *   remove: (key) => localStorage.removeItem(key),
+ * })
+ *
+ * const secret = useEncrypted('api-key', '')
+ * ```
+ */
+export function createStorage(
+  backend: StorageBackend,
+  backendName?: string,
+): <T>(
+  key: string,
+  defaultValue: T,
+  options?: StorageOptions<T>,
+) => StorageSignal<T> {
+  const name = backendName ?? 'custom'
+
+  return function useCustomStorage<T>(
+    key: string,
+    defaultValue: T,
+    options?: StorageOptions<T>,
+  ): StorageSignal<T> {
+    // Return existing signal if already registered
+    const existing = getEntry<T>(name, key)
+    if (existing) return existing.signal
+
+    // Read initial value
+    let initialValue = defaultValue
+    try {
+      const raw = backend.get(key)
+      if (raw !== null) {
+        initialValue = deserialize(
+          raw,
+          defaultValue,
+          options?.deserializer,
+          options?.onError,
+        )
+      }
+    } catch {
+      // Backend read failed — use default
+    }
+
+    const sig = signal<T>(initialValue)
+
+    // 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)
+      try {
+        backend.set(key, serialize(value, options?.serializer))
+      } catch {
+        // Write failed — signal still updates
+      }
+    }
+
+    storageSig.update = (fn: (current: T) => T) => {
+      const newValue = fn(sig.peek())
+      storageSig.set(newValue)
+    }
+
+    storageSig.remove = () => {
+      sig.set(defaultValue)
+      try {
+        backend.remove(key)
+      } catch {
+        // Remove failed
+      }
+      removeEntry(name, key)
+    }
+
+    setEntry(name, key, storageSig, defaultValue)
+
+    return storageSig
+  }
+}
+
+// ─── Memory storage ──────────────────────────────────────────────────────────
+
+/**
+ * In-memory storage backend. Useful for SSR, testing, or ephemeral state.
+ * Values are lost on page unload.
+ *
+ * @example
+ * ```ts
+ * import { useMemoryStorage } from '@pyreon/storage'
+ *
+ * const temp = useMemoryStorage('key', 'default')
+ * ```
+ */
+export const useMemoryStorage = createStorage(
+  (() => {
+    const store = new Map<string, string>()
+    return {
+      get: (key: string) => store.get(key) ?? null,
+      set: (key: string, value: string) => store.set(key, value),
+      remove: (key: string) => store.delete(key),
+    }
+  })(),
+  'memory',
+)

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @pyreon/storage — Reactive client-side storage for Pyreon.
+ *
+ * Signal-backed persistence across localStorage, sessionStorage, cookies,
+ * IndexedDB, and custom backends. Every stored value is a reactive signal
+ * that persists writes automatically.
+ *
+ * @example
+ * ```ts
+ * import { useStorage, useCookie, useIndexedDB } from '@pyreon/storage'
+ *
+ * // localStorage — persistent, cross-tab synced
+ * const theme = useStorage('theme', 'light')
+ * theme()            // read reactively
+ * theme.set('dark')  // updates signal + localStorage
+ *
+ * // Cookie — SSR-readable, configurable expiry
+ * const locale = useCookie('locale', 'en', { maxAge: 365 * 86400 })
+ *
+ * // IndexedDB — large data, debounced writes
+ * const draft = useIndexedDB('article-draft', { title: '', body: '' })
+ * ```
+ */
+
+// ─── Hooks ───────────────────────────────────────────────────────────────────
+
+export { setCookieSource, useCookie } from './cookie'
+export { createStorage, useMemoryStorage } from './custom'
+export { useIndexedDB } from './indexed-db'
+export { useStorage } from './local'
+export { useSessionStorage } from './session'
+
+// ─── Utilities ───────────────────────────────────────────────────────────────
+
+export { clearStorage, removeStorage } from './clear'
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type {
+  AsyncStorageBackend,
+  CookieOptions,
+  IndexedDBOptions,
+  StorageBackend,
+  StorageOptions,
+  StorageSignal,
+} from './types'
+
+// ─── Testing ─────────────────────────────────────────────────────────────────
+
+export { _resetDBCache } from './indexed-db'
+export { _resetRegistry } from './registry'