@sthirajs/persist

Persistence plugin for Sthira with IndexedDB, localStorage, and memory adapters.

Installation

pnpm add @sthirajs/persist

Quick Start

import { createStore } from '@sthirajs/core';
import { createPersistPlugin } from '@sthirajs/persist';

const store = createStore({
  name: 'settings',
  state: { theme: 'dark', language: 'en' },
  plugins: [
    createPersistPlugin({
      key: 'app-settings',
      storage: 'indexeddb', // 'localstorage' | 'memory'
    }),
  ],
});

// Access persist API
await store.persist.hydrate();
store.persist.getStatus(); // { hydrated: true, persisting: false }

Plugin API

interface PersistPluginConfig {
  key: string; // Storage key
  storage: 'indexeddb' | 'localstorage' | 'memory';
  debounce?: number; // Write debounce (ms)
  version?: number; // Schema version
  migrate?: (state, version) => state;
  partialize?: (state) => Partial<state>;
}

// API exposed on store.persist
interface PersistApi {
  hydrate: () => Promise<void>; // Load from storage
  persist: () => Promise<void>; // Manual save
  clear: () => Promise<void>; // Clear storage
  pause: () => void; // Pause auto-persist
  resume: () => void; // Resume auto-persist
  getStatus: () => { hydrated; persisting; lastPersistedAt };
}

Storage Adapters

IndexedDB (Recommended)

import { createIndexedDBAdapter } from '@sthirajs/persist';

const adapter = createIndexedDBAdapter({
  dbName: 'my-app',
  storeName: 'state',
});

createPersistPlugin({ key: 'my-store', adapter });

localStorage

import { createLocalStorageAdapter } from '@sthirajs/persist';

const adapter = createLocalStorageAdapter({ prefix: 'app_' });

Memory (Testing)

import { createMemoryAdapter } from '@sthirajs/persist';

const adapter = createMemoryAdapter();

Migrations

createPersistPlugin({
  key: 'settings',
  storage: 'indexeddb',
  version: 2,
  migrate: (state, version) => {
    if (version === 1) {
      return { ...state, newField: 'default' };
    }
    return state;
  },
});

Partialize

Persist only specific fields:

createPersistPlugin({
  key: 'user',
  storage: 'localstorage',
  partialize: (state) => ({
    preferences: state.preferences, // Persist
    // token: state.token, // Don't persist
  }),
});

Wait for Hydration

import { waitForHydration } from '@sthirajs/persist'

function App() {
  const [ready, setReady] = useState(false)

  useEffect(() => {
    waitForHydration(store.persist).then(() => setReady(true))
  }, [])

  if (!ready) return <Loading />
  return <Main />
}

License

MIT