Ripple-Reactive
API Reference

subscribe()

Simple value change listener. Like a stripped-down watch for when you just need a callback.

Subscribes a listener callback to value changes on a specific signal or computed value. It runs immediately upon creation with the current value, and re-executes whenever the value changes.

function subscribe<T>(
  source: Signal<T> | ReadonlySignal<T>,
  callback: (value: T) => void
): () => void;

Parameters

ParameterTypeDescription
sourceSignal<T> | ReadonlySignal<T>The signal or computed value to listen to.
callback(value: T) => voidInvoked immediately with the current value and whenever the value changes.

Returns

Returns an unsubscribe function (() => void). Calling this function cancels the subscription and stops further callback invocations.

Usage

Basic Subscription

subscribe() is ideal when you want to bridge a reactive signal to an external service or logging mechanism:

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

// Mock analytics tracker
const analytics = {
  track: (event: string, data: Record<string, unknown>) => {
    console.log(`[Analytics] ${event}`, data);
  },
};

const count = signal(0);

// Subscribes immediately (logs: { value: 0 })
const unsubscribe = subscribe(count, (value) => {
  analytics.track('count_changed', { value });
});

count.value = 5; // Analytics fires: { value: 5 }
count.value = 10; // Analytics fires: { value: 10 }

unsubscribe(); // Stop listening

count.value = 15; // No analytics event fired

Bridging to Non-Reactive External APIs

A common real-world use case is synchronizing reactive state with external browser APIs like localStorage, document.title, or WebSockets:

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

const activeTheme = signal<'light' | 'dark'>('dark');

// Synchronize root HTML class whenever the theme signal updates
const unbindTheme = subscribe(activeTheme, (theme) => {
  document.documentElement.classList.remove('light', 'dark');
  document.documentElement.classList.add(theme);
  localStorage.setItem('app-theme', theme);
});

// Switch themes
activeTheme.value = 'light';

// Clean up when no longer needed (e.g. during page unload or module teardown)
unbindTheme();

When to Use: subscribe() vs watch() vs effect()

Ripple.js provides three distinct ways to react to state changes. Choosing the right one depends on whether you are tracking a single signal, explicit multiple sources, or general reactive expressions:

Featuresubscribe()watch()effect()
Source TargetSingle Signal<T> or ReadonlySignal<T>Explicit getter function () => TImplicit (all signals read inside)
Callback Arguments(value: T)(newValue: T, oldValue: T | undefined)(onCleanup)
Initial RunImmediate (synchronous)Lazy by default (immediate with { immediate: true })Immediate (synchronous)
Callback TrackingUntracked (only subscribes to source)Untracked (only subscribes to source)Auto-tracks every signal accessed
Primary Use CaseExternal callbacks, analytics, simple 1:1 listenersOld/new comparisons, conditional side-effects, lazy watchersState synchronization, DOM updates, multi-dependency flows
import { signal, subscribe } from 'ripple-reactive';

const user = signal('Alice');

// Simple 1-to-1 callback with current value
const unsub = subscribe(user, (name) => {
  console.log(`User is now: ${name}`);
});

Immediate Execution: subscribe() runs its callback immediately upon creation with the current value. If you need lazy observation that only executes on future changes, use watch() instead.

Always retain the returned unsubscribe function and call it when the listener is no longer required (such as when tearing down components or web workers) to prevent memory leaks.

On this page