nexa-persistence API Reference

The nexa-persistence package enables seamless state synchronization between Nexa reactivity signals and client-side storage mechanisms (LocalStorage, SessionStorage, IndexedDB) with type safety and memory leak prevention.

persistSignal

Wraps an existing Nexa Signal to automatically synchronize its updates to a persistent storage backend and hydrate its state on initialization.

Signature

export interface PersistenceOptions<T> {
  storage?: Storage
  serialize?: (value: T) => string
  deserialize?: (value: string) => T
}

export function persistSignal<T>(
  signal: Signal<T>,
  key: string,
  options?: PersistenceOptions<T>
): Signal<T> & { dispose: () => void }

Options

• storage: The storage provider implementing the Web Storage API (defaults to window.localStorage).
• serialize: Custom serialization function for complex data structures (defaults to JSON.stringify).
• deserialize: Custom deserialization function with error recovery (defaults to JSON.parse).

Return Value

Returns the exact same Signal instance with an added .dispose() method. Calling .dispose() cleanly removes the reactive synchronization effect, preventing memory leaks.

Usage Example

import { signal } from 'nexa-reactivity'
import { persistSignal } from 'nexa-persistence'

const theme = signal('light')
const persistedTheme = persistSignal(theme, 'app-theme')

// Automatically updates localStorage
theme.value = 'dark'

// Clean up effect when component or context is destroyed
theme.dispose()