@pond-ts/react 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -7,10 +7,187 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 file covers both packages. Pre-1.0: minor bumps may include new features and
 type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.17.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.18.0...HEAD
+[0.18.0]: https://github.com/pjm17971/pond-ts/compare/v0.17.1...v0.18.0
 
 ## [Unreleased]
 
+## [0.18.0] — 2026-05-30
+
+This release graduates the **Phase 4.7 columnar substrate** from
+framework-internal (shipped piecemeal to `main` since v0.17.1) to a
+user-visible **public column API**, plus a column-native live buffer that
+fixes a high-partition-count OOM. Everything is additive except one
+documented breaking change (interval label kinds) and one documented
+behavior change (chunked-backed `pushMany` commit semantics). Pre-1.0: the
+column API is expected to keep moving toward its eventual shape.
+
+### Added
+
+- **Public column API (Phase 4.7 step 8).** A column-centric extraction
+  surface on `TimeSeries`, for high-throughput and charting consumers that
+  want typed-array access instead of per-`Event` iteration. Additive — every
+  existing row / `Event` API is unchanged.
+  - `series.column(name)` returns a schema-narrowed typed column view, with
+    public re-exports of the `Float64Column` / `BooleanColumn` /
+    `StringColumn` / `KeyColumn` (time / timeRange / interval) variants
+    ([#154](https://github.com/pjm17971/pond-ts/pull/154),
+    [#155](https://github.com/pjm17971/pond-ts/pull/155)).
+  - `Float64Column`: scalar reductions (`min` / `max` / `sum` / `mean` /
+    `count` / …) and `scan`
+    ([#155](https://github.com/pjm17971/pond-ts/pull/155)); `bin(...)` for
+    histogram / downsample bucketing
+    ([#156](https://github.com/pjm17971/pond-ts/pull/156)); and
+    `toFloat64Array()` for a storage-agnostic gather into a dense array
+    ([#165](https://github.com/pjm17971/pond-ts/pull/165)).
+  - `KeyColumn.at(i)` and `.slice(start, end)`
+    ([#159](https://github.com/pjm17971/pond-ts/pull/159)).
+- **Columnar substrate (Phase 4.7 step 1, framework layer).** All
+  eight sub-steps (1a–1h) shipped to main as PRs #132 / #133 /
+  #134 / #135 / #136 / #147 / #148 / #149. See `PLAN.md` and
+  [`packages/core/src/columnar/README.md`](packages/core/src/columnar/README.md)
+  for the full inventory. Framework-internal — surfaced behind the existing
+  `TimeSeries` API at step 2 (below) and the public column API at step 8
+  (above).
+
+### Changed
+
+- **Chunked columnar live backing for strict time-keyed `LiveSeries`**
+  ([#170](https://github.com/pjm17971/pond-ts/pull/170)). A top-level
+  `LiveSeries` with `ordering: 'strict'` and a time key now backs its
+  retained window with batch-granular columnar chunks instead of an
+  `Event[]` window — each `pushMany` validates straight into typed columns,
+  retaining **zero `Event` objects** (~4.7× less retained heap in-pond; the
+  high-partition-count OOM fix). Two consequences:
+  - **`pushMany` commit semantics** on the chunked path: the batch is
+    appended atomically _before_ any `'event'` fires, so a listener observes
+    the full post-batch `length` (not a row-by-row `1, 2, 3`), and a listener
+    that throws mid-batch leaves the whole batch committed. The per-row
+    `Event[]` backing (`reorder` / `drop` / interval-keyed /
+    internally-created series) keeps per-row commit. Listener _values_ and
+    `event → batch → evict` ordering are unchanged.
+  - **`LiveReduce` eviction** resolves by event identity (primary) with a
+    FIFO-frontier fallback for the chunked backing's materialized evictions —
+    correct for both `reorder` and the chunked backing. `min` / `max` /
+    `first` / `last` / `samples` over a `reorder` source **with retention**
+    remain a documented limitation (see `LiveReduce` JSDoc and PLAN
+    "Deferred") — pre-existing, not introduced here.
+- **Internal, behavior-preserving performance work.** Column-native intake
+  bypasses per-row `Event` allocation at `TimeSeries` construction
+  ([#151](https://github.com/pjm17971/pond-ts/pull/151)); numeric reducers
+  (`min` / `max` / `sum` / `avg` / …) compute over typed-array columns where
+  available, with NaN parity preserved
+  ([#153](https://github.com/pjm17971/pond-ts/pull/153)); the live storage
+  strategy was extracted behind an internal interface
+  ([#168](https://github.com/pjm17971/pond-ts/pull/168)).
+
+### Changed (BREAKING)
+
+- **Interval-keyed series must use one label type throughout**
+  ([#150](https://github.com/pjm17971/pond-ts/pull/150)). Pre-2a,
+  TimeSeries silently tolerated mixed-kind interval labels —
+  rows with `value: 'row-1'` (string) and `value: 2` (number) could
+  coexist in a single series because events were stored as a raw
+  array with no per-column type alignment. The columnar substrate
+  introduced at Phase 4.7 enforces one label kind per column via
+  `IntervalKeyColumn`, so mixed-kind labels now throw at series
+  construction with a row-pointed error message.
+  - **Affected:** Any series built via `new TimeSeries(...)`,
+    `TimeSeries.fromJSON(...)`, `TimeSeries.fromEvents(...)`, or
+    any transform that produces interval-keyed events, where the
+    `value` field of `IntervalInput` rows or `Interval` keys
+    mixes `string` and `number` types.
+  - **Migration:** Choose one label kind for the whole series.
+    Numeric labels can be stringified at intake (`String(label)`)
+    if the downstream consumer accepts string equality; string
+    labels parseable as integers can be converted to numbers at
+    intake. The error message names the first offending row so
+    the offending data is easy to find.
+  - **Rationale:** Aligns the row-API contract with the columnar
+    substrate's per-column kind discipline (matching Polars /
+    Arrow / Parquet). The previous behavior produced type-broken
+    events that worked only because TimeSeries didn't enforce
+    per-column alignment; downstream columnar operators (the
+    upcoming reducer adaptation in steps 3+) require it.
+  - **Affected types:** `IntervalValue` remains `string | number`
+    per the `Interval` class contract. The runtime restriction
+    is at the **series** level (all intervals within one series
+    must share a kind), not the per-interval level. Type-level
+    narrowing of `IntervalKeyedSchema<S>` over label kind is a
+    follow-up deferred to a later sub-step.
+
+## [0.17.1] — 2026-05-11
+
+Bug fix: `live.partitionBy()` now default-inherits `ordering`,
+`graceWindow`, and `retention` from the source `LiveSeries`. Surfaced
+by the gRPC experiment's
+[M4 late-data friction note](https://github.com/pjm17971/pond-grpc-experiment/blob/main/friction-notes/M4.md),
+which measured `99.5%` of late events crashing the partition router
+under `source = LiveSeries({ ordering: 'reorder', graceWindow })`
+followed by bare `partitionBy('host')`.
+
+### Fixed
+
+- **`LiveSeries.partitionBy(by)` default-inherits source config**
+  ([#TBD](https://github.com/pjm17971/pond-ts/pull/TBD)). Pre-fix,
+  per-partition sub-series were constructed with default
+  `ordering: 'strict'` regardless of source mode. Under a `'reorder'`
+  source, late events that the source accepted via its reorder path
+  were routed into the partition's `#insert` and threw with a
+  strict-mode error; the throw propagated back through the source's
+  listener fan-out into `live.push()`.
+
+  Post-fix, `partitionBy(by)` defaults each per-partition sub-series'
+  `ordering`, `graceWindow`, and `retention` to the source's values.
+  Explicit options on `partitionBy(by, { ordering, ... })` override
+  per-field. `graceWindow` inheritance is gated on effective ordering
+  being `'reorder'` (LiveSeries rejects strict + graceWindow combos).
+
+  ```ts
+  // Pre-0.17.1: crashed the partition router
+  const live = new LiveSeries({
+    name: 'metrics',
+    schema,
+    ordering: 'reorder',
+    graceWindow: '30s',
+  });
+  live.partitionBy('host'); // ← partition was strict regardless
+
+  // Post-0.17.1: partitions inherit reorder + 30s grace; late events
+  // accept correctly via the reorder path.
+  ```
+
+  Existing callers with explicit `partitionBy(by, { ordering, ... })`:
+  unchanged. Existing callers on `'strict'` sources: unchanged.
+  Existing callers on `'reorder'` sources with bare `partitionBy`:
+  the previously-thrown late events now accept correctly — bug fix,
+  not a behavior change anyone could rely on.
+
+- **`collect()` and `apply()` on `LivePartitionedSeries` default-
+  inherit `ordering` and `graceWindow`** from the partitioned series
+  (which inherits from source). Pre-fix, the unified buffer defaulted
+  to `'strict'`, so partition fan-in on a `'reorder'` source could
+  deliver events out-of-order to a strict unified buffer and throw.
+  Retention stays caller-explicit on these per the existing append-
+  only fan-in semantics.
+
+### Notes
+
+- **Six regression tests pin the new defaults** in
+  `LivePartitionedSeries.test.ts`: inherited ordering, inherited
+  graceWindow within reorder, inherited retention on partitions,
+  explicit override of inheritance, strict-source no-change, and the
+  edge case where overriding ordering to strict suppresses graceWindow
+  inheritance. `collect()` inheritance pinned separately.
+- The gRPC experiment's M4 friction note also surfaced milestone B
+  (capability-based late repair) as **driver-light by empirical test**
+  after Codex's adversarial pass caught simulator RNG leakage across
+  A/B legs. Drift signal collapsed to within noise on every host once
+  all randomness sources were seeded — milestone B's library design
+  stays sound, but the gRPC experiment's measurement style (last-tick
+  `.value()` reads) doesn't surface its payoff. Milestone B sequencing
+  updated in PLAN.md to reflect this finding.
+
 ## [0.17.0] — 2026-05-08
 
 `sample({...})` operator wave: bounded-memory stream thinning, surfaced
@@ -385,6 +562,7 @@ compaction); any downstream code reading `#entries` directly would
 break, but those fields are private. Public APIs and types are
 unchanged.
 
+[0.17.1]: https://github.com/pjm17971/pond-ts/compare/v0.17.0...v0.17.1
 [0.17.0]: https://github.com/pjm17971/pond-ts/compare/v0.16.1...v0.17.0
 [0.16.1]: https://github.com/pjm17971/pond-ts/compare/v0.16.0...v0.16.1
 [0.16.0]: https://github.com/pjm17971/pond-ts/compare/v0.15.2...v0.16.0

package/README.md

@@ -1,134 +1,39 @@
-# pond-ts - A modern typescript timeseries library
+# pond-ts
 
-TypeScript-first time series primitives built around typed events, typed schemas, and explicit temporal keys.
+**Highly optimised, fully typed Timeseries library for TypeScript**
+ 
+Schema-driven events, composable batch transforms, push-based streaming
+ingest, multi-entity partitioning, and an optional React integration —
+all strict TypeScript end to end, all immutable.
 
-**pond-ts** is the successor to [pondjs](https://github.com/esnet/pond), rewritten from scratch in TypeScript with a focus on performance, type safety, and composable live streaming.
-
-- typed `TimeSeries` construction and immutable `Event` objects
-- `Time`, `TimeRange`, and `Interval` temporal keys
-- alignment, aggregation, joins, rolling windows, and smoothing
-- `LiveSeries` with push-based ingestion, retention policies, and subscriptions
-- `LiveView`, `LiveAggregation`, and `LiveRollingAggregation` for streaming composition
-- timezone-aware calendar sequences and ingest helpers
-
-The package is intended to work in modern Node and frontend projects.
-
-## Performance
-
-pond-ts is **7.6x faster** than pondjs on average across all comparable operations,
-with no regressions. The advantage grows with data size.
-
-| Category          | Speedup (N=16k) | Notes                                         |
-| ----------------- | --------------- | --------------------------------------------- |
-| **Aggregation**   | 25–32x          | O(N+B) bucketing vs O(N×B) Pipeline           |
-| **Alignment**     | 32x             | Forward cursor vs repeated binary search      |
-| **Rate/diff**     | 18x             | Direct array walk vs Pipeline materialization |
-| **Fill**          | 10–11x          | Single-pass vs Pipeline per strategy          |
-| **Transforms**    | 3–16x           | Pre-validated constructor skips re-validation |
-| **Construction**  | 7x              | Plain objects vs ImmutableJS wrapping         |
-| **Statistics**    | 7–9x            | Direct computation vs ImmutableJS iteration   |
-| **Serialization** | 4x              | Simpler internal representation               |
-| **Event access**  | 23x             | Array indexing vs ImmutableJS `get()`         |
-
-See the [full benchmark results](website/docs/reference/benchmarks.mdx) for detailed numbers.
-Run locally: `npm run build && node packages/core/bench/vs-pondjs.cjs`
-
-## Install
-
-```sh
-npm install pond-ts
-```
-
-## Build
-
-The repo toolchain should work on Node 18, but use `nvm` to verify against newer stable Node releases when needed.
-
-```sh
-npm run build
-```
-
-## Format
-
-```sh
-npm run format
-```
-
-## Test
-
-```sh
-npm test
-```
-
-## Verify
+**pond-ts** is the TypeScript-first successor to
+[pondjs](https://github.com/esnet/pond), rewritten from scratch with a
+focus on type safety, composability, and the live-streaming patterns
+that pondjs never grew.
 
 ```sh
-npm run verify
-```
-
-## Docs site
-
-The documentation website lives in [`website/`](./website) and is built with Docusaurus.
-
-## Examples
-
-- **[pond-ts-dashboard](https://github.com/pjm17971/pond-ts-dashboard)** —
-  a working React dashboard that streams synthetic per-host CPU/request
-  metrics, computes per-host rolling baselines, flags anomalies against
-  ±σ bands, and renders everything as live line and bar charts (~600
-  lines of TypeScript). The repo's README is also published as a docs-
-  site guide: [Building a dashboard](website/docs/how-to-guides/dashboard-guide.mdx).
-
-## License
-
-MIT
-
-## Core model
-
-The key types are:
-
-- `Time`: a point in time
-- `TimeRange`: an unlabeled interval
-- `Interval`: a labeled interval
-
-An `Event` is a key plus typed data.
-
-A `TimeSeries` is an ordered immutable collection of events sharing one schema.
-
-## Quick start
-
-```ts
-import { TimeSeries } from 'pond-ts';
-
-const schema = [
-  { name: 'time', kind: 'time' },
-  { name: 'cpu', kind: 'number' },
-  { name: 'host', kind: 'string' },
-  { name: 'healthy', kind: 'boolean' },
-] as const;
-
-const series = new TimeSeries({
-  name: 'cpu',
-  schema,
-  rows: [
-    [new Date('2025-01-01T00:00:00.000Z'), 0.42, 'api-1', true],
-    [new Date('2025-01-01T00:01:00.000Z'), 0.51, 'api-2', true],
-  ],
-});
-
-const event = series.at(1);
-if (!event) {
-  throw new Error('missing event');
-}
-
-event.key();
-event.timeRange();
-event.get('cpu');
-event.data().host;
-```
-
-## Worked example
-
-This is the kind of flow `pond-ts` is built for: start with typed events, then derive aligned, aggregated, and smoothed analytical views without mutating the original series.
+npm install pond-ts                 # core
+npm install @pond-ts/react          # React hooks (optional)
+```
+
+- **Typed schemas** — declare once, every transform downstream narrows
+  off it. `event.get('cpu')` returns `number | undefined` straight from
+  the schema; no `as` casts.
+- **Batch + streaming with the same vocabulary** — `filter`, `map`,
+  `aggregate`, `rolling`, `diff`, `rate`, `fill`, `cumulative`,
+  `sample`, `reduce` all exist on both `TimeSeries` and `LiveSeries`.
+- **Multi-entity by construction** — `partitionBy('host')` routes per
+  entity; `rolling` / `aggregate` / `fill` / `sample` over a partitioned
+  view all become per-entity automatically.
+- **Bounded-memory streaming** — retention policies, eviction-aware
+  views, and sampling decouple downstream window length
+  from event rate at firehose loads (up to 500k events/sec on a
+  single node.js instance.)
+- **Triggers** — for control of rolling emission cadences. Synchronised
+  partitioned rolling fires across partitions on every boundary.
+- **No legacy baggage**
+
+## Quick start: batch
 
 ```ts
 import { Sequence, TimeSeries } from 'pond-ts';
@@ -144,316 +49,171 @@ const cpu = TimeSeries.fromJSON({
   name: 'cpu',
   schema,
   rows: [
-    ['2025-01-01T00:00:00Z', 0.31, 120, 'api-1'],
-    ['2025-01-01T00:01:00Z', 0.44, 135, 'api-1'],
-    ['2025-01-01T00:02:00Z', 0.52, 141, 'api-1'],
-    ['2025-01-01T00:03:00Z', 0.48, 128, 'api-1'],
-    ['2025-01-01T00:04:00Z', 0.63, 166, 'api-1'],
+    ['2025-01-01T00:00:00Z', 0.31, 120, 'host1'],
+    ['2025-01-01T00:01:00Z', 0.44, 135, 'host2'],
+    ['2025-01-01T00:02:00Z', 0.52, 141, 'host1'],
+    ['2025-01-01T00:03:00Z', 0.48, 128, 'host1'],
+    ['2025-01-01T00:04:00Z', 0.63, 166, 'host3'],
   ],
 });
 
-const perMinute = cpu.align(Sequence.every('1m'), {
-  method: 'hold',
-});
-
-const fiveMinute = cpu.aggregate(Sequence.every('5m'), {
+const byMinute = cpu.aggregate(Sequence.every('1m'), {
   cpu: 'avg',
   requests: 'sum',
   host: 'last',
 });
 
-const rolling = cpu.rolling('3m', {
-  cpu: 'avg',
-  requests: 'sum',
-});
-
-const smoothed = cpu.smooth('cpu', 'ema', {
-  alpha: 0.35,
-  output: 'cpuTrend',
-});
+const bands = cpu.baseline('cpu', { window: '2m', sigma: 2 });
+//    ^ appends rolling avg / sd / upper / lower in one pass.
 
-console.log(perMinute.first()?.key().asString());
-console.log(fiveMinute.first()?.data());
-console.log(rolling.last()?.data());
-console.log(smoothed.last()?.get('cpuTrend'));
+const anomalies = cpu.outliers('cpu', { window: '2m', sigma: 2 });
+//    ^ schema-preserving filter — same columns, just the spikes.
 ```
 
-From one typed source series, you can derive:
-
-- aligned interval views for dashboards and joins
-- bucketed aggregates for reporting
-- rolling metrics for short-term behavior
-- smoothed trends for visualization or alerting
-
-All of those remain fully typed and immutable.
+The full batch surface (`align`, `rolling`, `smooth`, `groupBy`, `join`,
+`reduce`, `diff`, `rate`, `fill`, `dedupe`, `materialize`, `sample`,
+`partitionBy`, `pivotByGroup`, …) follows the same shape: TimeSeries
+in, TimeSeries out, schema preserved.
 
-## JSON ingest
-
-Use `TimeSeries.fromJSON(...)` for external data and ambiguous local timestamps.
+## Quick start: live (streaming)
 
 ```ts
-import { TimeSeries } from 'pond-ts';
+import { LiveSeries, Sequence } from 'pond-ts';
 
-const schema = [
-  { name: 'time', kind: 'time' },
-  { name: 'value', kind: 'number' },
-  { name: 'status', kind: 'string', required: false },
-] as const;
-
-const series = TimeSeries.fromJSON({
+// 1. Same schema; this is a live append buffer with retention.
+const live = new LiveSeries({
   name: 'cpu',
   schema,
-  rows: [
-    ['2025-01-01T09:00', 0.42, 'ok'],
-    ['2025-01-01T10:00', 0.51, null],
-  ],
-  parse: { timeZone: 'Europe/Madrid' },
-});
-```
-
-Export back into the same JSON-friendly shape:
-
-```ts
-const rows = series.toJSON();
-const objectRows = series.toJSON({ rowFormat: 'object' });
-```
-
-For normalized in-memory export helpers:
-
-```ts
-const normalizedRows = series.toRows();
-const normalizedObjects = series.toObjects();
-```
-
-## Event and series transforms
-
-Event-level transforms:
-
-- `get(...)`
-- `set(...)`
-- `merge(...)`
-- `select(...)`
-- `rename(...)`
-- `collapse(...)`
-- `asTime(...)`
-- `asTimeRange()`
-- `asInterval(...)`
-
-Series-level transforms:
-
-- `map(...)`
-- `select(...)`
-- `rename(...)`
-- `collapse(...)`
-- `asTime(...)`
-- `asTimeRange()`
-- `asInterval(...)`
-
-Example:
-
-```ts
-const renamed = series.rename({ cpu: 'usage' });
-const selected = renamed.select('usage', 'healthy');
-```
-
-## Temporal selection
-
-`TimeSeries` includes both positional and temporal selection methods:
-
-- `slice(...)`
-- `filter(...)`
-- `find(...)`
-- `first()`
-- `last()`
-- `before(...)`
-- `after(...)`
-- `within(...)`
-- `overlapping(...)`
-- `containedBy(...)`
-- `trim(...)`
-- `includesKey(...)`
-- `bisect(...)`
-- `atOrBefore(...)`
-- `atOrAfter(...)`
-
-Vocabulary is intentionally distinct:
-
-- `within(...)`: fully contained
-- `overlapping(...)`: intersects without clipping
-- `trim(...)`: intersects and clips event extents
-
-## Sequences
-
-Use `Sequence` for unbounded grids and `BoundedSequence` for explicit finite interval lists.
-
-Fixed-step sequences:
-
-```ts
-import { Sequence } from 'pond-ts';
-
-const minuteGrid = Sequence.every('1m');
-const hourlyGrid = Sequence.hourly();
-```
-
-Calendar-aware sequences:
-
-```ts
-const localDays = Sequence.calendar('day', {
-  timeZone: 'America/New_York',
+  retention: { maxAge: '10m' }, // keep only the last 10 minutes
 });
-```
-
-Explicit bounded sequences:
-
-```ts
-import { BoundedSequence, Interval } from 'pond-ts';
-
-const buckets = new BoundedSequence([
-  new Interval({ value: 'a', start: 0, end: 10 }),
-  new Interval({ value: 'b', start: 20, end: 30 }),
-]);
-```
 
-## Alignment and aggregation
-
-Align onto a sequence:
-
-```ts
-const aligned = series.align(Sequence.every('1m'), {
-  method: 'hold',
-});
-```
+// 2. Push as events arrive. Each push is validated against the schema.
+live.push([Date.now(), 0.45, 128, 'api-1']);
 
-Aggregate into buckets:
+// 3. Compose live views — incremental, push-driven, eviction-aware.
+const recentAvg = live.rolling('5m', { cpu: 'avg' });
+recentAvg.on('event', (e) => render(e.get('cpu')));
 
-```ts
-const aggregated = series.aggregate(Sequence.every('5m'), {
-  cpu: 'avg',
-  host: 'last',
-});
+// 4. Snapshot to a TimeSeries for batch analytics at any time.
+const snap = live.toTimeSeries();
 ```
 
-Built-in aggregations:
-
-- `sum`
-- `avg`
-- `min`
-- `max`
-- `count`
-- `first`
-- `last`
+The full live surface (`filter`, `map`, `select`, `window`, `aggregate`,
+`rolling`, `reduce`, `diff`, `rate`, `pctChange`, `fill`, `cumulative`,
+`sample`) is incremental — events flow, views emit, retention bounds
+memory.
 
-## Joins
+## Quick start: multi-entity
 
-Join two aligned or bucketed series:
+`partitionBy` routes events into per-key buffers. Every stateful
+operator downstream of `partitionBy` runs per-partition automatically:
 
 ```ts
-const joined = left.join(right, { type: 'outer' });
-```
+const perHost = cpu
+  .partitionBy('host')
+  .rolling('5m', { cpu: 'avg', cpu_sd: 'stdev' });
 
-Supported join types:
-
-- `outer`
-- `left`
-- `right`
-- `inner`
-
-Join many:
-
-```ts
-const wide = TimeSeries.joinMany([cpu, memory, errors], {
-  type: 'outer',
-});
+// .collect() fans the per-partition outputs back into a flat TimeSeries
+// with the partition key auto-injected as a column.
+const flat = perHost.collect();
 ```
 
-Conflict handling:
+Same shape on the live side — `live.partitionBy('host')` returns a
+`LivePartitionedSeries` whose `rolling` / `fill` / `diff` / `sample`
+methods all maintain per-partition state.
 
-- default: `onConflict: "error"`
-- optional prefixing:
+## Quick start: bounded-memory sampling
 
-```ts
-const joined = left.join(right, {
-  onConflict: 'prefix',
-  prefixes: ['left', 'right'] as const,
-});
-```
-
-## Rolling windows
-
-Event-driven rolling:
+At firehose rates, a long rolling baseline blows the heap. `sample({
+stride: N })` decouples baseline length from event rate; chain it
+between `partitionBy` and `rolling`:
 
 ```ts
-const rolled = series.rolling('5m', {
-  cpu: 'avg',
-  host: 'last',
-});
+// Per-host 1-in-10 stride feeding a per-host 5m baseline.
+live
+  .partitionBy('host')
+  .sample({ stride: 10 })
+  .rolling('5m', { cpu_avg: 'avg', cpu_sd: 'stdev' });
 ```
 
-Sequence-driven rolling:
+For visualization, the snapshot side ships reservoir sampling too —
+single-pass Algorithm R, sorted by key, fixed point count regardless of
+source size:
 
 ```ts
-const rolledOnGrid = series.rolling(Sequence.every('1m'), '5m', { cpu: 'avg' });
+const points = series.sample({ reservoir: { size: 500 } }).toRows();
+// 500 uncorrelated points drawn uniformly from the source.
 ```
 
-Rolling alignment options:
-
-- `trailing`
-- `centered`
-- `leading`
+## Performance
 
-## Smoothing
+pond-ts is **7.6x faster** than pondjs on average across all comparable
+operations, with no regressions. The advantage grows with data size.
 
-Smoothing targets one numeric column at a time.
+| Category          | Speedup (N=16k) | Notes                                         |
+| ----------------- | --------------- | --------------------------------------------- |
+| **Aggregation**   | 25–32x          | O(N+B) bucketing vs O(N×B) Pipeline           |
+| **Alignment**     | 32x             | Forward cursor vs repeated binary search      |
+| **Rate/diff**     | 18x             | Direct array walk vs Pipeline materialization |
+| **Fill**          | 10–11x          | Single-pass vs Pipeline per strategy          |
+| **Transforms**    | 3–16x           | Pre-validated constructor skips re-validation |
+| **Construction**  | 7x              | Plain objects vs ImmutableJS wrapping         |
+| **Statistics**    | 7–9x            | Direct computation vs ImmutableJS iteration   |
+| **Serialization** | 4x              | Simpler internal representation               |
+| **Event access**  | 23x             | Array indexing vs ImmutableJS `get()`         |
 
-Replace the source column:
+See the [full benchmark results](website/docs/reference/benchmarks.mdx)
+for detailed numbers. Run locally:
 
-```ts
-const smoothed = series.smooth('cpu', 'ema', { alpha: 0.2 });
+```sh
+npm run build && node packages/core/bench/vs-pondjs.cjs
 ```
 
-Append the smoothed output:
+## Documentation
 
-```ts
-const smoothed = series.smooth('cpu', 'movingAverage', {
-  window: '5m',
-  alignment: 'centered',
-  output: 'cpuAvg',
-});
-```
+The full guide is at **<https://pjm17971.github.io/pond-ts/>**.
 
-Supported smoothing methods:
+- **[Start here](https://pjm17971.github.io/pond-ts/docs/)**
+  — five-minute walkthrough with batch, live, and React examples.
+- **[Concepts](https://pjm17971.github.io/pond-ts/docs/start-here/concepts)**
+  — temporal keys, sequences, windowing, partitioning, triggers, late
+  data.
+- **[Transforms reference](https://pjm17971.github.io/pond-ts/docs/pond-ts/transforms/queries)**
+  — every batch operator (queries, aggregation, alignment, rolling,
+  smoothing, sampling, cleaning, reshape, anomaly detection).
+- **[Live reference](https://pjm17971.github.io/pond-ts/docs/pond-ts/live/live-series)**
+  — `LiveSeries`, live transforms, triggering.
+- **[How-to guides](https://pjm17971.github.io/pond-ts/docs/how-to-guides)**
+  — building a dashboard, ingesting messy data.
+- **[API reference (auto-generated)](https://pjm17971.github.io/pond-ts/generated-api/core/)**
+  — TypeDoc output, every public class and method.
+- **[CHANGELOG](./CHANGELOG.md)** — what shipped in each release.
 
-- `ema`
-- `movingAverage`
-- `loess`
+## Examples
 
-For interval-like keys, smoothing uses the key midpoint as the internal anchor.
+- **[pond-ts-dashboard](https://github.com/pjm17971/pond-ts-dashboard)**
+  — a working React dashboard that streams synthetic per-host CPU /
+  request metrics, computes per-host rolling baselines, flags anomalies
+  against ±σ bands, and renders everything as live line and bar charts
+  (~600 lines of TypeScript). Walked through end-to-end in
+  [Building a dashboard](website/docs/how-to-guides/dashboard-guide.mdx).
 
-## Calendar-aware helpers
+## Develop
 
-Primitive helpers normalize local calendar inputs into absolute time:
+The repo is an npm-workspaces monorepo with two published packages
+(`pond-ts`, `@pond-ts/react`). Node 18+ for runtime; Node 20+ for the
+docs site (Docusaurus).
 
-```ts
-import { Interval, Time, TimeRange } from 'pond-ts';
-
-const time = Time.parse('2025-01-01T09:00', { timeZone: 'Europe/Madrid' });
-const day = TimeRange.fromDate('2025-01-01', { timeZone: 'UTC' });
-const month = Interval.fromCalendar('month', '2025-01', {
-  timeZone: 'UTC',
-  value: '2025-01',
-});
+```sh
+npm install         # one-time, hoists deps for both packages
+npm run build       # build both packages
+npm test            # runtime + type-level tests on both packages
+npm run format      # prettier write across the repo
+npm run verify      # format check + build + test (CI parity)
 ```
 
-## Current scope
-
-The library provides both batch analytics (`TimeSeries`) and live streaming
-(`LiveSeries`, `LiveView`, `LiveAggregation`, `LiveRollingAggregation`).
-
-- type-safe construction with schema types that flow through every operation
-- temporal modeling with `Time`, `TimeRange`, and `Interval` keys
-- composable batch analytics (aggregate, align, join, rolling, smooth, fill, diff, rate, groupBy)
-- push-based live ingestion with retention policies and subscriptions
-- live composition: filter, map, select, window, diff, rate, fill, cumulative, aggregate, rolling
+`packages/core/` is the `pond-ts` package; `packages/react/` is
+`@pond-ts/react`. Docs live in `website/`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/react",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "React hooks for pond-ts live time series",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,7 @@
     "test:runtime": "vitest run"
   },
   "peerDependencies": {
-    "pond-ts": "^0.17.0",
+    "pond-ts": "^0.18.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {