pond-ts 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -7,7 +7,9 @@ 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.25.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
 [0.23.0]: https://github.com/pjm17971/pond-ts/compare/v0.22.0...v0.23.0
@@ -19,6 +21,42 @@ type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [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
+
+- **`rolling(...)` now builds its output columns directly instead of
+  materializing events.** The rolling family was the last batch operator still
+  assembling a row per event and re-validating/re-packing it through the
+  constructor; it now reads the key axis and source values straight off the
+  columnar store and writes the result columns via trusted construction. The
+  result is unchanged for the common (scalar) cases. Measured: `rolling` with
+  `avg`/`sum` ~2.2–2.7× faster; rolling `stdev` on 100k events ~3.3–7.3×
+  (a 1-event window 45.7 ms → 6.3 ms); partitioned rolling ~1.8×.
+  `baseline` / `outliers` (which delegate to `rolling`) inherit the speedup.
+  - **Behavior note — `array` columns:** an identity-comparing reducer (`keep`,
+    or a custom reducer using `===` on the cell) on an `array`-kind source
+    column now compares the value stored in the column, not the original object
+    reference passed at construction. Two rows given the *same* array object
+    therefore read as distinct. Scalar columns (number / string / boolean) are
+    unaffected. A non-finite or wrong-kind reducer result is still rejected with
+    a `ValidationError`, exactly as the constructor's intake did.
+
 ## [0.25.0] — 2026-06-15
 
 ### 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/operators/column-builders.d.ts

@@ -0,0 +1,31 @@
+import { type Column } from '../../columnar/index.js';
+/**
+ * Build a typed {@link Column} from a per-row value array, dispatching on the
+ * column's `kind`. An `undefined` cell becomes missing (its validity bit is
+ * left unset, so `read(i)` returns `undefined`). Numeric arrays reject
+ * non-finite values at construction (`float64ColumnFromArray`) — packed
+ * numeric columns stay NaN-free.
+ *
+ * This is the shared form of the kind→builder dispatch that `fill`
+ * (`buildFilledColumn`), `map` (its inline builder), and `collapse`
+ * (`buildScalarColumn`) each carry a local copy of — flagged there as a
+ * follow-up to converge. Columnar `rolling` is the fourth caller and uses
+ * this one directly; retrofitting the other three onto it is a separate
+ * (optional) cleanup.
+ */
+export declare function columnFromValuesByKind(kind: string, values: unknown[]): Column;
+/**
+ * Throw if any *defined* value fails the column's `kind` contract, mirroring
+ * the constructor's strict intake (`validate.ts`): a `number` must be finite;
+ * `string` / `boolean` must match `typeof`; an `array` must be a real array
+ * whose elements are each a finite number, string, or boolean. `undefined`
+ * (missing) values are allowed.
+ *
+ * Computed-writer paths that assemble via trusted construction bypass intake,
+ * and {@link columnFromValuesByKind}'s `*FromArray` builders silently coerce a
+ * kind mismatch to a *missing* cell — so a caller that must preserve the intake
+ * rejection (e.g. columnar `rolling`, matching `mapColumns`) calls this first.
+ * `label` is prefixed to the thrown message.
+ */
+export declare function assertColumnValuesMatchKind(kind: string, values: ReadonlyArray<unknown>, label: string): void;
+//# sourceMappingURL=column-builders.d.ts.map

package/dist/batch/operators/column-builders.js

@@ -0,0 +1,103 @@
+import { arrayColumnFromArray, booleanColumnFromArray, float64ColumnFromArray, stringColumnFromArray, } from '../../columnar/index.js';
+import { ValidationError } from '../../core/errors.js';
+/**
+ * Build a typed {@link Column} from a per-row value array, dispatching on the
+ * column's `kind`. An `undefined` cell becomes missing (its validity bit is
+ * left unset, so `read(i)` returns `undefined`). Numeric arrays reject
+ * non-finite values at construction (`float64ColumnFromArray`) — packed
+ * numeric columns stay NaN-free.
+ *
+ * This is the shared form of the kind→builder dispatch that `fill`
+ * (`buildFilledColumn`), `map` (its inline builder), and `collapse`
+ * (`buildScalarColumn`) each carry a local copy of — flagged there as a
+ * follow-up to converge. Columnar `rolling` is the fourth caller and uses
+ * this one directly; retrofitting the other three onto it is a separate
+ * (optional) cleanup.
+ */
+export function columnFromValuesByKind(kind, values) {
+    switch (kind) {
+        case 'number':
+            return float64ColumnFromArray(values);
+        case 'string':
+            return stringColumnFromArray(values);
+        case 'boolean':
+            return booleanColumnFromArray(values);
+        case 'array':
+            // ArrayValue cells; the cast is the kind dispatch's trust point.
+            return arrayColumnFromArray(values);
+        default:
+            throw new TypeError(`columnFromValuesByKind: unsupported kind '${kind}'`);
+    }
+}
+/**
+ * Throw if any *defined* value fails the column's `kind` contract, mirroring
+ * the constructor's strict intake (`validate.ts`): a `number` must be finite;
+ * `string` / `boolean` must match `typeof`; an `array` must be a real array
+ * whose elements are each a finite number, string, or boolean. `undefined`
+ * (missing) values are allowed.
+ *
+ * Computed-writer paths that assemble via trusted construction bypass intake,
+ * and {@link columnFromValuesByKind}'s `*FromArray` builders silently coerce a
+ * kind mismatch to a *missing* cell — so a caller that must preserve the intake
+ * rejection (e.g. columnar `rolling`, matching `mapColumns`) calls this first.
+ * `label` is prefixed to the thrown message.
+ */
+export function assertColumnValuesMatchKind(kind, values, label) {
+    for (let i = 0; i < values.length; i += 1) {
+        const v = values[i];
+        if (v === undefined)
+            continue; // missing cell — allowed
+        let ok;
+        switch (kind) {
+            case 'number':
+                ok = typeof v === 'number' && Number.isFinite(v);
+                break;
+            case 'string':
+                ok = typeof v === 'string';
+                break;
+            case 'boolean':
+                ok = typeof v === 'boolean';
+                break;
+            case 'array': {
+                if (!Array.isArray(v)) {
+                    ok = false;
+                    break;
+                }
+                // Indexed loop, NOT `.every` (which skips holes): a sparse array's
+                // hole reads as `undefined`, an invalid element that intake's indexed
+                // scan rejects. Match it exactly so sparse arrays throw here rather
+                // than getting silently coerced to a missing cell by the builder.
+                ok = true;
+                for (let j = 0; j < v.length; j += 1) {
+                    const el = v[j];
+                    if (!((typeof el === 'number' && Number.isFinite(el)) ||
+                        typeof el === 'string' ||
+                        typeof el === 'boolean')) {
+                        ok = false;
+                        break;
+                    }
+                }
+                break;
+            }
+            default:
+                ok = false;
+        }
+        if (!ok) {
+            // `ValidationError` (not `RangeError`) so the failure class matches the
+            // constructor's strict intake — a caller that catches `ValidationError`
+            // for bad user data sees columnar-rolling rejections identically. The
+            // value is stringified defensively: some invalid values (e.g. an array
+            // containing a `Symbol`) throw from `String(...)`, which would mask the
+            // `ValidationError` with a `TypeError`.
+            let shown;
+            try {
+                shown = String(v);
+            }
+            catch {
+                shown = `<unstringifiable ${typeof v}>`;
+            }
+            throw new ValidationError(`${label}: result ${shown} is not a valid '${kind}' value`);
+        }
+    }
+}
+//# sourceMappingURL=column-builders.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.
@@ -900,6 +932,14 @@ export declare class TimeSeries<S extends SeriesSchema> {
      * series carrying multiple entities (host, region, device id), use
      * `series.partitionBy(col).rolling(...).collect()` to scope per
      * entity. See {@link TimeSeries.partitionBy}.
+     *
+     * **`array`-column identity:** the window reads values from the
+     * columnar store, so on an `array`-kind source column an identity-
+     * comparing reducer (`keep`, or a custom reducer using `===` on the
+     * cell) compares the stored cell, not the original object reference
+     * from construction. Two rows that were given the *same* array object
+     * therefore read as distinct values here. Scalar columns
+     * (number / string / boolean) are unaffected (value semantics).
      */
     rolling<const Mapping extends ValidatedAggregateMap<S, Mapping>>(window: DurationInput, mapping: Mapping, options?: {
         alignment?: RollingAlignment;

package/dist/batch/time-series.js

@@ -5,6 +5,8 @@ import { fillOp } from './operators/fill.js';
 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';
@@ -12,7 +14,7 @@ import { TimeRange } from '../core/time-range.js';
 import { compareEventKeys } from '../core/temporal.js';
 import { PartitionedTimeSeries } from './partitioned-time-series.js';
 import { Sequence } from '../sequence/sequence.js';
-import { IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, float64ColumnFromArray, stringColumnFromArray, withColumnsRenamed, withColumnsSelected, withKeyColumn, withRowRange, withRowSelection, } from '../columnar/index.js';
+import { ColumnarStore, IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, float64ColumnFromArray, stringColumnFromArray, withColumnsRenamed, withColumnsSelected, withKeyColumn, withRowRange, withRowSelection, } from '../columnar/index.js';
 import { SeriesStore } from '../live/series-store.js';
 import { parseDuration } from '../core/duration.js';
 import { resolveReducer, bucketStateFor, rollingStateFor, } from '../reducers/index.js';
@@ -1370,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) {
@@ -1979,33 +2012,34 @@ export class TimeSeries {
             this.schema[0],
             ...resultColumnDefs,
         ]);
+        // Columnar output path (3C): read the key + source columns straight off
+        // the store and build the result columns directly — no `this.events`
+        // materialization, no per-row `Event`, no row re-validation/re-pack.
+        const store = this.#store.store;
+        const rowCount = store.length;
+        const sourceCols = columnSpecs.map((spec) => store.columns.get(spec.source));
         const reducerStates = columnSpecs.map((spec) => isBuiltInAggregateReducer(spec.reducer)
             ? createRollingReducerState(spec.reducer)
             : null);
-        const beginTimes = this.events.map((event) => event.begin());
-        const resultRows = new Array(this.events.length);
+        // Begin axis from the key buffer (replaces `this.events.map(e => e.begin())`).
+        const beginTimes = store.keys.begin;
+        // One value accumulator per output column; the result columns are built
+        // from these and assembled via trusted construction below.
+        const outValues = columnSpecs.map(() => new Array(rowCount));
         let windowStart = 0;
         let windowEnd = 0;
         const addEvent = (index) => {
-            const event = this.events[index];
-            const data = event.data();
             for (let i = 0; i < reducerStates.length; i++) {
                 const state = reducerStates[i];
-                if (state) {
-                    const spec = columnSpecs[i];
-                    state.add(index, data[spec.source]);
-                }
+                if (state)
+                    state.add(index, sourceCols[i].read(index));
             }
         };
         const removeEvent = (index) => {
-            const event = this.events[index];
-            const data = event.data();
             for (let i = 0; i < reducerStates.length; i++) {
                 const state = reducerStates[i];
-                if (state) {
-                    const spec = columnSpecs[i];
-                    state.remove(index, data[spec.source]);
-                }
+                if (state)
+                    state.remove(index, sourceCols[i].read(index));
             }
         };
         const snapshotWindow = () => {
@@ -2015,25 +2049,33 @@ export class TimeSeries {
                 const state = reducerStates[i];
                 if (state)
                     return state.snapshot();
-                const values = this.events
-                    .slice(windowStart, windowEnd)
-                    .map((event) => {
-                    const data = event.data();
-                    return data[spec.source];
-                });
+                // Custom reducer: read the window's source values directly off the
+                // column in arrival order — identical value list to the old
+                // `this.events.slice(windowStart, windowEnd)` path.
+                const col = sourceCols[i];
+                const values = [];
+                for (let j = windowStart; j < windowEnd; j++)
+                    values.push(col.read(j));
                 return applyAggregateReducer(spec.reducer, values);
             });
         };
+        // Scatter one window's aggregated values across every row of an equal-key
+        // group (replaces the per-row frozen `[key, ...aggregated]` tuple write).
+        const writeGroup = (groupStart, groupEnd, aggregated) => {
+            for (let index = groupStart; index < groupEnd; index++) {
+                for (let c = 0; c < outValues.length; c++) {
+                    outValues[c][index] = aggregated[c];
+                }
+            }
+        };
         if (alignment === 'trailing') {
-            for (let groupStart = 0; groupStart < this.events.length;) {
+            for (let groupStart = 0; groupStart < rowCount;) {
                 const anchor = beginTimes[groupStart];
                 let groupEnd = groupStart + 1;
-                while (groupEnd < this.events.length &&
-                    beginTimes[groupEnd] === anchor) {
+                while (groupEnd < rowCount && beginTimes[groupEnd] === anchor) {
                     groupEnd += 1;
                 }
-                while (windowEnd < this.events.length &&
-                    beginTimes[windowEnd] <= anchor) {
+                while (windowEnd < rowCount && beginTimes[windowEnd] <= anchor) {
                     addEvent(windowEnd);
                     windowEnd += 1;
                 }
@@ -2043,22 +2085,15 @@ export class TimeSeries {
                     removeEvent(windowStart);
                     windowStart += 1;
                 }
-                const aggregated = snapshotWindow();
-                for (let index = groupStart; index < groupEnd; index++) {
-                    resultRows[index] = Object.freeze([
-                        this.events[index].key(),
-                        ...aggregated,
-                    ]);
-                }
+                writeGroup(groupStart, groupEnd, snapshotWindow());
                 groupStart = groupEnd;
             }
         }
         else if (alignment === 'leading') {
-            for (let groupStart = 0; groupStart < this.events.length;) {
+            for (let groupStart = 0; groupStart < rowCount;) {
                 const anchor = beginTimes[groupStart];
                 let groupEnd = groupStart + 1;
-                while (groupEnd < this.events.length &&
-                    beginTimes[groupEnd] === anchor) {
+                while (groupEnd < rowCount && beginTimes[groupEnd] === anchor) {
                     groupEnd += 1;
                 }
                 const lowerBound = anchor;
@@ -2068,28 +2103,20 @@ export class TimeSeries {
                     windowStart += 1;
                 }
                 const upperBound = anchor + windowMs;
-                while (windowEnd < this.events.length &&
-                    beginTimes[windowEnd] < upperBound) {
+                while (windowEnd < rowCount && beginTimes[windowEnd] < upperBound) {
                     addEvent(windowEnd);
                     windowEnd += 1;
                 }
-                const aggregated = snapshotWindow();
-                for (let index = groupStart; index < groupEnd; index++) {
-                    resultRows[index] = Object.freeze([
-                        this.events[index].key(),
-                        ...aggregated,
-                    ]);
-                }
+                writeGroup(groupStart, groupEnd, snapshotWindow());
                 groupStart = groupEnd;
             }
         }
         else {
             const halfWindow = windowMs / 2;
-            for (let groupStart = 0; groupStart < this.events.length;) {
+            for (let groupStart = 0; groupStart < rowCount;) {
                 const anchor = beginTimes[groupStart];
                 let groupEnd = groupStart + 1;
-                while (groupEnd < this.events.length &&
-                    beginTimes[groupEnd] === anchor) {
+                while (groupEnd < rowCount && beginTimes[groupEnd] === anchor) {
                     groupEnd += 1;
                 }
                 const lowerBound = anchor - halfWindow;
@@ -2099,26 +2126,36 @@ export class TimeSeries {
                     windowStart += 1;
                 }
                 const upperBound = anchor + halfWindow;
-                while (windowEnd < this.events.length &&
-                    beginTimes[windowEnd] < upperBound) {
+                while (windowEnd < rowCount && beginTimes[windowEnd] < upperBound) {
                     addEvent(windowEnd);
                     windowEnd += 1;
                 }
-                const aggregated = snapshotWindow();
-                for (let index = groupStart; index < groupEnd; index++) {
-                    resultRows[index] = Object.freeze([
-                        this.events[index].key(),
-                        ...aggregated,
-                    ]);
-                }
+                writeGroup(groupStart, groupEnd, snapshotWindow());
                 groupStart = groupEnd;
             }
         }
-        return new TimeSeries({
-            name: this.name,
-            schema: resultSchema,
-            rows: resultRows,
-        });
+        // Assemble the result columns from the per-column accumulators and wrap via
+        // trusted construction — the key column passes through zero-copy, and there
+        // is no row re-validation / re-pack (the win this path exists for).
+        const outColumns = new Map();
+        for (let c = 0; c < columnSpecs.length; c++) {
+            const kind = resultColumnDefs[c].kind;
+            const values = outValues[c];
+            // The old event-based path re-packed via the constructor's strict intake,
+            // which rejected any defined result that didn't match the declared output
+            // kind — a non-finite number (a `sum` overflow), or a wrong-typed value
+            // (a custom reducer / `kind` override producing a string for a number
+            // column, etc.). Trusted construction skips intake, and the `*FromArray`
+            // builders silently coerce a kind mismatch to a *missing* cell — so
+            // re-assert the same contract here (same value rules AND the same
+            // `ValidationError` class as intake), keeping packed columns clean.
+            // Missing cells (`undefined`, e.g. the minSamples warm-up) are
+            // unaffected. (#225 Codex finding.)
+            assertColumnValuesMatchKind(kind, values, `rolling column '${columnSpecs[c].output}'`);
+            outColumns.set(columnSpecs[c].output, columnFromValuesByKind(kind, values));
+        }
+        const outStore = ColumnarStore.fromTrustedStore(resultSchema, store.keys, outColumns);
+        return TimeSeries.#fromTrustedStore(this.name, resultSchema, outStore);
     }
     /**
      * Example: `series.smooth("value", "ema", { alpha: 0.2 })`.

package/package.json

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