pond-ts 0.68.0 → 0.70.0

package/README.md

@@ -1,21 +1,44 @@
 # pond-ts
 
+[![npm](https://img.shields.io/npm/v/pond-ts?label=pond-ts)](https://www.npmjs.com/package/pond-ts)
+[![CI](https://github.com/pond-ts/pond/actions/workflows/ci.yml/badge.svg)](https://github.com/pond-ts/pond/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/npm/l/pond-ts)](https://github.com/pond-ts/pond/blob/main/LICENSE)
+[![docs](https://img.shields.io/badge/docs-pond--ts.org-1f6feb)](https://pond-ts.org)
+
 **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.
+ingest, multi-entity partitioning — and, optionally, React hooks and
+canvas charts that read the series directly. 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.
 
+## The packages
+
+Three packages carry most projects. The core has no dependency on the other
+two; add them only if you render.
+
+| Package                                                                           | What it is                                                                                                                                                                                         | Needs                                    |
+| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| **[`pond-ts`](https://www.npmjs.com/package/pond-ts)** — core                     | `TimeSeries` (batch) and `LiveSeries` (streaming) with one operator vocabulary: aggregate, rolling, align, fill, partition, join, typed columns. Node or browser, no React.                        | nothing                                  |
+| **[`@pond-ts/charts`](https://www.npmjs.com/package/@pond-ts/charts)** — optional | Declarative React charts on a canvas data plane that consume a pond series with no adapter: line, area, band, bar, scatter, box, candlestick, heat map; cursors, selection, pan/zoom, annotations. | `pond-ts`, `@pond-ts/react`, React 18/19 |
+| **[`@pond-ts/react`](https://www.npmjs.com/package/@pond-ts/react)** — optional   | Hooks to own a series in a component and read live views on a throttled snapshot cadence (`useLiveSeries`, `useSnapshot`, …).                                                                      | `pond-ts`, React 18/19                   |
+
 ```sh
-npm install pond-ts                 # core
-npm install @pond-ts/react          # React hooks (optional)
+npm install pond-ts                                   # core — enough for Node pipelines and non-React apps
+npm install @pond-ts/charts @pond-ts/react pond-ts    # add the React chart stack
 ```
 
+Two domain packages ([`@pond-ts/financial`](#domain-packages) for markets,
+[`@pond-ts/fit`](#domain-packages) for activity data) and one experimental
+runtime ([`@pond-ts/process`](#domain-packages)) sit on top — see
+[Domain packages](#domain-packages) below. All six release together under
+one version; keep them in step.
+
 - **Typed schemas** — declare once, every transform downstream narrows
   off it. `event.get('cpu')` returns `number | undefined` straight from
   the schema; no `as` casts.
@@ -108,6 +131,43 @@ The full live surface (`filter`, `map`, `select`, `window`, `aggregate`,
 `sample`) is incremental — events flow, views emit, retention bounds
 memory.
 
+## Quick start: charts (React)
+
+`@pond-ts/charts` reads a `TimeSeries` or `LiveSeries` directly — do the maths
+in pond, hand the result to a layer. Rows share one x scale, so they pan,
+zoom and track the cursor together.
+
+```tsx
+import {
+  BandChart,
+  ChartContainer,
+  ChartRow,
+  Layers,
+  LineChart,
+  YAxis,
+} from '@pond-ts/charts';
+
+// `bands` is the baseline() result from the batch quick start:
+// cpu + avg / sd / upper / lower columns.
+export function CpuChart({ width }: { width: number }) {
+  return (
+    <ChartContainer width={width} cursor="crosshair" panZoom>
+      <ChartRow height={240}>
+        <YAxis id="cpu" format=".0%" />
+        <Layers>
+          <BandChart series={bands} lower="lower" upper="upper" axis="cpu" />
+          <LineChart series={bands} column="cpu" axis="cpu" />
+        </Layers>
+      </ChartRow>
+    </ChartContainer>
+  );
+}
+```
+
+Pass `width="auto"` to measure the parent instead. Live data renders through
+the same layers: own the series with `useLiveSeries` from `@pond-ts/react`
+and pass its snapshot as `series`.
+
 ## Quick start: multi-entity
 
 `partitionBy` routes events into per-key buffers. Every stateful
@@ -182,6 +242,26 @@ it is behind. Run locally:
 npm run build && node packages/core/bench/vs-pondjs.cjs
 ```
 
+## Domain packages
+
+Optional, domain-specific, all on plain pond series:
+
+- **[`@pond-ts/financial`](https://www.npmjs.com/package/@pond-ts/financial)**
+  — sixty-plus oracle-verified technical studies (SMA, EMA, RSI, MACD,
+  Bollinger, ATR, VWAP, …) that append columns to a bar series, a fluent
+  `bars.sma({ period: 20 }).rsi({ period: 14 })` form, and a
+  `TradingCalendar` so session-aligned bars, rolling windows and chart axes
+  stop at the close.
+- **[`@pond-ts/fit`](https://www.npmjs.com/package/@pond-ts/fit)** — fitness
+  and activity analytics: typed quantities with units, canonical activity
+  series, geo (distance, elevation, best efforts), power (NP / IF / TSS,
+  curves), heart-rate zones, splits.
+- **[`@pond-ts/process`](https://www.npmjs.com/package/@pond-ts/process)** —
+  **experimental.** Computations as data: processing graphs authored fluently
+  or composed as JSON, resolved against a declared op vocabulary with
+  content-addressed caching, provenance and per-node timings. The API is
+  expected to move.
+
 ## Documentation
 
 The full guide is at **<https://pond-ts.org/>**.
@@ -233,20 +313,22 @@ the loop:
 
 ## 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
+The repo is an npm-workspaces monorepo with six published packages
+(`pond-ts`, `@pond-ts/react`, `@pond-ts/charts`, `@pond-ts/financial`,
+`@pond-ts/fit`, `@pond-ts/process`). Node 18+ for runtime; Node 20+ for the
 docs site (Docusaurus).
 
 ```sh
-npm install         # one-time, hoists deps for both packages
+npm install         # one-time, hoists deps for all 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/`.
+Each package lives under `packages/<name>/` (`core` is `pond-ts`, the rest
+match their scoped names). Docs live in `website/` — its own npm root, not a
+workspace.
 
 ## License
 

package/dist/batch/partitioned-time-series.d.ts

@@ -4,7 +4,7 @@ import { Sequence } from '../sequence/sequence.js';
 import type { DurationInput } from '../core/duration.js';
 import type { TemporalLike } from '../core/temporal.js';
 import type { BatchSampleStrategy } from '../sequence/sample.js';
-import type { AggregateSchema, AlignSchema, AppendColumn, BaselineSchema, DedupeKeep, DiffSchema, EventDataForSchema, FillMapping, FillStrategy, MaterializeSchema, NumericColumnNameForSchema, RollingAlignment, RollingSchema, SeriesSchema, SmoothAppendSchema, SmoothMethod, SmoothSchema, ValidatedAggregateMap } from '../schema/index.js';
+import type { AggregateSchema, AlignSchema, AppendColumn, BaselineSchema, DedupeKeep, DiffSchema, EventDataForSchema, ValueColumnsForSchema, FillMapping, FillStrategy, MaterializeSchema, NumericColumnNameForSchema, RollingAlignment, RollingSchema, SeriesSchema, SmoothAppendSchema, SmoothMethod, SmoothSchema, ValidatedAggregateMap } from '../schema/index.js';
 import type { ScanStep } from './operators/scan.js';
 type SequenceLike = Sequence | BoundedSequence;
 type AlignMethod = 'hold' | 'linear';
@@ -24,7 +24,7 @@ type AlignSample = 'begin' | 'center' | 'end';
  * the one actually passed — harmless because injected columns are already
  * optional.
  */
-export type WithPartitionColumns<Mapping, By extends string> = string extends By ? Mapping : Mapping & {
+export type WithPartitionColumns<S extends SeriesSchema, Mapping, By extends string> = string extends By ? Mapping : string extends ValueColumnsForSchema<S>[number]['name'] ? Mapping : Mapping & {
     readonly [C in Exclude<By, keyof Mapping>]: 'first';
 };
 /**
@@ -74,6 +74,22 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
     #private;
     readonly source: TimeSeries<S>;
     readonly by: ReadonlyArray<keyof EventDataForSchema<S> & string>;
+    /**
+     * Phantom, erased at runtime. Pins `By` **contravariantly** so a view
+     * partitioned by one column cannot be assigned where a view partitioned
+     * by another is claimed (`PartitionedTimeSeries<S, K, 'host'>` ←
+     * `partitionBy('region')` is an error), while a specialised view still
+     * assigns to the legacy `PartitionedTimeSeries<S>` / `<S, K>` shape.
+     * Without it `By` only appears inside a conditional in return positions
+     * and TypeScript treats it as freely convertible (Codex finding on #724).
+     *
+     * Spelling note: **`never` (the default) is the "any / unknown column"
+     * view**, and it is the top of this pin — every specialised view assigns
+     * to it. `string` is the *bottom* (a `string`-typed `By` assigns to any
+     * literal), so do not write `PartitionedTimeSeries<S, K, string>` to mean
+     * "any column"; the `partitionBy` overloads never produce it.
+     */
+    readonly __partitionColumns?: (by: By) => void;
     /**
      * Declared partition values when `partitionBy(col, { groups })` was
      * used. When set, `toMap` iterates in declared order (not insertion
@@ -266,13 +282,13 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
     rolling<const Mapping extends ValidatedAggregateMap<S, Mapping>>(window: DurationInput, mapping: Mapping, options?: {
         alignment?: RollingAlignment;
         minSamples?: number;
-    }): PartitionedTimeSeries<RollingSchema<S, WithPartitionColumns<Mapping, By>>, K, By>;
+    }): PartitionedTimeSeries<RollingSchema<S, WithPartitionColumns<S, Mapping, By>>, K, By>;
     rolling<const Mapping extends ValidatedAggregateMap<S, Mapping>>(sequence: SequenceLike, window: DurationInput, mapping: Mapping, options?: {
         alignment?: RollingAlignment;
         sample?: AlignSample;
         range?: TemporalLike;
         minSamples?: number;
-    }): PartitionedTimeSeries<AggregateSchema<S, WithPartitionColumns<Mapping, By>>, K, By>;
+    }): PartitionedTimeSeries<AggregateSchema<S, WithPartitionColumns<S, Mapping, By>>, K, By>;
     /** Per-partition `smooth`. See {@link TimeSeries.smooth}. */
     smooth<const Target extends NumericColumnNameForSchema<S>, const Output extends string | undefined = undefined>(column: Target, method: SmoothMethod, options: {
         alpha: number;
@@ -332,7 +348,7 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
     /** Per-partition `aggregate`. See {@link TimeSeries.aggregate}. */
     aggregate<const Mapping extends ValidatedAggregateMap<S, Mapping>>(sequence: SequenceLike, mapping: Mapping, options?: {
         range?: TemporalLike;
-    }): PartitionedTimeSeries<AggregateSchema<S, WithPartitionColumns<Mapping, By>>, K, By>;
+    }): PartitionedTimeSeries<AggregateSchema<S, WithPartitionColumns<S, Mapping, By>>, K, By>;
 }
 export {};
 //# sourceMappingURL=partitioned-time-series.d.ts.map

package/dist/core/calendar.d.ts

@@ -1,5 +1,5 @@
-import { Temporal } from '@js-temporal/polyfill';
-export type CalendarUnit = 'day' | 'week' | 'month';
+/** A calendar bucket unit. Boundaries are wall-clock in an IANA zone, so a `'day'` is 23, 24 or 25 hours across DST. */
+export type CalendarUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
 export type WeekStartsOn = 1 | 2 | 3 | 4 | 5 | 6 | 7;
 export type TimeZoneOptions = {
     timeZone?: string;
@@ -10,9 +10,6 @@ export type CalendarOptions = TimeZoneOptions & {
 export declare function resolveTimeZone(options?: TimeZoneOptions): string;
 export declare function normalizeWeekStartsOn(value: number | undefined): WeekStartsOn;
 export declare function parseTimestampString(value: string, options?: TimeZoneOptions): number;
-export declare function toPlainDateStart(instantMs: number, timeZone: string, unit: CalendarUnit, weekStartsOn: WeekStartsOn): Temporal.PlainDate;
-export declare function plainDateToStart(date: Temporal.PlainDate, timeZone: string): Temporal.ZonedDateTime;
-export declare function nextCalendarStart(current: Temporal.PlainDate, unit: CalendarUnit): Temporal.PlainDate;
 export declare function dayRangeForDate(reference: string, options?: TimeZoneOptions): {
     start: number;
     end: number;

package/dist/core/calendar.js

@@ -1,4 +1,5 @@
 import { Temporal } from '@js-temporal/polyfill';
+import { TimeZone } from './time-zone.js';
 const DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
 const YEAR_MONTH_RE = /^\d{4}-\d{2}$/;
 const DATE_TIME_LOCAL_RE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?$/;
@@ -42,51 +43,6 @@ export function parseTimestampString(value, options = {}) {
     }
     return Temporal.Instant.from(value).epochMilliseconds;
 }
-export function toPlainDateStart(instantMs, timeZone, unit, weekStartsOn) {
-    // **Floor to the containing millisecond.** `Temporal.Instant` refuses a
-    // fractional epoch ms outright — `fromEpochMilliseconds(1577836800000.37)`
-    // throws `epoch milliseconds must be an integer` — and a fraction is not a
-    // caller error here. A chart's wheel-zoom derives its view range from pixel
-    // positions through `xScale.invert()`, so a perfectly ordinary gesture hands
-    // us `1.7e12 + 0.37`; realizing a calendar sequence over that range then
-    // crashed the page outright.
-    //
-    // Flooring is the only sane reading rather than a papering-over: the epoch
-    // millisecond *is* the atomic unit of this model, so an over-precise input
-    // can only mean the millisecond containing it, and calendar boundaries are
-    // themselves whole milliseconds — so the bucket containing `t` and the one
-    // containing `t + 0.37` are necessarily the same. Integer inputs are
-    // untouched.
-    //
-    // `Math.floor`, not `Math.trunc`: before 1970 they disagree, and `-5.5` lies
-    // inside the millisecond spanning `[-6, -5)`, which is `-6`.
-    const zoned = Temporal.Instant.fromEpochMilliseconds(Math.floor(instantMs)).toZonedDateTimeISO(timeZone);
-    const date = zoned.toPlainDate();
-    if (unit === 'day') {
-        return date;
-    }
-    if (unit === 'month') {
-        return Temporal.PlainDate.from({
-            year: date.year,
-            month: date.month,
-            day: 1,
-        });
-    }
-    const offset = (date.dayOfWeek - weekStartsOn + 7) % 7;
-    return date.subtract({ days: offset });
-}
-export function plainDateToStart(date, timeZone) {
-    return date.toZonedDateTime({ timeZone }).startOfDay();
-}
-export function nextCalendarStart(current, unit) {
-    if (unit === 'day') {
-        return current.add({ days: 1 });
-    }
-    if (unit === 'week') {
-        return current.add({ weeks: 1 });
-    }
-    return current.add({ months: 1 });
-}
 export function dayRangeForDate(reference, options = {}) {
     const timeZone = resolveTimeZone(options);
     const start = Temporal.PlainDate.from(reference)
@@ -102,12 +58,10 @@ export function calendarRangeForReference(unit, reference, options = {}) {
     const timeZone = resolveTimeZone(options);
     const weekStartsOn = normalizeWeekStartsOn(options.weekStartsOn);
     const referenceMs = parseTimestampString(reference, { timeZone });
-    const startDate = toPlainDateStart(referenceMs, timeZone, unit, weekStartsOn);
-    const start = plainDateToStart(startDate, timeZone);
-    const end = plainDateToStart(nextCalendarStart(startDate, unit), timeZone);
+    const zone = TimeZone.of(timeZone);
     return {
-        start: start.epochMilliseconds,
-        end: end.epochMilliseconds,
+        start: zone.startOf(unit, referenceMs, { weekStartsOn }),
+        end: zone.next(unit, referenceMs, { weekStartsOn }),
     };
 }
 //# sourceMappingURL=calendar.js.map

package/dist/core/index.d.ts

@@ -6,4 +6,6 @@ export type { DurationInput, DurationUnit } from './duration.js';
 export { ValidationError } from './errors.js';
 export type { EventKey, IntervalInput, IntervalValue, TemporalLike, TimeRangeInput, TimestampInput, } from './temporal.js';
 export type { CalendarOptions, CalendarUnit, TimeZoneOptions, } from './calendar.js';
+export { TimeZone } from './time-zone.js';
+export type { Disambiguation, StartOfOptions, ZonedParts, ZonedPartsInput, } from './time-zone.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -3,4 +3,5 @@ export { Interval } from './interval.js';
 export { Time } from './time.js';
 export { TimeRange, toTimeRange } from './time-range.js';
 export { ValidationError } from './errors.js';
+export { TimeZone } from './time-zone.js';
 //# sourceMappingURL=index.js.map

package/dist/core/time-zone.d.ts

@@ -0,0 +1,122 @@
+import type { CalendarUnit, WeekStartsOn } from './calendar.js';
+/**
+ * How `TimeZone.instant()` resolves a wall-clock time that a transition
+ * makes ambiguous (a fall-back repeats an hour) or skips (a spring-forward
+ * drops one). Same vocabulary and same defaults as Temporal:
+ *
+ * - `'compatible'` (default) — the earlier instant when the time repeats,
+ *   the instant *after* the gap when it is skipped (02:30 on a spring-forward
+ *   night becomes 03:30). This is also what `startOf('day')` needs on the
+ *   rare days that have no midnight.
+ * - `'earlier'` / `'later'` — always the earlier / later of the two readings.
+ * - `'reject'` — throw a `RangeError` for either case.
+ */
+export type Disambiguation = 'compatible' | 'earlier' | 'later' | 'reject';
+/** The wall-clock reading of an instant in a zone. `weekday` is ISO: 1 = Monday … 7 = Sunday. */
+export type ZonedParts = {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    millisecond: number;
+    weekday: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+};
+/** The date-and-time fields `TimeZone.instant()` accepts. Time fields default to zero. */
+export type ZonedPartsInput = {
+    year: number;
+    month: number;
+    day: number;
+    hour?: number;
+    minute?: number;
+    second?: number;
+    millisecond?: number;
+};
+export type StartOfOptions = {
+    /** First day of the week for `'week'`, ISO numbering (1 = Monday, default) … 7 = Sunday. */
+    weekStartsOn?: WeekStartsOn;
+};
+declare function assertCalendarUnit(unit: string): asserts unit is CalendarUnit;
+/**
+ * An IANA time zone as a calendar: the one place in pond that turns instants
+ * (UTC epoch milliseconds) into wall-clock readings and calendar boundaries,
+ * and back.
+ *
+ * Instances are interned — `TimeZone.of('Europe/Berlin')` returns the same
+ * object every time — and cache the zone's offset transitions as they are
+ * discovered, so after the first query in a stretch of history every call
+ * is integer arithmetic. `Sequence.calendar` buckets with it; the charts'
+ * time axis places and labels ticks with it; the two therefore agree on
+ * every boundary by construction.
+ *
+ * A `TimeZone` holds no instant. Values (`Time`, `TimeRange`, `Interval`)
+ * stay plain UTC milliseconds; the zone is a parameter to the code that
+ * interprets them.
+ */
+export declare class TimeZone {
+    #private;
+    /** The canonical IANA identifier, e.g. `'America/New_York'` or `'UTC'`. */
+    readonly id: string;
+    private constructor();
+    /**
+     * Example: `TimeZone.of('Australia/Sydney')`. Looks up a zone by IANA
+     * identifier. Throws `RangeError` for an identifier the runtime does not
+     * know. Case-insensitive on input; `id` reports the canonical spelling.
+     * A fixed-offset identifier such as `'+05:30'` is accepted too, as
+     * Temporal accepts it, and behaves as a zone with a single segment.
+     */
+    static of(id: string): TimeZone;
+    /** Example: `TimeZone.UTC.startOf('month', t)`. The UTC zone. */
+    static get UTC(): TimeZone;
+    /**
+     * Example: `TimeZone.local()`. The runtime's own zone, as the environment
+     * reports it. Resolved on every call, so a test that changes `TZ` between
+     * calls sees the change.
+     */
+    static local(): TimeZone;
+    /** Example: `zone.offsetAt(t)`. The zone's UTC offset at an instant, in milliseconds east of UTC. */
+    offsetAt(ms: number): number;
+    /**
+     * Example: `zone.parts(t).hour`. The wall-clock reading of an instant in
+     * this zone.
+     */
+    parts(ms: number): ZonedParts;
+    /**
+     * Example: `zone.instant({ year: 2026, month: 3, day: 29, hour: 2, minute: 30 })`.
+     * The instant at which this zone's clocks read the given wall time. When
+     * a transition makes the reading ambiguous or nonexistent,
+     * `disambiguation` decides (default `'compatible'`, as Temporal).
+     */
+    instant(parts: ZonedPartsInput, options?: {
+        disambiguation?: Disambiguation;
+    }): number;
+    /**
+     * Example: `zone.startOf('week', t, { weekStartsOn: 7 })`. The first
+     * instant of the calendar unit containing `ms`, in this zone. On a day
+     * with no midnight (a spring-forward at 00:00) this is the first instant
+     * that exists, as `Temporal.ZonedDateTime.startOfDay` does.
+     */
+    startOf(unit: CalendarUnit, ms: number, options?: StartOfOptions): number;
+    /**
+     * Example: `zone.next('month', t)`. The first instant of the calendar unit
+     * *after* the one containing `ms` — i.e. the exclusive end of `startOf`'s
+     * bucket.
+     */
+    next(unit: CalendarUnit, ms: number, options?: StartOfOptions): number;
+    /**
+     * Example: `zone.abbreviation(t)` → `'EDT'`. The zone's short name at an
+     * instant, as `Intl` reports it for `locale` (default: the runtime's
+     * locale). Which zones have a conventional abbreviation is a locale
+     * question — `en-US` knows `EST`, `en-AU` knows `AEDT`, and neither knows
+     * the other's; the fallback is a `GMT±h[:mm]` offset string. Pass the
+     * viewer's locale when rendering.
+     */
+    abbreviation(ms: number, options?: {
+        locale?: string;
+    }): string;
+    toString(): string;
+    toJSON(): string;
+}
+export { assertCalendarUnit };
+//# sourceMappingURL=time-zone.d.ts.map