@pond-ts/fit 0.31.0 → 0.31.1

package/CHANGELOG.md

@@ -8,8 +8,9 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`, and
 them all. 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.31.0...HEAD
-[0.31.0]: https://github.com/pjm17971/pond-ts/compare/v0.30.0...v0.31.0
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.31.1...HEAD
+[0.31.1]: https://github.com/pjm17971/pond-ts/compare/v0.30.0...v0.31.1
+[0.31.0]: https://github.com/pjm17971/pond-ts/compare/v0.30.0...3c4e8bd
 [0.30.0]: https://github.com/pjm17971/pond-ts/compare/v0.29.0...v0.30.0
 [0.29.0]: https://github.com/pjm17971/pond-ts/compare/v0.28.0...v0.29.0
 [0.28.0]: https://github.com/pjm17971/pond-ts/compare/v0.27.0...v0.28.0
@@ -24,6 +25,15 @@ patch bumps are strictly additive.
 [0.19.0]: https://github.com/pjm17971/pond-ts/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/pjm17971/pond-ts/compare/v0.17.1...v0.18.0
 
+## [0.31.1] — 2026-06-28
+
+### Fixed
+
+- **`@pond-ts/charts` and `@pond-ts/fit` now ship their own README** on npm.
+  0.31.0 inadvertently published the `pond-ts` core README on every package
+  (each `prepack` copied the repo-root README); charts and fit now carry their
+  own. No code or API changes.
+
 ## [0.31.0] — 2026-06-28
 
 First published release of **`@pond-ts/charts`** and **`@pond-ts/fit`** (both were

package/README.md

@@ -1,228 +1,68 @@
-# pond-ts
+# @pond-ts/fit
 
-**Highly optimised, fully typed Timeseries library for TypeScript**
+**Fitness & activity analytics on [pond-ts](https://www.npmjs.com/package/pond-ts).**
 
-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.
+Turn raw activity streams (GPS, power, heart rate, cadence, …) into a typed,
+immutable activity model with unit-safe quantities and the analytics you'd
+expect — splits, power (NP / IF / TSS / curve), zones, elevation, best efforts —
+behind a small `Activity` / `Section` façade.
 
 ```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.
+npm install @pond-ts/fit pond-ts
 ```
 
-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.
+`pond-ts` is a peer dependency.
 
-## Quick start: live (streaming)
+## Quick start
 
 ```ts
-import { LiveSeries, Sequence } from 'pond-ts';
+import { Activity, Distance } from '@pond-ts/fit';
 
-// 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
-});
+// `imported` is an ImportedActivity — your raw streams (time, lat/lon, power, hr, …)
+const activity = Activity.fromStreams(imported);
 
-// 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();
+activity.summary(); // { distance, duration, elevation, avg/max metrics, … }
+activity.splits(Distance.km(1)); // per-kilometre Section[]
+activity.power(260); // PowerSummary at FTP 260 W — NP, IF, TSS, curve, zones
 ```
 
-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:
+Attach an athlete `Profile` for zone-aware, type-safe analytics — the
+`ProfiledActivity` knows the athlete, so power/zone calls need no thresholds
+passed in:
 
 ```ts
-const perHost = cpu
-  .partitionBy('host')
-  .rolling('5m', { cpu: 'avg', cpu_sd: 'stdev' });
+import { Profile } from '@pond-ts/fit';
 
-// .collect() fans the per-partition outputs back into a flat TimeSeries
-// with the partition key auto-injected as a column.
-const flat = perHost.collect();
+const profiled = activity.usingProfile(
+  Profile.of({ ftpWatts: 260, weightKg: 72 }),
+);
+profiled.power(); // zone-aware — FTP comes from the profile
+profiled.splits(Distance.km(1)); // ProfiledSection[] — slices carry the profile through
 ```
 
-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`:
+Quantities are unit-safe and format themselves:
 
 ```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:
+import { Speed } from '@pond-ts/fit';
 
-```ts
-const points = series.sample({ reservoir: { size: 500 } }).toRows();
-// 500 uncorrelated points drawn uniformly from the source.
+Speed.mps(5.5).format('imperial'); // "12.3 mph"
 ```
 
-## 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:
+## What's in the box
 
-```sh
-npm run build && node packages/core/bench/vs-pondjs.cjs
-```
+- **Façade** — `Activity` / `Section`: load once, then ask for summary / splits /
+  laps / ranges.
+- **Quantities** — `Distance` / `Speed` / `Pace` / `Power` / `HeartRate` /
+  `Cadence` / … with unit conversions and `.format()`.
+- **Analytics** — geo (distance, elevation, best efforts), power (NP / IF / TSS /
+  curve), and zone distributions.
+- **Profiles** — `Profile` + `usingProfile()` → type-safe `ProfiledActivity` /
+  `ProfiledSection`.
 
 ## 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/`.
+Guides and the full API live at **<https://pjm17971.github.io/pond-ts/>**.
+Source and issues: [github.com/pjm17971/pond-ts](https://github.com/pjm17971/pond-ts).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/fit",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "private": false,
   "description": "Fitness & activity domain library on pond-ts — quantities, canonical activity series, and analytics (geo, power, zones, splits)",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "build": "tsc -p tsconfig.json",
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
-    "prepack": "cp ../../README.md ./README.md && cp ../../LICENSE ./LICENSE && cp ../../CHANGELOG.md ./CHANGELOG.md && npm run build && cp cjs-fallback.cjs dist/cjs-fallback.cjs && find dist -name '*.map' -delete",
+    "prepack": "cp ../../LICENSE ./LICENSE && cp ../../CHANGELOG.md ./CHANGELOG.md && npm run build && cp cjs-fallback.cjs dist/cjs-fallback.cjs && find dist -name '*.map' -delete",
     "test": "npm run test:type && npm run test:runtime",
     "test:type": "tsc -p tsconfig.types.json",
     "test:runtime": "vitest run",