@pond-ts/react 0.11.7 → 0.12.0

package/CHANGELOG.md

@@ -7,10 +7,196 @@ 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.11.7...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.12.0...HEAD
 
 ## [Unreleased]
 
+## [0.12.0] — 2026-05-01
+
+The "triggers" release. Major redesign of how live accumulators
+control emission cadence — `Trigger` is now a first-class concept
+shaped by two converging real-world use cases (synchronised
+partitioned tick aggregation in the gRPC pipeline experiment,
+sequence-sampled rolling in webapp telemetry).
+
+Two correctness audits before publish: a Layer 2 Claude review
+(column collision, dispose, late-spawn, peer-dep) and a Codex
+adversarial review (quiet-partition stale samples, pre-existing
+data replay at construction, spawn-listener cleanup). All findings
+fixed and pinned with regression tests. 1039 / 1039 tests pass.
+
+### Added
+
+- **Trigger as a first-class concept.** A new `Trigger` factory
+  exposed at the package root lets `LiveRollingAggregation` switch
+  emission cadence without changing any other shape:
+
+  ```ts
+  import { LiveSeries, Sequence, Trigger } from 'pond-ts';
+
+  // Webapp telemetry: rolling 1m p95, emit on every 30 s of event-time
+  const rolling = timings.rolling(
+    '1m',
+    { latency: 'p95' },
+    { trigger: Trigger.clock(Sequence.every('30s')) },
+  );
+
+  rolling.on('event', (e) =>
+    fetch('/api/telemetry', { method: 'POST', body: JSON.stringify(e.data()) }),
+  );
+  rolling.value(); // current rolling-window snapshot, independent of trigger
+  ```
+
+  Two trigger variants in this release:
+  - **`Trigger.event()`** — per-event emission. Default; the historical
+    behavior of `LiveRollingAggregation` when no trigger is specified.
+  - **`Trigger.clock(sequence)`** — sequence-triggered emission. One
+    snapshot fires when a source event crosses an epoch-aligned
+    boundary of the (fixed-step) `Sequence`. Output keyed at boundary
+    instants. Calendar sequences are rejected upfront.
+
+  Future variants (`Trigger.count(n)`, custom predicates, compound
+  triggers) are reserved but not yet shipped.
+
+- **Synchronised partitioned rolling.** `LivePartitionedSeries.rolling`
+  now accepts a clock trigger. The output is a
+  `LiveSource<RowSchema>` whose schema is `[time, <partitionColumn>,
+...mappingColumns]`; on every boundary crossing, one event fires
+  per known partition, all sharing the same boundary timestamp.
+  Synchronised across partitions by construction (the bucket index is
+  shared, not per-partition).
+
+  ```ts
+  // Dashboard tick aggregation: 100 hosts, 200ms cadence
+  const ticks = live
+    .partitionBy('host')
+    .rolling(
+      '1m',
+      { cpu: 'avg' },
+      { trigger: Trigger.clock(Sequence.every('200ms')) },
+    );
+
+  ticks.on('event', (e) => {
+    // e.begin() === <boundary timestamp>, same for every host this tick
+    // e.get('host') === 'api-1' | 'api-2' | …
+    // e.get('cpu') === <rolling avg for that host>
+  });
+  ```
+
+  Restricted to direct-after-`partitionBy` in this release: chained
+  sugar (`partitionBy(c).fill(...).rolling(...)`) rejects clock
+  triggers with a clear error. Lifts in a future release once a real
+  use case appears.
+
+  Closes the gRPC experiment's M3.5 dashboard friction note (the
+  hand-rolled `HostAggregator` becomes ~10 lines of pond code).
+
+### Removed (breaking — pre-1.0)
+
+- **`LiveSequenceRollingAggregation`** class deleted. Its capability
+  is preserved as `LiveRollingAggregation` with
+  `{ trigger: Trigger.clock(sequence) }`. Migration: replace
+  `live.rolling('1m', m).sample(seq)` with
+  `live.rolling('1m', m, { trigger: Trigger.clock(seq) })`. Single
+  rolling object now serves both backend reporting and direct
+  `.value()` reads (no separate sampler reference).
+- **`.sample(sequence)`** method removed from `LiveRollingAggregation`.
+  Use the trigger option above.
+
+### Changed
+
+- **`LiveRollingOptions`** gains an optional `trigger?: Trigger`
+  field. Default behavior (no `trigger` specified) is unchanged from
+  v0.11.x — per-event emission. Backward compatible for everyone
+  who didn't use `.sample()`.
+
+### Performance
+
+- New benchmark `scripts/perf-triggers.mjs` covers both
+  non-partitioned and synchronised partitioned cases. Headline numbers
+  on a current MacBook Pro:
+  - Non-partitioned: clock(30s) ~50% faster than per-event baseline
+    (emission is rarer); clock(1s) similar.
+  - Synchronised partitioned (100 hosts, 30k events at realistic
+    rates): ~300 ns/emission at 200ms cadence; +205% over per-
+    partition baseline at the high end. Well within budget for the
+    motivating dashboard use case.
+
+### Notes
+
+- **`docs/rfcs/triggers.md`** captures the full design rationale,
+  the four sign-off questions, and the migration plan. Read this if
+  you want the "why this shape" context.
+
+### Known limitations
+
+- **Synchronised partitioned rolling output type is loose** —
+  `LiveSource<SeriesSchema>` rather than a schema-narrowed shape.
+  Runtime schema is correct; only static types widen. Tightening is
+  queued for a follow-up release.
+- **Synchronised partitioned rolling rejects column-name collisions**
+  between the partition column and any reducer-output column at
+  construction (e.g. `partitionBy('cpu').rolling('1m', { cpu: 'avg' }, { trigger })`).
+  Rename the reducer output (once `AggregateOutputMap` lands on live
+  rolling) or partition by a different column.
+- **Late-spawn partitions only appear in ticks after their first event
+  arrives.** A partition unknown to the sync source contributes no
+  row to the current tick. Use `partitionBy(col, { groups: [...] })`
+  to eagerly include partitions from construction.
+
+## [0.11.8] — 2026-04-30
+
+### Added
+
+- **`rolling.sample(sequence)`** on `LiveRollingAggregation` — taps a
+  rolling aggregation and emits one snapshot of the rolling state each
+  time a source event crosses an epoch-aligned boundary of `sequence`.
+  Closes the frontend-telemetry gap: collect high-frequency timing
+  events, sample p95 latency to a backend every 30 s, while the same
+  rolling drives an in-app live display (no duplicated deque).
+
+  ```ts
+  const rolling = timings.rolling('1m', { latency: 'p95' });
+
+  // One sampler → backend report every 30 s of event time
+  const reported = rolling.sample(Sequence.every('30s'));
+  reported.on('event', (e) =>
+    fetch('/api/telemetry', { method: 'POST', body: JSON.stringify(e.data()) }),
+  );
+
+  // Same rolling drives the UI live display
+  useLiveQuery(timings, () => rolling.value());
+  ```
+
+  `sequence` must be a fixed-step `Sequence`; calendar sequences
+  (`Sequence.daily()` etc.) are rejected upfront — boundary indexing
+  needs a constant step.
+
+  Emission is **data-driven**: no `setInterval`. If the source goes
+  quiet, no events fire. A single source event spanning multiple
+  boundaries fires exactly one event at the new bucket. Snapshot is
+  taken after the boundary-crossing event is ingested by the rolling,
+  so the emitted value includes that event's contribution.
+
+  **Independent lifetimes.** `sample.dispose()` only detaches the
+  sampler from the rolling; the rolling's lifecycle stays the user's
+  responsibility. One rolling can power multiple `.sample()` cadences
+  plus direct `rolling.value()` reads without coupling.
+
+- **`LiveSequenceRollingAggregation` exported** from package root with
+  full `LiveSource<Out>` surface and the same view-transform set as
+  `LiveRollingAggregation` (`filter`, `map`, `select`, `window`,
+  `diff`, `rate`, `pctChange`, `fill`, `cumulative`, `rolling`,
+  `aggregate`).
+
+- **Telemetry-reporting recipe** at
+  `website/docs/recipes/telemetry-reporting.mdx` — end-to-end
+  frontend-collection → backend-summary pattern using `.sample()`,
+  plus the React in-app display via `useLiveQuery`.
+
+[0.12.0]: https://github.com/pjm17971/pond-ts/compare/v0.11.8...v0.12.0
+[0.11.8]: https://github.com/pjm17971/pond-ts/compare/v0.11.7...v0.11.8
+
 ## [0.11.7] — 2026-04-29
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/react",
-  "version": "0.11.7",
+  "version": "0.12.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.11.0",
+    "pond-ts": "^0.12.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {