Skip to main content

How-to guides

Long-form walkthroughs grounded in real problem-solving with pond-ts. Each guide is built around a working reference implementation — agents and contributors who hit friction in specific shapes have written up their experiences for future readers.

Available:

  • Building a dashboard — adapted from the dashboard agent's reference repo. React + LiveSeries ingest, throttled snapshot reading, per-host rolling baselines, anomaly detection, and chart-library bridging — built around a ~600-line working dashboard.

  • Ingesting messy data — adapted from a CSV-cleaner agent run on a real-world per-host metrics dump (mixed timestamp formats, four spellings of "missing," duplicate-retry rows, multi-host interleaving, gap-from-missed- scrapes). Walks through schema declaration, boundary normalization, dedupe, partitionBy for per-entity scope, gap- capped fill, and optional regularization with materialize.

  • Histograms — stacked bars, value / ordinal band axes, and horizontal orientation with @pond-ts/charts, where the buckets come from pond's own aggregation (aggregate / byColumn / partitionBy). Four worked examples: incidents-by-host, risk bands, heart-rate zones, and a power distribution.

  • Categorical charts (the transpose view) — categories on the x-axis (ticker / account / zone) as the transpose of the time chart: read one row of a wide series across into a bar per column, via pivotByGroup → transposeRow → <BarChart categories>. Covers the band scale, stable per-column selection, and the high-cardinality label policy.

  • Rendering large time series — drawing millions of points without the pan-and-zoom cliff: how the built-in decimator (viewport culling + M4 min/max/first/last) makes the draw cost flat in the point count, what the machine-recorded bench numbers actually say, per-layer aggregates (line / area / band / candle / box), and the honest ceilings — the three-at-1M render floor and the data-side ceiling that hits first for live streams.

  • From a CSV to a banded chart — an air-quality export (US EPA PM2.5 AQI, two sensors, three days) taken from raw file to finished chart: telling measurements from chart furniture, the BOM / timezone / blank-is-not-zero parsing traps, verifying a parse against a number the file already claims, and then <Zone> — the y-span band that turns a value axis into a scale you can read a verdict off. Generalises to heart-rate zones, SLO bands, and control-chart spec limits.

  • A streaming aggregator, in TypeScript and Rust — adapted from the gRPC experiment: a gRPC firehose of per-host metrics into one LiveSeries, per-host 1-minute baselines and 200 ms slices on a shared clock trigger, and frames out to a browser dashboard. Built twice, on pond-ts and on pond-rs, with a side-by-side check that both give the same rows, bounded producer queues, and a race of the two (and the latency measuring mistake it caught).

  • A live chart at 120 fps, off the main thread — built from the offscreen-stream spike: a market feed drawn in a Web Worker on an OffscreenCanvas, with the WebSocket on a second worker, ticks kept in a LiveSeries through pushSeries, and one bucket per pixel column so a frame costs the same at 10 thousand points or 30 million. Covers hover across threads, resizing, what the spike measured on a 120 Hz screen, and when LineChart is the better choice.

For shorter, primitive-focused docs, see the pond-ts core reference and @pond-ts/react reference.