@pond-ts/react 0.13.2 → 0.14.1

package/CHANGELOG.md

@@ -7,10 +7,202 @@ 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.13.2...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.14.1...HEAD
 
 ## [Unreleased]
 
+## [0.14.1] — 2026-05-03
+
+The "samples reducer + lifted custom-fn guard" release. Surfaced by
+the gRPC experiment's step-4 (anomaly density) walkback: the use
+case "compute counts of values exceeding `k·σ` from a baseline" needs
+the **raw values** from the rolling window, but pond's existing
+built-ins all collapse to scalars or deduplicate. Custom-function
+reducers — which would cover the use case cleanly — worked on batch
+but were rejected at runtime on live with a `TypeError` pointing at
+`AggregateOutputMap` aliases (which don't actually solve "all values"
+either). Two related changes ship together to close both gaps.
+
+### Added
+
+- **`'samples'` built-in reducer.** Returns the bucket's defined
+  values as an array, in arrival order, with duplicates preserved.
+  Sits beside `'unique'` (which deduplicates) and `'top${N}'` (which
+  bounds and frequency-orders) — same array-output kind, same
+  type-system narrowing through `AggregateOutputMap`. Library-
+  implemented; per-event cost is O(1) `add` / O(1) `remove`
+  (Map-keyed by event index); `snapshot` is O(N) array copy.
+  Memory O(window size).
+
+  ```ts
+  // Anomaly density: count samples > k·σ from a separate baseline.
+  const stats = live.rolling(
+    '1m',
+    {
+      mean: { from: 'cpu', using: 'avg' },
+      sd:   { from: 'cpu', using: 'stdev' },
+    },
+    { trigger: Trigger.every('30s') },
+  );
+
+  const recent = live.rolling('200ms', {
+    vals: { from: 'cpu', using: 'samples' },
+  });
+
+  // At each tick, count threshold crossings against the baseline:
+  stats.on('event', (e) => {
+    const samples = recent.value().vals as ReadonlyArray<number>;
+    const counts = thresholds.map(
+      (k) => samples.filter((v) => v - e.get('mean') > k * e.get('sd')).length,
+    );
+    // ... emit anomaly density
+  });
+  ```
+
+  Like `unique`, `samples` flattens one level on array-kind source
+  columns. Returns `[]` for an empty bucket.
+
+### Changed
+
+- **Custom-function reducers now work on live.** Removed the runtime
+  `TypeError` guards on `LiveAggregation`, `LiveRollingAggregation`,
+  and `LivePartitionedSyncRolling` that previously rejected
+  function-typed reducers. New `bucketStateFor` and `rollingStateFor`
+  helpers in `reducers/index.ts` route built-ins to their dedicated
+  O(1) machinery and wrap custom functions in a generic adapter:
+
+  - **Bucket adapter** (`LiveAggregation`): buffers values, calls
+    the function once at `snapshot()` time. O(N) per snapshot.
+  - **Rolling adapter** (`LiveRollingAggregation`,
+    `LivePartitionedSyncRolling`): Map-keyed by event index for O(1)
+    `add` / O(1) `remove`; `snapshot()` calls the function with
+    `Array.from(map.values())` in arrival order. **O(N) per
+    snapshot** — the function re-runs over the current window each
+    time the accumulator emits.
+
+  Documented as the explicit trade-off: convenience of writing
+  `(values) => ...` inline against the perf cliff at high event
+  rates. For high-throughput streams prefer built-ins or `'samples'`
+  (collapse the window once on the producer side, run custom logic
+  on the consumer). For low-rate dashboards / debug pipelines /
+  prototypes, the convenience usually wins.
+
+  Pre-v0.14.1, calling `live.rolling(...)` with a custom-function
+  reducer threw `TypeError: live rolling reducer for output 'X' must
+  be a built-in name; ...`. Post-v0.14.1, the same call constructs
+  successfully and runs.
+
+### Tests
+
+- 15 new tests in `test/samples-reducer.test.ts` covering: batch
+  reduce / aggregate / rolling (including the array-source
+  flattening); live aggregate (per-bucket arrays); live rolling
+  (window eviction, snapshot correctness through multiple cycles);
+  synced partitioned rolling with samples per partition; an
+  end-to-end anomaly-density-against-baseline scenario.
+- 2 obsolete tests in `LiveAggregateOutputMap.test.ts` rewritten —
+  previously asserted the rejection error, now assert that custom
+  functions construct successfully and produce the right value.
+- Total core tests: 1087 (was 1072).
+
+### Docs
+
+- `pond-ts/transforms/reducer-reference.mdx`: new `'samples'` entry
+  in the Array-producing reducers section; "Choosing a reducer"
+  matrix updated; empty-bucket and rolling-complexity tables
+  updated; Custom reducers section gained the live perf-cliff
+  callout.
+- `pond-ts/transforms/rolling.mdx`: replaced the "Custom-function
+  reducers are batch-only" note with the new "O(N) per snapshot on
+  live" perf-cliff note pointing at the reducer reference.
+
+[0.14.1]: https://github.com/pjm17971/pond-ts/compare/v0.14.0...v0.14.1
+
+## [0.14.0] — 2026-05-01
+
+Two perf wins driven by the gRPC experiment's V3 profiling pass
+(PR #14 on `pond-grpc-experiment`): `estimateEventBytes` at 6.2%
+self time and the partition router's `Event → row → Event`
+round-trip (combined ~7% in `#validateRow` + `Event` constructor
+re-allocations). Both root-caused, both fixed.
+
+Benchmark deltas on `scripts/perf-live-partitioned.mjs`
+(100k events, median ms):
+
+| Scenario                              | Before | After  | Δ       |
+| ------------------------------------- | -----: | -----: | ------: |
+| bare `LiveSeries.push`                |  41.11 |  30.08 | **−27%** |
+| `partitionBy('host')` routing (10)    |  83.14 |  39.10 | **−53%** |
+| `partitionBy + collect()`             | 124.82 |  49.96 | **−60%** |
+| `partitionBy + apply(fill)`           | 120.53 |  49.64 | **−59%** |
+| `partitionBy('host')` routing (1000)  | 105.92 |  43.23 | **−59%** |
+
+The bare-push delta is from the byte-estimate removal; the
+partition-routing deltas are from the trusted-pipeline path that
+skips `Event → row → Event` reconstruction at every routing hop.
+
+### Removed (breaking, pre-1.0)
+
+- **`retention.maxBytes`** option on `LiveSeriesOptions`. Speculative
+  feature from pre-v0.10 that no real user has reached for. Use
+  `retention.maxEvents` for count-based caps; `maxBytes` was
+  approximate (rough per-event byte estimate) and the imprecision
+  meant it was rarely used as designed.
+
+  Migration: replace `{ retention: { maxBytes: N } }` with
+  `{ retention: { maxEvents: M } }` where M is your desired
+  upper bound on event count.
+
+### Changed
+
+- **`estimateEventBytes` and the `#byteEstimate` accumulator
+  removed** from `LiveSeries`. Closes the 6.2% per-push self-time
+  line the gRPC experiment surfaced. Bare push is now ~27% faster
+  for the typical case where `maxBytes` was never set.
+
+- **Partition router uses a trusted-pipeline fast path.**
+  `LivePartitionedSeries.#routeEvent`, `collect()`, and `apply()`
+  previously round-tripped `Event → row → Event` at every routing
+  hop — re-validating and re-allocating Events that the source
+  pipeline had already constructed. New `_pushTrustedEvents` method
+  on `LiveSeries` accepts pre-validated Event references (under a
+  schema-identity contract; only used internally where the source
+  and target schemas are guaranteed identical). Closes the ~7%
+  combined self-time line in `#validateRow` (×2) and `Event`
+  constructor (×2) that the gRPC profile flagged.
+
+  Trusted-pipeline applies to: the source-to-partition route, the
+  per-partition replay-on-construct prefix, the unified-buffer
+  `collect()` subscriber, and `apply()`'s factory-output forwarding.
+  All four sites had identical schemas at both ends — the trust
+  contract holds without runtime re-checking.
+
+  `_pushTrustedEvents` is `@internal` and not exported from the
+  public type surface. Reach for `pushMany` from any external
+  context; the trusted variant skips schema validation and is
+  only safe for pond's own internal pipelines.
+
+### Tests
+
+- 4 new tests in `test/LiveSeries.test.ts` for the trusted-pipeline
+  path: insertion without re-validation, listener fan-out and
+  retention behaviour, ordering enforcement (strict still rejects
+  out-of-order on the trusted path — the trust contract is only
+  about validation/allocation, not insertion ordering), empty-array
+  no-op.
+- Removed the `retention: maxBytes` describe block in
+  `test/LiveSeries.test.ts` and the `forwards retention.maxBytes`
+  assertion in `test/LiveSeries.snapshot-append.test.ts`.
+- Total core tests: 1072 (was 1070; +4 new for the trusted path,
+  −2 for the removed maxBytes assertions).
+
+### Docs
+
+- `live-series.mdx`: retention table and example trimmed to
+  `maxEvents` + `maxAge` only. Removed the byte-estimate prose.
+
+[0.14.0]: https://github.com/pjm17971/pond-ts/compare/v0.13.2...v0.14.0
+
 ## [0.13.2] — 2026-05-01
 
 Strictly additive over v0.13.1. Adds `Trigger.count(n)` per the

package/package.json

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