@sylphx/zen-persistent

Persistent storage integration for Zen state manager. Automatically syncs state with localStorage or sessionStorage, with cross-tab synchronization support.

Installation

npm install @sylphx/zen-persistent
# or
bun add @sylphx/zen-persistent

Usage

Basic Example

import { persistentZen } from '@sylphx/zen-persistent';

// Create a persistent zen that syncs with localStorage
const theme = persistentZen('theme', 'light');

// Changes are automatically saved to localStorage
set(theme, 'dark');

// Value persists across page reloads and browser tabs

Persistent Map

import { persistentMap } from '@sylphx/zen-persistent';

const userPreferences = persistentMap('prefs', {
  fontSize: 14,
  language: 'en',
  notifications: true,
});

// Changes sync automatically
setKey(userPreferences, 'fontSize', 16);

Custom Storage

import { persistentZen } from '@sylphx/zen-persistent';

// Use sessionStorage instead of localStorage
const sessionData = persistentZen('session', { userId: null }, {
  storage: sessionStorage,
  listen: false, // Disable cross-tab sync
});

Custom Serialization

import { persistentZen } from '@sylphx/zen-persistent';

const dateStore = persistentZen('lastVisit', new Date(), {
  serializer: {
    encode: (date) => date.toISOString(),
    decode: (str) => new Date(str),
  },
});

API

`persistentZen<Value>(key, initialValue, options?)`

Creates a persistent zen that syncs with storage.

Parameters:

key: Unique storage key
initialValue: Default value if nothing in storage
options:
- storage: Storage engine (default: localStorage)
- serializer: Custom serializer (default: JSON)
- listen: Enable cross-tab sync (default: true)

`persistentMap<Value>(key, initialValue, options?)`

Creates a persistent map that syncs with storage.

Same parameters as persistentZen.

Features

✅ Automatic persistence to localStorage/sessionStorage
✅ Cross-tab synchronization
✅ Custom serialization support
✅ SSR-safe (gracefully handles non-browser environments)
✅ TypeScript support

License

MIT

3.41.0 - 2025-11-17

Fixed

Reverted v3.40.0 loop unrolling optimization that caused 22% regression in Computed Value Access

Reverted batch threshold lowering (100→10) that hurt medium fanouts

Reverted dual state extraction that added overhead to hot path

Added

Optimized Computation.read() for untracked reads (no currentObserver)

Fast path that avoids tracking logic when reading outside reactive context

Targets Extreme Read benchmark (10000x untracked reads): 64K→150K+ ops/sec

Performance

Expected to recover Single Read to 21.5M ops/sec (from v3.38.0 baseline)

Expected to recover Computed Value Access to 17.2M ops/sec

Expected Hybrid Weighted score: 50.0→57.6/100 (reverting regression)

Detalhes do pacote