@pond-ts/react

Thin, render-safe React hooks over the pond-ts live primitives. Dashboard-sized state out of the box: WebSocket ingest, throttled rendering, per-field reference stability, automatic subscription cleanup.

Install — npm install pond-ts @pond-ts/react. Peer-depends on React 18 or 19.

import { useEffect } from 'react';
import { useLiveSeries, useCurrent } from '@pond-ts/react';

const schema = [
  { name: 'time', kind: 'time' },
  { name: 'cpu', kind: 'number' },
] as const;

function Dashboard() {
  const [live, snap] = useLiveSeries({
    name: 'metrics',
    schema,
    retention: { maxAge: '10m' },
  });

  // The thing you came here for: pipe events from a WebSocket (or any
  // push-style source) into the LiveSeries. Hooks below re-render as
  // pushes arrive, throttled.
  useEffect(() => {
    const ws = new WebSocket('/api/metrics');
    ws.onmessage = (e) => {
      const { ts, cpu } = JSON.parse(e.data);
      live.push([ts, cpu]);
    };
    return () => ws.close();
  }, [live]);

  const { cpu } = useCurrent(live, { cpu: 'avg' });

  return (
    <>
      <Stat label="Avg CPU" value={cpu} />
      {snap && <Chart points={snap.select('cpu').toPoints()} />}
    </>
  );
}

Where to start

• Concepts — the three-group mental model (source / snapshot / reducer), subscription lifecycle, throttling, reference stability.
• Hooks — reference for all eight hooks with signatures and worked examples.
• Patterns — end-to-end dashboard composition, throttling strategy, retention, testing, SSR.
• API reference — the generated full-width reference, every signature and type.

For a longer-form walkthrough, see Building a dashboard in the How-to guides section.

The hook surface at a glance

Purpose	Hook
Parse JSON → typed TimeSeries	useTimeSeries
Own a LiveSeries in a component	useLiveSeries
Live source → batch TimeSeries	useSnapshot
Prop-dependent view + snapshot	useLiveQuery
Pure transform, memoized	useDerived
Windowed view with auto-dispose	useWindow
Current scalars for stat cards	useCurrent
Latest single event	useLatest

Pandas has nothing analogous — React state management for time series is a different problem than in-memory data analysis. pondjs users: the subscribe + rerender plumbing you wrote by hand around Pond is what these hooks replace; the library never shipped React bindings.