pond-ts 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -7,7 +7,8 @@ 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.26.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.27.0...HEAD
+[0.27.0]: https://github.com/pjm17971/pond-ts/compare/v0.26.0...v0.27.0
 [0.26.0]: https://github.com/pjm17971/pond-ts/compare/v0.25.0...v0.26.0
 [0.25.0]: https://github.com/pjm17971/pond-ts/compare/v0.24.0...v0.25.0
 [0.24.0]: https://github.com/pjm17971/pond-ts/compare/v0.23.0...v0.24.0
@@ -20,7 +21,22 @@ type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
-## [0.26.0] — 2026-06-15
+## [0.27.0] — 2026-06-16
+
+### Added
+
+- **`TimeSeries.byColumn(col, { width, origin? } | { edges }, mapping)` —
+  value-axis aggregation.** Where `aggregate` buckets the temporal key,
+  `byColumn` buckets rows by the **value** of a numeric column and reduces each
+  bin, returning an ordered array of `{ start, end, ...aggregates }` records
+  (one per bin) — not a `TimeSeries`, since value-bins (distance / power ranges)
+  aren't time-indexed. `{ width }` gives even bins emitted contiguously from the
+  lowest to highest occupied bin (monotonic source → splits / profile;
+  non-monotonic → histogram); `{ edges }` gives explicit ascending bins (e.g.
+  power zones). Reuses the reducer mapping + non-finite policy. Rows whose bin
+  value is missing / non-finite (or, for `edges`, out of range) are dropped;
+  empty bins emit the reducer's empty value; a non-finite / wrong-kind reducer
+  result throws `ValidationError`. See `docs/notes/bycolumn-value-axis.md`.
 
 ### Changed
 

package/dist/batch/by-column.d.ts

@@ -0,0 +1,29 @@
+import type { ColumnSchema, ColumnarStore } from '../columnar/index.js';
+import type { ColumnValue } from '../schema/index.js';
+import type { AggregateColumnSpec } from './aggregate-columns.js';
+/**
+ * Binning for {@link TimeSeries.byColumn}: even-`width` bins (optionally shifted
+ * by `origin`, default 0) or explicit ascending `edges`. See
+ * `docs/notes/bycolumn-value-axis.md`.
+ */
+export type BinSpec = {
+    width: number;
+    origin?: number;
+} | {
+    edges: readonly number[];
+};
+/** One value-bin's record: its `[start, end)` range plus the mapped aggregates. */
+export type BinRecord = {
+    start: number;
+    end: number;
+} & Record<string, ColumnValue | undefined>;
+/**
+ * Value-axis aggregation runtime. Buckets the store's rows by the value of
+ * `binColName` and reduces each bin via `columnSpecs`, returning one
+ * {@link BinRecord} per bin in ascending order. Reads straight off the columnar
+ * store (no event materialization); rows whose bin value is missing / non-finite
+ * (or, for `edges`, out of range) contribute to no bin. Empty bins emit each
+ * reducer's empty value, like an empty `aggregate` bucket.
+ */
+export declare function computeByColumn(store: ColumnarStore<ColumnSchema>, binColName: string, spec: BinSpec, columnSpecs: ReadonlyArray<AggregateColumnSpec>): BinRecord[];
+//# sourceMappingURL=by-column.d.ts.map

package/dist/batch/by-column.js

@@ -0,0 +1,166 @@
+import { bucketStateFor } from '../reducers/index.js';
+// Guards a `width` spec from an accidental explosion (e.g. a sub-unit width over
+// a huge range) that would allocate millions of empty output records.
+const MAX_WIDTH_BINS = 1_000_000;
+/**
+ * Value-axis aggregation runtime. Buckets the store's rows by the value of
+ * `binColName` and reduces each bin via `columnSpecs`, returning one
+ * {@link BinRecord} per bin in ascending order. Reads straight off the columnar
+ * store (no event materialization); rows whose bin value is missing / non-finite
+ * (or, for `edges`, out of range) contribute to no bin. Empty bins emit each
+ * reducer's empty value, like an empty `aggregate` bucket.
+ */
+export function computeByColumn(store, binColName, spec, columnSpecs) {
+    const binCol = store.columns.get(binColName);
+    if (binCol === undefined) {
+        throw new RangeError(`byColumn: unknown column '${binColName}'`);
+    }
+    if (binCol.kind !== 'number') {
+        throw new TypeError(`byColumn: column '${binColName}' must be a number column (got '${binCol.kind}')`);
+    }
+    // `start` / `end` carry the bin range in every record, so a mapping output
+    // can't claim them (it would silently overwrite the range).
+    for (const s of columnSpecs) {
+        if (s.output === 'start' || s.output === 'end') {
+            throw new RangeError(`byColumn: output name '${s.output}' is reserved for the bin range`);
+        }
+    }
+    const sourceCols = columnSpecs.map((s) => store.columns.get(s.source));
+    const n = store.length;
+    // Resolve the bin assignment + the [start, end) of a given bin index.
+    const usesEdges = 'edges' in spec;
+    let binOf;
+    let rangeOf;
+    if (usesEdges) {
+        const edges = spec.edges;
+        if (edges.length < 2) {
+            throw new RangeError('byColumn: edges must have at least 2 entries');
+        }
+        for (let i = 0; i < edges.length; i += 1) {
+            if (!Number.isFinite(edges[i])) {
+                throw new RangeError(`byColumn: edges[${i}] is not finite`);
+            }
+            if (i > 0 && edges[i] <= edges[i - 1]) {
+                throw new RangeError('byColumn: edges must be strictly ascending');
+            }
+        }
+        const last = edges.length - 1;
+        binOf = (v) => {
+            if (v < edges[0] || v >= edges[last])
+                return NaN; // out of range → drop
+            // rightmost edge <= v, clamped to a valid bin [0, last)
+            let lo = 0;
+            let hi = last; // bins are [0, last)
+            while (lo < hi) {
+                const mid = (lo + hi + 1) >>> 1;
+                if (edges[mid] <= v)
+                    lo = mid;
+                else
+                    hi = mid - 1;
+            }
+            return lo;
+        };
+        rangeOf = (i) => ({ start: edges[i], end: edges[i + 1] });
+    }
+    else {
+        const width = spec.width;
+        const origin = spec.origin ?? 0;
+        if (!Number.isFinite(width) || width <= 0) {
+            throw new RangeError('byColumn: width must be a positive finite number');
+        }
+        if (!Number.isFinite(origin)) {
+            throw new RangeError('byColumn: origin must be finite');
+        }
+        binOf = (v) => {
+            let bin = Math.floor((v - origin) / width);
+            // `floor((v−origin)/width)` (division) and the emitted boundary
+            // `origin + i*width` (multiplication) round independently, so for
+            // fractional widths a value can land just outside its floored bin's
+            // `[start, end)` (e.g. width 0.1, v = −3*0.1 → bin −4 whose end *is* v).
+            // Nudge the bin so `v ∈ [origin + bin*width, origin + (bin+1)*width)` —
+            // a ≤1-step correction for normal inputs. The counter caps the loop so a
+            // collapsed range (origin/width beyond float precision) can't spin; emit's
+            // representability check then rejects that bin.
+            let guard = 0;
+            while (v < origin + bin * width && guard++ < 4)
+                bin -= 1;
+            while (v >= origin + (bin + 1) * width && guard++ < 4)
+                bin += 1;
+            return bin;
+        };
+        rangeOf = (i) => ({
+            start: origin + i * width,
+            end: origin + (i + 1) * width,
+        });
+    }
+    // Scatter: one bucket-state set per occupied bin index.
+    const states = new Map();
+    let minBin = Infinity;
+    let maxBin = -Infinity;
+    for (let i = 0; i < n; i += 1) {
+        const bv = binCol.read(i);
+        if (typeof bv !== 'number' || !Number.isFinite(bv))
+            continue;
+        const bin = binOf(bv);
+        if (Number.isNaN(bin))
+            continue; // edges out-of-range (width bins may be negative)
+        let cells = states.get(bin);
+        if (cells === undefined) {
+            cells = columnSpecs.map((s) => bucketStateFor(s.reducer));
+            states.set(bin, cells);
+        }
+        for (let c = 0; c < columnSpecs.length; c += 1) {
+            cells[c].add(sourceCols[c].read(i));
+        }
+        if (bin < minBin)
+            minBin = bin;
+        if (bin > maxBin)
+            maxBin = bin;
+    }
+    const out = [];
+    const emit = (binIndex) => {
+        const { start, end } = rangeOf(binIndex);
+        // Every emitted bin must be a representable half-open `[start, end)`. A safe
+        // bin INDEX doesn't guarantee representable BOUNDARIES: at extreme
+        // magnitudes `origin + i*width` can collapse (`start === end`, e.g.
+        // origin 1e20 + width 1) or overflow (`end === Infinity`, e.g. width 1e308).
+        // (Edges are pre-validated finite + strictly ascending, so this only ever
+        // fires on a pathological width/origin.)
+        if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) {
+            throw new RangeError(`byColumn: bin [${start}, ${end}) is not a representable range — the origin/width magnitude exceeds float precision; use a larger width or explicit edges`);
+        }
+        const cells = states.get(binIndex);
+        const rec = { start, end };
+        for (let c = 0; c < columnSpecs.length; c += 1) {
+            // Occupied bin → that bin's own accumulated snapshot. Empty bin → a FRESH
+            // empty snapshot per bin (not a cached/shared value): array-kind reducers
+            // would otherwise alias one `[]` across bins, and a custom reducer's empty
+            // is `fn([])` which `aggregate` evaluates per empty bucket — match that.
+            rec[columnSpecs[c].output] = cells
+                ? cells[c].snapshot()
+                : bucketStateFor(columnSpecs[c].reducer).snapshot();
+        }
+        out.push(rec);
+    };
+    if (usesEdges) {
+        const binCount = spec.edges.length - 1;
+        for (let b = 0; b < binCount; b += 1)
+            emit(b);
+    }
+    else if (states.size > 0) {
+        // A finite-but-huge value can floor to a bin index past the safe-integer
+        // range (or to ±Infinity on overflow); the emit loop's `b += 1` would then
+        // never advance. Reject it rather than spin.
+        if (!Number.isSafeInteger(minBin) || !Number.isSafeInteger(maxBin)) {
+            throw new RangeError('byColumn: the data range and width produce a bin index outside the safe integer range; use a larger width');
+        }
+        const binCount = maxBin - minBin + 1;
+        if (binCount > MAX_WIDTH_BINS) {
+            throw new RangeError(`byColumn: width produces ${binCount} bins (> ${MAX_WIDTH_BINS}); use a larger width or explicit edges`);
+        }
+        for (let b = minBin; b <= maxBin; b += 1)
+            emit(b);
+    }
+    return out;
+}
+//# sourceMappingURL=by-column.js.map

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

@@ -1,5 +1,6 @@
 import type { AlignSchema, MaterializeSchema, ArrayAggregateAppendSchema, ArrayAggregateReplaceSchema, ArrayColumnNameForSchema, ArrayExplodeAppendSchema, ArrayExplodeReplaceSchema, BaselineSchema, AggregateReducer, AggregateSchema, CollapseSchema, EventDataForSchema, EventForSchema, FirstColKind, IntervalKeyedSchema, JsonRowFormat, JoinManySchema, JoinSchema, JoinType, NumericColumnNameForSchema, NormalizedObjectRow, NormalizedRowForSchema, PivotByGroupSchema, PointRowForSchema, PrefixedJoinManySchema, PrefixedJoinSchema, ReduceResult, RenameMap, ValidatedAggregateMap } from '../schema/index.js';
 import type { RenameSchema, RollingAlignment, RollingSchema, ColumnValue, DedupeKeep, DiffSchema, FillMapping, FillStrategy, ScalarKind, ScalarValue, SmoothMethod, SmoothAppendSchema, SmoothSchema, SelectSchema, SeriesSchema, TimeKeyedSchema, TimeSeriesJsonInput, TimeSeriesInput, TimeRangeKeyedSchema, ValueColumnKindForName, ValueColumnNameForSchema, ValueColumnsForSchema } from '../schema/index.js';
+import { type BinSpec } from './by-column.js';
 import { BoundedSequence } from '../sequence/bounded-sequence.js';
 import { type TimeZoneOptions } from '../core/calendar.js';
 import { TimeRange } from '../core/time-range.js';
@@ -519,6 +520,37 @@ export declare class TimeSeries<S extends SeriesSchema> {
      */
     reduce(column: ValueColumnsForSchema<S>[number]['name'], reducer: AggregateReducer): ColumnValue | undefined;
     reduce<const Mapping extends ValidatedAggregateMap<S, Mapping>>(mapping: Mapping): ReduceResult<S, Mapping>;
+    /**
+     * Example:
+     * `series.byColumn('cumDist', { width: 1000 }, { gain: { from: 'ele', using: 'sum' } })`.
+     *
+     * **Value-axis aggregation.** Where `aggregate` buckets the temporal key and
+     * `reduce` collapses the whole series to one record, `byColumn` buckets rows
+     * by the **value** of a numeric column and collapses **each value-bin** to one
+     * record. Returns an ordered array of `{ start, end, ...aggregates }` — the
+     * bin's `[start, end)` range plus the mapped reducers — *not* a `TimeSeries`,
+     * because value-bins (distance / power ranges) are not time-indexed.
+     *
+     * Two binning modes:
+     * - `{ width, origin? }` — even-width bins (`origin` defaults to `0`). Bins are
+     *   emitted contiguously from the lowest to the highest occupied bin (interior
+     *   empty bins included), so a histogram / profile has no gaps. A monotonic
+     *   source (cumulative distance / work) yields contiguous ranges (per-km
+     *   splits, elevation-vs-distance profile); a non-monotonic source (power)
+     *   yields a histogram (distribution).
+     * - `{ edges }` — explicit ascending edges `[e₀ … eₙ]` → `n` bins, bin `i` =
+     *   `[eᵢ, eᵢ₊₁)` (e.g. FTP / Coggan power zones). Always emits all `n` bins.
+     *
+     * A row whose bin value is missing / non-finite (or, for `edges`, outside
+     * `[e₀, eₙ)`) contributes to no bin. The reducer non-finite policy still
+     * applies to the *source* columns. Empty bins emit each reducer's empty value
+     * (`count` → 0, `avg` / `min` / … → `undefined`), like an empty `aggregate`
+     * bucket. See `docs/notes/bycolumn-value-axis.md`.
+     */
+    byColumn<const Mapping extends ValidatedAggregateMap<S, Mapping>>(col: NumericColumnNameForSchema<S>, spec: BinSpec, mapping: Mapping): Array<{
+        start: number;
+        end: number;
+    } & ReduceResult<S, Mapping>>;
     /**
      * Example: `series.groupBy("host")`.
      * Partitions the series into groups keyed by the distinct values of a payload column.

package/dist/batch/time-series.js

@@ -6,6 +6,7 @@ import { mapOp } from './operators/map.js';
 import { shiftOp } from './operators/shift.js';
 import { collapseOp } from './operators/collapse.js';
 import { assertColumnValuesMatchKind, columnFromValuesByKind, } from './operators/column-builders.js';
+import { computeByColumn } from './by-column.js';
 import { BoundedSequence } from '../sequence/bounded-sequence.js';
 import { Interval } from '../core/interval.js';
 import { Time } from '../core/time.js';
@@ -1371,6 +1372,37 @@ export class TimeSeries {
         }
         return result;
     }
+    /**
+     * Example:
+     * `series.byColumn('cumDist', { width: 1000 }, { gain: { from: 'ele', using: 'sum' } })`.
+     *
+     * **Value-axis aggregation.** Where `aggregate` buckets the temporal key and
+     * `reduce` collapses the whole series to one record, `byColumn` buckets rows
+     * by the **value** of a numeric column and collapses **each value-bin** to one
+     * record. Returns an ordered array of `{ start, end, ...aggregates }` — the
+     * bin's `[start, end)` range plus the mapped reducers — *not* a `TimeSeries`,
+     * because value-bins (distance / power ranges) are not time-indexed.
+     *
+     * Two binning modes:
+     * - `{ width, origin? }` — even-width bins (`origin` defaults to `0`). Bins are
+     *   emitted contiguously from the lowest to the highest occupied bin (interior
+     *   empty bins included), so a histogram / profile has no gaps. A monotonic
+     *   source (cumulative distance / work) yields contiguous ranges (per-km
+     *   splits, elevation-vs-distance profile); a non-monotonic source (power)
+     *   yields a histogram (distribution).
+     * - `{ edges }` — explicit ascending edges `[e₀ … eₙ]` → `n` bins, bin `i` =
+     *   `[eᵢ, eᵢ₊₁)` (e.g. FTP / Coggan power zones). Always emits all `n` bins.
+     *
+     * A row whose bin value is missing / non-finite (or, for `edges`, outside
+     * `[e₀, eₙ)`) contributes to no bin. The reducer non-finite policy still
+     * applies to the *source* columns. Empty bins emit each reducer's empty value
+     * (`count` → 0, `avg` / `min` / … → `undefined`), like an empty `aggregate`
+     * bucket. See `docs/notes/bycolumn-value-axis.md`.
+     */
+    byColumn(col, spec, mapping) {
+        const columnSpecs = normalizeAggregateColumns(this.schema, mapping);
+        return computeByColumn(this.#store.store, col, spec, columnSpecs);
+    }
     groupBy(column, transform) {
         const buckets = new Map();
         for (const event of this.events) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pond-ts",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "TypeScript-first time series primitives",
   "license": "MIT",
   "repository": {