Ripple-Reactive

State Management

Built-in utilities for complex state, undo/redo history, and persistence.

While fine-grained signals are perfect for isolated values, applications often require structured state, time-travel debugging, and local storage persistence. Ripple.js provides these as zero-dependency utility functions.

Reactive Stores

A createStore defines a Zustand/Pinia-style store with typed state, derived getters, and actions — all backed by signals under the hood.

import { createStore, effect } from 'ripple-reactive';

const counter = createStore({
  state: { count: 0, name: 'Aditya' },
  getters: {
    double: (state) => state.count.value * 2,
    greeting: (state) => `Hello, ${state.name.value}!`,
  },
  actions: {
    increment: (state) => state.count.value++,
    add: (state, amount: number) => state.count.value += amount,
    setName: (state, name: string) => state.name.value = name,
  },
});

// Use actions directly
counter.increment();
counter.add(10);

// Read getters (they're computed signals)
effect(() => {
  console.log(counter.double.value); // 22
  console.log(counter.greeting.value); // "Hello, Aditya!"
});

// Reset to initial state
counter.$reset();

Each property in state becomes an individual signal. Getters become computed values. Actions receive the state object and any extra arguments you pass.

Time-Travel (Undo/Redo)

Ripple.js includes a built-in createHistory wrapper that attaches a time-travel timeline to any signal. This is exceptionally useful for canvas editors, rich text interfaces, or complex forms.

import { signal, createHistory } from 'ripple-reactive';

const documentText = signal('');
const history = createHistory(documentText, { limit: 50 });

// User types
documentText.value = 'Hello';
documentText.value = 'Hello World';

console.log(documentText.value); // 'Hello World'

history.undo();
console.log(documentText.value); // 'Hello'

history.redo();
console.log(documentText.value); // 'Hello World'

// Check capabilities
console.log(history.canUndo); // true
console.log(history.canRedo); // false

Persistence

The persistedSignal utility creates a signal that automatically syncs with the browser's localStorage. It handles JSON serialization and deserialization automatically.

import { persistedSignal } from 'ripple-reactive';

// Initializes with the value from localStorage if it exists,
// otherwise defaults to 'dark'.
const theme = persistedSignal('ripple-app-theme', 'dark');

// Automatically saved to localStorage
theme.value = 'light';

// Survives page refreshes!
// Also syncs across browser tabs via the 'storage' event.

persistedSignal requires a browser environment with localStorage. It will fall back to the default value in Node.js or SSR contexts.

Combining Utilities

Because Ripple.js utilities are highly composable, you can combine persistence with history to create undo-able state that survives page reloads.

import { persistedSignal, createHistory } from 'ripple-reactive';

const settings = persistedSignal('app-settings', { volume: 50, brightness: 80 });
const settingsHistory = createHistory(settings);

// Change, undo, and it's all saved to localStorage automatically
settings.value = { volume: 75, brightness: 80 };
settingsHistory.undo(); // back to { volume: 50, brightness: 80 }

On this page