@pond-ts/react 0.11.6 → 0.11.8

package/CHANGELOG.md

@@ -7,10 +7,95 @@ 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.6...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.11.8...HEAD
 
 ## [Unreleased]
 
+## [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.11.8]: https://github.com/pjm17971/pond-ts/compare/v0.11.7...v0.11.8
+
+## [0.11.7] — 2026-04-29
+
+### Added
+
+- **`LiveView.count()` and `LiveView.eventRate()` terminal accessors.**
+  Read the current event count and events-per-second over a windowed
+  view directly — closes the
+  `useCurrent(live, { cpu: 'count' }, { tail: '1m' }).cpu / 60`
+  boilerplate surfaced by the gRPC experiment.
+  ```ts
+  const eventsPerSec = live.window('1m').eventRate(); // events/sec
+  const eventsInWindow = live.window('1m').count();
+  ```
+  `eventRate()` requires a time-based window (`window('1m')`) and
+  throws on count-based windows (`window(100)`) — there's no
+  denominator to use. Distinct from `LiveView.rate(columns)`,
+  which is the per-column derivative operator (rate-of-change of
+  values).
+- `LiveView.{filter,map,select}` now propagate the parent's window
+  duration to the child view, so chains like
+  `live.window('1m').filter(...).eventRate()` work as expected.
+- `@pond-ts/react` ships **`useEventRate(source, '1m')`** — a
+  reactive hook returning the events-per-second number, throttled
+  on `'event'` like `useSnapshot`. Hooks mounted on already-
+  populated sources render the actual rate on first paint via
+  lazy `useState` init.
+  ```tsx
+  const eventsPerSec = useEventRate(liveSeries, '1m');
+  // <div>EVENT RATE {eventsPerSec.toFixed(1)}/s</div>
+  ```
+
+[0.11.7]: https://github.com/pjm17971/pond-ts/compare/v0.11.6...v0.11.7
+
 ## [0.11.6] — 2026-04-29
 
 ### Added

package/dist/index.d.ts

@@ -6,5 +6,6 @@ export { useDerived } from './useDerived.js';
 export { useLiveQuery } from './useLiveQuery.js';
 export { useLatest } from './useLatest.js';
 export { useCurrent, type UseCurrentOptions } from './useCurrent.js';
+export { useEventRate } from './useEventRate.js';
 export { takeSnapshot } from './takeSnapshot.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -7,5 +7,6 @@ export { useDerived } from './useDerived.js';
 export { useLiveQuery } from './useLiveQuery.js';
 export { useLatest } from './useLatest.js';
 export { useCurrent } from './useCurrent.js';
+export { useEventRate } from './useEventRate.js';
 export { takeSnapshot } from './takeSnapshot.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,WAAW,GAGZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAA0B,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,WAAW,GAGZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAA0B,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/useEventRate.d.ts

@@ -0,0 +1,40 @@
+import type { LiveSource, RollingWindow, SeriesSchema } from 'pond-ts';
+import type { UseSnapshotOptions } from './useSnapshot.js';
+/**
+ * `LiveSource` that supports `.window(duration)` — `LiveSeries`,
+ * `LiveView`, and accumulators.
+ */
+type Windowable<S extends SeriesSchema> = LiveSource<S> & {
+    window(size: RollingWindow): LiveSource<S> & {
+        count(): number;
+        eventRate(): number;
+        on(type: 'event', fn: (...args: any[]) => void): () => void;
+    };
+};
+/**
+ * Subscribe to a live source, maintain a `.window(duration)` view
+ * over it, and return its events-per-second as a reactive number.
+ *
+ * @example
+ * ```tsx
+ * const eventRate = useEventRate(liveSeries, '1m');
+ * // <div>EVENT RATE {eventRate.toFixed(1)}/s</div>
+ * ```
+ *
+ * Sugar over `live.window(duration).eventRate()` plus a subscription
+ * that re-reads on each push and throttles updates. Closes the
+ * boilerplate that the gRPC experiment's M1 friction notes
+ * surfaced — `useCurrent(live, { cpu: 'count' }, { tail: '1m' }).cpu / 60`
+ * collapses to one hook.
+ *
+ * Throttling matches `useSnapshot`: `throttle: 100` ms by default.
+ * Returns `0` until the first event lands.
+ *
+ * @throws TypeError if `windowDuration` is a count-based window (a
+ *   number) — `eventRate` requires a time denominator. Pass a
+ *   duration string like `'1m'`, `'30s'`, or a number-of-ms via
+ *   `DurationInput` instead.
+ */
+export declare function useEventRate<S extends SeriesSchema>(source: Windowable<S>, windowDuration: RollingWindow, options?: UseSnapshotOptions): number;
+export {};
+//# sourceMappingURL=useEventRate.d.ts.map

package/dist/useEventRate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEventRate.d.ts","sourceRoot":"","sources":["../src/useEventRate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D;;;GAGG;AACH,KAAK,UAAU,CAAC,CAAC,SAAS,YAAY,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG;IACxD,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG;QAC3C,KAAK,IAAI,MAAM,CAAC;QAChB,SAAS,IAAI,MAAM,CAAC;QACpB,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;KAC7D,CAAC;CACH,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,YAAY,EACjD,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EACrB,cAAc,EAAE,aAAa,EAC7B,OAAO,CAAC,EAAE,kBAAkB,GAC3B,MAAM,CAuDR"}

package/dist/useEventRate.js

@@ -0,0 +1,75 @@
+import { useEffect, useRef, useState } from 'react';
+/**
+ * Subscribe to a live source, maintain a `.window(duration)` view
+ * over it, and return its events-per-second as a reactive number.
+ *
+ * @example
+ * ```tsx
+ * const eventRate = useEventRate(liveSeries, '1m');
+ * // <div>EVENT RATE {eventRate.toFixed(1)}/s</div>
+ * ```
+ *
+ * Sugar over `live.window(duration).eventRate()` plus a subscription
+ * that re-reads on each push and throttles updates. Closes the
+ * boilerplate that the gRPC experiment's M1 friction notes
+ * surfaced — `useCurrent(live, { cpu: 'count' }, { tail: '1m' }).cpu / 60`
+ * collapses to one hook.
+ *
+ * Throttling matches `useSnapshot`: `throttle: 100` ms by default.
+ * Returns `0` until the first event lands.
+ *
+ * @throws TypeError if `windowDuration` is a count-based window (a
+ *   number) — `eventRate` requires a time denominator. Pass a
+ *   duration string like `'1m'`, `'30s'`, or a number-of-ms via
+ *   `DurationInput` instead.
+ */
+export function useEventRate(source, windowDuration, options) {
+    const throttleMs = options?.throttle ?? 100;
+    // Lazy initial value: take a one-shot read off a temporary view so a
+    // hook mounted on an already-populated source renders the correct
+    // rate on the first paint, not 0. The temporary view is GC'd when
+    // the effect creates the long-lived view; no leak because we don't
+    // subscribe.
+    const [rate, setRate] = useState(() => {
+        const initialView = source.window(windowDuration);
+        const r = initialView.eventRate();
+        if ('dispose' in initialView &&
+            typeof initialView.dispose === 'function') {
+            initialView.dispose();
+        }
+        return r;
+    });
+    const sourceRef = useRef(source);
+    sourceRef.current = source;
+    useEffect(() => {
+        const view = source.window(windowDuration);
+        setRate(view.eventRate());
+        let timer = null;
+        let pending = false;
+        const flush = () => {
+            timer = null;
+            pending = false;
+            setRate(view.eventRate());
+        };
+        const unsub = view.on('event', () => {
+            if (throttleMs === 0) {
+                setRate(view.eventRate());
+                return;
+            }
+            if (!pending) {
+                pending = true;
+                timer = setTimeout(flush, throttleMs);
+            }
+        });
+        return () => {
+            unsub();
+            if (timer !== null)
+                clearTimeout(timer);
+            if ('dispose' in view && typeof view.dispose === 'function') {
+                view.dispose();
+            }
+        };
+    }, [source, windowDuration, throttleMs]);
+    return rate;
+}
+//# sourceMappingURL=useEventRate.js.map

package/dist/useEventRate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEventRate.js","sourceRoot":"","sources":["../src/useEventRate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAgBpD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAqB,EACrB,cAA6B,EAC7B,OAA4B;IAE5B,MAAM,UAAU,GAAG,OAAO,EAAE,QAAQ,IAAI,GAAG,CAAC;IAC5C,qEAAqE;IACrE,kEAAkE;IAClE,kEAAkE;IAClE,mEAAmE;IACnE,aAAa;IACb,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE;QACpC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,WAAW,CAAC,SAAS,EAAE,CAAC;QAClC,IACE,SAAS,IAAI,WAAW;YACxB,OAAQ,WAAmB,CAAC,OAAO,KAAK,UAAU,EAClD,CAAC;YACA,WAAmB,CAAC,OAAO,EAAE,CAAC;QACjC,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC;IAE3B,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QAC3C,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QAE1B,IAAI,KAAK,GAAyC,IAAI,CAAC;QACvD,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,MAAM,KAAK,GAAG,GAAG,EAAE;YACjB,KAAK,GAAG,IAAI,CAAC;YACb,OAAO,GAAG,KAAK,CAAC;YAChB,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QAC5B,CAAC,CAAC;QAEF,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YAClC,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;gBACrB,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;gBAC1B,OAAO;YACT,CAAC;YACD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,IAAI,CAAC;gBACf,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;YACxC,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,OAAO,GAAG,EAAE;YACV,KAAK,EAAE,CAAC;YACR,IAAI,KAAK,KAAK,IAAI;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YACxC,IAAI,SAAS,IAAI,IAAI,IAAI,OAAQ,IAAY,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;gBACpE,IAAY,CAAC,OAAO,EAAE,CAAC;YAC1B,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,UAAU,CAAC,CAAC,CAAC;IAEzC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/react",
-  "version": "0.11.6",
+  "version": "0.11.8",
   "description": "React hooks for pond-ts live time series",
   "license": "MIT",
   "repository": {