@pond-ts/fit 0.31.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Murphy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# pond-ts
+
+**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 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 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.
+- **Typed column extraction** — `series.column('cpu')` returns a
+  schema-narrowed typed column with single-pass reductions
+  (`min`/`max`/`sum`/`mean`/`stdev`/`median`/`percentile`/`minMax`),
+  index downsampling (`bin`), and a zero-copy `toFloat64Array()` for
+  canvas / WebGL draw loops — no per-event allocation on the hot path.
+- **No legacy baggage**
+
+## Quick start: batch
+
+```ts
+import { Sequence, TimeSeries } from 'pond-ts';
+
+const schema = [
+  { name: 'time', kind: 'time' },
+  { name: 'cpu', kind: 'number' },
+  { name: 'requests', kind: 'number' },
+  { name: 'host', kind: 'string' },
+] as const;
+
+const cpu = TimeSeries.fromJSON({
+  name: 'cpu',
+  schema,
+  rows: [
+    ['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 byMinute = cpu.aggregate(Sequence.every('1m'), {
+  cpu: 'avg',
+  requests: 'sum',
+  host: 'last',
+});
+
+const bands = cpu.baseline('cpu', { window: '2m', sigma: 2 });
+//    ^ appends rolling avg / sd / upper / lower in one pass.
+
+const anomalies = cpu.outliers('cpu', { window: '2m', sigma: 2 });
+//    ^ schema-preserving filter — same columns, just the spikes.
+```
+
+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.
+
+## Quick start: live (streaming)
+
+```ts
+import { LiveSeries, Sequence } from 'pond-ts';
+
+// 1. Same schema; this is a live append buffer with retention.
+const live = new LiveSeries({
+  name: 'cpu',
+  schema,
+  retention: { maxAge: '10m' }, // keep only the last 10 minutes
+});
+
+// 2. Push as events arrive. Each push is validated against the schema.
+live.push([Date.now(), 0.45, 128, 'api-1']);
+
+// 3. Compose live views — incremental, push-driven, eviction-aware.
+const recentAvg = live.rolling('5m', { cpu: 'avg' });
+recentAvg.on('event', (e) => render(e.get('cpu')));
+
+// 4. Snapshot to a TimeSeries for batch analytics at any time.
+const snap = live.toTimeSeries();
+```
+
+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.
+
+## Quick start: multi-entity
+
+`partitionBy` routes events into per-key buffers. Every stateful
+operator downstream of `partitionBy` runs per-partition automatically:
+
+```ts
+const perHost = cpu
+  .partitionBy('host')
+  .rolling('5m', { cpu: 'avg', cpu_sd: 'stdev' });
+
+// .collect() fans the per-partition outputs back into a flat TimeSeries
+// with the partition key auto-injected as a column.
+const flat = perHost.collect();
+```
+
+Same shape on the live side — `live.partitionBy('host')` returns a
+`LivePartitionedSeries` whose `rolling` / `fill` / `diff` / `sample`
+methods all maintain per-partition state.
+
+## Quick start: bounded-memory sampling
+
+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
+// 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' });
+```
+
+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 points = series.sample({ reservoir: { size: 500 } }).toRows();
+// 500 uncorrelated points drawn uniformly from the source.
+```
+
+## Performance
+
+pond-ts is faster on **every** comparable operation, with no regressions —
+a **~17x** geometric-mean speedup across the measurable ops, plus a handful
+of transforms (`select` / `rename`) that are **effectively instant** (O(1)
+column rebinds, below the timer's resolution). The advantage grows with data
+size.
+
+| Category          | Speedup (N=16k)                                      | Notes                                         |
+| ----------------- | ---------------------------------------------------- | --------------------------------------------- |
+| **Rate**          | ~120x                                                | Single columnar walk vs Pipeline              |
+| **Fill**          | 77–87x                                               | Single columnar pass vs Pipeline per strategy |
+| **Aggregation**   | 57–82x                                               | O(N+B) bucketing vs O(N×B) Pipeline           |
+| **Statistics**    | 18–80x                                               | Typed-array reduce vs ImmutableJS iteration   |
+| **Alignment**     | 42x                                                  | Forward cursor vs repeated binary search      |
+| **Construction**  | 13x                                                  | Columnar intake vs ImmutableJS wrapping       |
+| **Chained**       | 8x                                                   | Derived constructors vs per-step Pipeline     |
+| **Transforms**    | `select`/`rename` instant; `collapse` 30x; `map` ~4x | Column reshapes vs Pipeline                   |
+| **Event access**  | 6x                                                   | Array indexing vs ImmutableJS `get()`         |
+| **Serialization** | 4x                                                   | Lightweight columnar representation           |
+
+See the [full benchmark results](website/docs/reference/benchmarks.mdx)
+for detailed numbers. Run locally:
+
+```sh
+npm run build && node packages/core/bench/vs-pondjs.cjs
+```
+
+## Documentation
+
+The full guide is at **<https://pjm17971.github.io/pond-ts/>**.
+
+- **[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.
+
+## 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). Walked through end-to-end in
+  [Building a dashboard](website/docs/how-to-guides/dashboard-guide.mdx).
+
+## Develop
+
+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).
+
+```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)
+```
+
+`packages/core/` is the `pond-ts` package; `packages/react/` is
+`@pond-ts/react`. Docs live in `website/`.
+
+## License
+
+MIT

package/dist/activity/index.d.ts

@@ -0,0 +1,254 @@
+/**
+ * The `Activity` / `Section` façade — the ergonomic object model of the fitness
+ * library. A thin, memoizing skin over the functional
+ * operator core: `prepareActivity` (the canonical pond series + derived columns),
+ * `summaryFromPrepared`, the geo splitters, and the power/zone analytics. Every
+ * method delegates to a tested pure operator and hands back {@link quantities}
+ * (Distance, Power, Speed, …) instead of bare numbers.
+ *
+ * `Activity` is **profile-agnostic**: anything that needs an athlete's FTP, body
+ * weight, or zone definitions takes them as arguments (the caller resolves them
+ * from the athlete profile as-of the activity date). The object wraps only the
+ * activity's own evidence.
+ *
+ * `Section` is a range-with-metrics over the activity — a split, a recorded lap,
+ * or an arbitrary `[from, to]` slice — exposing the same quantity-typed analytics
+ * as the whole activity. (NOT `Segment`: that word is reserved for the story
+ * hierarchy, Story → Chapter → Segment → Activity. See the RFC.)
+ */
+import type { ActivityMeta, ImportedActivity } from '../types.js';
+import type { TrackSeries, DistanceEffort } from '../geo/index.js';
+import { type PreparedActivity, type ActivitySummary, type ActivitySummaryOptions, type WindowChannelOptions, type ChannelProfile } from '../summary/index.js';
+import { type PowerSummary, type PowerCurvePoint, type PowerEffort, type PowerZone } from '../power/index.js';
+import { type ZoneTime } from '../zones/index.js';
+import { Profile, type ZoneDef } from '../profile/index.js';
+import { Distance, Elevation, Duration, Speed, Pace, Power, HeartRate, Cadence } from '../quantities.js';
+/** The normalized metric bundle a {@link Section} is a quantity-typed view over.
+ *  Produced three ways — a computed split, a recorded lap, or an arbitrary range
+ *  — all reduced to the same shape (native SI). Optional fields are absent when
+ *  the underlying channel wasn't recorded. */
+export interface SectionMetrics {
+    label: string;
+    /** Elapsed seconds from activity start to the section's start / end. */
+    fromSec: number;
+    toSec: number;
+    /** Cumulative-distance window into the activity (metres) — the map-highlight
+     *  anchor, mirroring [fromSec, toSec] on the distance axis. */
+    startMeters: number;
+    endMeters: number;
+    distanceMeters: number;
+    /** Wall-clock span (toSec − fromSec). */
+    durationSeconds: number;
+    /** Time actually moving — equals duration for computed splits. */
+    movingSeconds: number;
+    elevationGainMeters: number;
+    elevationLossMeters?: number | undefined;
+    normalizedWatts?: number | undefined;
+    avgWatts?: number | undefined;
+    maxWatts?: number | undefined;
+    avgHeartrate?: number | undefined;
+    maxHeartrate?: number | undefined;
+    avgCadence?: number | undefined;
+    avgSpeedMps?: number | undefined;
+    maxSpeedMps?: number | undefined;
+}
+/**
+ * A range of an activity with its own analytics — a split, a lap, or a slice.
+ * Quantity-typed views over a {@link SectionMetrics} bundle; nothing computes
+ * here (the producer already did), so accessors are pure getters.
+ */
+export declare class Section {
+    private readonly m;
+    constructor(m: SectionMetrics);
+    get label(): string;
+    /** Elapsed `[from, to]` window into the activity, in seconds — the time anchor
+     *  a contiguous Focus / range annotation maps onto. */
+    get fromSeconds(): number;
+    get toSeconds(): number;
+    /** Cumulative-distance window [start, end] into the activity (metres) — the
+     *  anchor for a map-segment highlight, the distance-axis peer of from/toSeconds. */
+    get startMeters(): number;
+    get endMeters(): number;
+    distance(): Distance;
+    duration(): Duration;
+    movingTime(): Duration;
+    elevationGain(): Elevation;
+    elevationLoss(): Elevation | undefined;
+    normalizedPower(): Power | undefined;
+    avgPower(): Power | undefined;
+    maxPower(): Power | undefined;
+    avgHeartRate(): HeartRate | undefined;
+    maxHeartRate(): HeartRate | undefined;
+    avgCadence(): Cadence | undefined;
+    /** Average speed — the recorded average when present, else distance ÷ moving
+     *  time. `undefined` only when neither is available (no distance / no time). */
+    avgSpeed(): Speed | undefined;
+    maxSpeed(): Speed | undefined;
+    /** Average pace — the inverse view of {@link avgSpeed}. */
+    pace(): Pace | undefined;
+}
+/** Channel values interpolated at one instant — what {@link Activity.at} returns.
+ *  Only channels the activity carries are present. */
+export interface Sample {
+    /** Elapsed seconds from the start (the query time, clamped to the activity). */
+    atSeconds: number;
+    distance?: Distance;
+    elevation?: Elevation;
+    heartRate?: HeartRate;
+    power?: Power;
+    cadence?: Cadence;
+    speed?: Speed;
+}
+/**
+ * The activity façade. Construct from an imported activity (`fromStreams`); read
+ * the canonical series (`timeSeries`), slice it (`splits` / `laps` / `range`),
+ * sample it (`at`), and run analytics (`power` / `powerCurve` / `bestEfforts` /
+ * `hrZones`). Immutable; derived results memoize on first call.
+ */
+export declare class Activity {
+    private readonly prep;
+    private _summary?;
+    /** NaN-for-missing power, lazily cleaned; `null` once we know there is none. */
+    private _watts?;
+    /** Splits memoized per interval (metres) — the summary recompute isn't cheap. */
+    private readonly _splits;
+    private constructor();
+    /** Build from an imported activity (streams + metadata + optional laps) — the
+     *  Strava / fixture path. `fromFit` / `fromGpx` / `fromTcx` land with ingest. */
+    static fromStreams(imported: ImportedActivity): Activity;
+    /** Session metadata — id, name, sport, start, totals. */
+    get meta(): ActivityMeta;
+    /** Whether the activity carries GPS positions (a map; otherwise indoor / GPS-off). */
+    get hasTrack(): boolean;
+    /** Whether a power channel was recorded. */
+    get hasPower(): boolean;
+    /** The canonical pond series (the escape hatch to the functional/pond layer). */
+    timeSeries(): TrackSeries;
+    /** The prepared per-sample columns + derived series — for consumers still on
+     *  the functional path (e.g. the chart) while they migrate to the façade. */
+    prepared(): PreparedActivity;
+    /** The full journey summary (totals, channels, polyline, splits, laps). */
+    summary(options?: ActivitySummaryOptions): ActivitySummary;
+    /** Channels re-bucketed over a distance window `[startMeters, endMeters]` — the
+     *  chart-zoom resolution path, finer than the whole-activity profile from
+     *  {@link summary}. The façade home for the functional `windowChannels`. */
+    windowChannels(options: WindowChannelOptions): ChannelProfile[];
+    /** Total moving / elapsed / distance, quantity-typed. */
+    distance(): Distance;
+    elapsedTime(): Duration;
+    movingTime(): Duration;
+    /** Even-distance splits (per-km, per-mile, …) as Sections, in order. */
+    splits(interval: Distance): Section[];
+    /** Device-recorded laps as Sections (empty if the source recorded none). */
+    laps(): Section[];
+    /** An arbitrary slice `[from, to]` (elapsed time) as a Section, with metrics
+     *  computed from the series over that window. Clamped to the activity. */
+    range(from: Duration, to: Duration, label?: string): Section;
+    /** Power summary (NP, IF, TSS, distribution, zones, curve) at the given FTP —
+     *  `undefined` when no power was recorded. `elapsedSeconds` drives TSS. */
+    power(ftp: number): PowerSummary | undefined;
+    /** Mean-maximal power curve; `[]` when no power. */
+    powerCurve(durations?: number[]): PowerCurvePoint[];
+    /** Power best efforts at the canonical durations (+ W/kg if `weightKg`); `[]`
+     *  when no power. */
+    bestEfforts(opts?: {
+        weightKg?: number;
+        durations?: number[];
+    }): PowerEffort[];
+    /** Distance best efforts — fastest time over each canonical distance window
+     *  (400 m … marathon), with avg HR. Needs a time axis; `[]` otherwise. */
+    distanceBestEfforts(distances?: number[]): DistanceEffort[];
+    /** Time-in-zone for heart rate against the given zone definition; `[]` with no HR. */
+    hrZones(def: ZoneDef): ZoneTime[];
+    /** Time-in-zone for pace (from the derived speed) against `def`; `[]` with no time. */
+    paceZones(def: ZoneDef): ZoneTime[];
+    /** Bind an athlete {@link Profile} for the analytics that need FTP / body
+     *  weight / zone definitions — power summary, time-in-zone, W/kg. Returns a
+     *  {@link ProfiledActivity} whose slices (`splits` / `range` / `laps`) stay
+     *  bound to the same profile (turtles all the way down). The bare `Activity`
+     *  keeps only the profile-agnostic methods. */
+    usingProfile(profile: Profile): ProfiledActivity;
+    /** Channel values interpolated at one elapsed instant — the scrub / annotation
+     *  anchor sample. Linear between the bracketing samples. */
+    at(t: Duration): Sample;
+    /** Cleaned (NaN-for-missing) power column, memoized; `undefined` if no power. */
+    private watts;
+    /** Compute a range's metrics from the columns over `[lo, hi]` (inclusive). */
+    private metricsForRange;
+}
+/**
+ * An {@link Activity} bound to an athlete {@link Profile} — the home for the
+ * analytics that need FTP / body weight / zone definitions. Obtained via
+ * `activity.usingProfile(bob)`. Its slices (`splits` / `range` / `laps`) return
+ * {@link ProfiledSection}s carrying the same profile, so the binding flows all
+ * the way down. The bare {@link Activity} keeps only the profile-agnostic
+ * methods, so a missing FTP / weight is a type-level absence, not a runtime
+ * `undefined`.
+ */
+export declare class ProfiledActivity {
+    private readonly activity;
+    private readonly profile;
+    constructor(activity: Activity, profile: Profile);
+    /** Full power summary (NP, IF, TSS, distribution, zones, curve) at the
+     *  profile's FTP. `undefined` when no power was recorded or no FTP is known. */
+    power(): PowerSummary | undefined;
+    /** Time in each Coggan power zone (FTP-relative); `[]` with no power or no FTP. */
+    byPowerZone(): PowerZone[];
+    /** Time in each heart-rate zone; `[]` with no HR or no HR zones on the profile. */
+    byHeartRateZone(): ZoneTime[];
+    /** Time in each pace zone; `[]` with no time axis or no pace zones on the profile. */
+    byPaceZone(): ZoneTime[];
+    /** Power best efforts (+ W/kg from the profile's body weight); `[]` with no power. */
+    bestEfforts(durations?: number[]): PowerEffort[];
+    /** Even-distance splits as profile-bound sections. */
+    splits(interval: Distance): ProfiledSection[];
+    /** Device-recorded laps as profile-bound sections (empty if none recorded). */
+    laps(): ProfiledSection[];
+    /** An arbitrary `[from, to]` slice as a profile-bound section. */
+    range(from: Duration, to: Duration, label?: string): ProfiledSection;
+}
+/**
+ * A {@link Section} bound to a {@link Profile} — adds the FTP / weight / zone
+ * analytics over the section's own window. Profile-agnostic metrics delegate to
+ * the underlying section; the zone / power methods recompute over the section's
+ * `[fromSeconds, toSeconds]` slice of the parent activity.
+ */
+export declare class ProfiledSection {
+    private readonly activity;
+    private readonly section;
+    private readonly profile;
+    private _window?;
+    constructor(activity: Activity, section: Section, profile: Profile);
+    /** The underlying profile-agnostic section. */
+    get unprofiled(): Section;
+    get label(): string;
+    get fromSeconds(): number;
+    get toSeconds(): number;
+    get startMeters(): number;
+    get endMeters(): number;
+    distance(): Distance;
+    duration(): Duration;
+    movingTime(): Duration;
+    elevationGain(): Elevation;
+    elevationLoss(): Elevation | undefined;
+    normalizedPower(): Power | undefined;
+    avgPower(): Power | undefined;
+    maxPower(): Power | undefined;
+    avgHeartRate(): HeartRate | undefined;
+    maxHeartRate(): HeartRate | undefined;
+    avgCadence(): Cadence | undefined;
+    avgSpeed(): Speed | undefined;
+    maxSpeed(): Speed | undefined;
+    pace(): Pace | undefined;
+    /** Power summary over the section's window; `undefined` with no power / no FTP. */
+    power(): PowerSummary | undefined;
+    /** Time in each power zone over the section's window; `[]` with no power / FTP. */
+    byPowerZone(): PowerZone[];
+    /** Time in each HR zone over the section's window; `[]` with no HR / HR zones. */
+    byHeartRateZone(): ZoneTime[];
+    /** Time in each pace zone over the section's window; `[]` with no time / pace zones. */
+    byPaceZone(): ZoneTime[];
+    /** Slice the parent columns to `[fromSeconds, toSeconds]`, computed once. */
+    private window;
+}
+//# sourceMappingURL=index.d.ts.map