pond-ts 0.71.0 → 0.72.0

package/CHANGELOG.md

@@ -8,7 +8,8 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 under a single `v*` tag, so this file covers them all. Pre-1.0: minor bumps may
 include new features and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pond-ts/pond/compare/v0.71.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.72.0...HEAD
+[0.72.0]: https://github.com/pond-ts/pond/compare/v0.71.0...v0.72.0
 [0.71.0]: https://github.com/pond-ts/pond/compare/v0.70.0...v0.71.0
 [0.70.0]: https://github.com/pond-ts/pond/compare/v0.69.0...v0.70.0
 [0.69.0]: https://github.com/pond-ts/pond/compare/v0.68.0...v0.69.0
@@ -74,6 +75,37 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.72.0] — 2026-10-08
+
+### Changed
+
+- `pond-ts`: **`join` and `joinMany` work on columns now, not events** — 20
+  to 190× faster in the cases below, with the same output. `join` used to
+  build an event for every row on both sides, merge them row by row and
+  rebuild the columns. Now it walks the two key columns once, then either
+  adopts each column as is or gathers it in one pass. A side's value columns
+  are adopted as is whenever all its rows land in the output once and in order:
+  always the left side of a `left` join, the right side of a `right` join, and
+  both sides when the keys match one for one (`joinMany` over a shared grid).
+  One year of 1-minute bars, ~97.5k rows a side, `type: 'left'` unless noted
+  (`packages/core/scripts/perf-join.mjs`):
+
+  | Value columns per side   | Before   | After    |
+  | ------------------------ | -------- | -------- |
+  | 59 and 59                | 1,868 ms | 24 ms    |
+  | 5 and 5                  | 168 ms   | 4.2 ms   |
+  | 59 and 2                 | 766 ms   | 4.1 ms   |
+  | `joinMany`, 4 × 5, outer | 457 ms   | 15–20 ms |
+
+  A left join now costs about as much as the **other** side is wide. To bring
+  across only the columns you read, narrow that side first; `select` and
+  `rename` don't copy:
+  `bars.join(spy.select('close').rename({ close: 'spy' }), { type: 'left' })`.
+
+  One visible difference: on a row with no match, `event.data()` now lists the
+  other side's fields as `undefined`, as every other operator's events do. It
+  used to leave them out. `get()` returns `undefined` either way.
+
 ## [0.71.0] — 2026-09-24
 
 ### Added

package/dist/batch/operators/join.d.ts

@@ -0,0 +1,37 @@
+import { type ColumnSchema, ColumnarStore } from '../../columnar/index.js';
+import type { JoinType } from '../../schema/index.js';
+/**
+ * **Column-native exact-key `join`** ([PND-JOINCOL]). Merge-walks the two
+ * key columns once into a pair of row-match indices — output row `r` takes
+ * left row `leftIdx[r]` and right row `rightIdx[r]`, with `-1` meaning "no
+ * row on that side" — then builds every output column from those indices:
+ *
+ * - **Pass-through.** When one side's index is the identity (each of its
+ *   rows appears once, in order, with nothing interleaved), that side's
+ *   value columns are adopted by reference — and, on the left, the key
+ *   column too. This is always true of the primary in a `left` join and of
+ *   the other side in a `right` join, and it is true of **both** sides when
+ *   the two keys match one for one — the `joinMany` over a shared grid case.
+ * - **Gather.** Otherwise each column is one `sliceByIndices` over the match
+ *   index; a `-1` slot comes out missing through the column's validity, the
+ *   substrate's existing out-of-range gather contract.
+ *
+ * No `Event` is materialised on either side or in the output.
+ *
+ * **Semantics are the event walk's, exactly.** The key comparison is
+ * `compareEventKeys` / `Interval.compare` restated over the buffers —
+ * `begin`, then `end`, then (interval keys only) `compareIntervalValues` on
+ * the labels — and the walk pairs equal keys **one to one** in order: a key
+ * that repeats `a` times on the left and `b` times on the right yields
+ * `min(a, b)` matched rows plus `|a − b|` one-sided rows, not `a·b`. A matched
+ * row carries the **left** key.
+ *
+ * Complexity: O(N + M) for the walk, plus O(R) per gathered column (R output
+ * rows). Pass-through columns cost nothing.
+ *
+ * The caller has already checked that the key kinds agree and that no value
+ * column name appears on both sides; `outSchema` is the left key column
+ * followed by the left then the right value columns.
+ */
+export declare function joinOp(left: ColumnarStore<ColumnSchema>, right: ColumnarStore<ColumnSchema>, joinType: JoinType, outSchema: ColumnSchema): ColumnarStore<ColumnSchema>;
+//# sourceMappingURL=join.d.ts.map

package/dist/batch/operators/join.js

@@ -0,0 +1,252 @@
+import { ColumnarStore, Float64Column, IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, ValueKeyColumn, stringColumnFromArray, } from '../../columnar/index.js';
+import { compareIntervalValues } from '../../core/temporal.js';
+/**
+ * **Column-native exact-key `join`** ([PND-JOINCOL]). Merge-walks the two
+ * key columns once into a pair of row-match indices — output row `r` takes
+ * left row `leftIdx[r]` and right row `rightIdx[r]`, with `-1` meaning "no
+ * row on that side" — then builds every output column from those indices:
+ *
+ * - **Pass-through.** When one side's index is the identity (each of its
+ *   rows appears once, in order, with nothing interleaved), that side's
+ *   value columns are adopted by reference — and, on the left, the key
+ *   column too. This is always true of the primary in a `left` join and of
+ *   the other side in a `right` join, and it is true of **both** sides when
+ *   the two keys match one for one — the `joinMany` over a shared grid case.
+ * - **Gather.** Otherwise each column is one `sliceByIndices` over the match
+ *   index; a `-1` slot comes out missing through the column's validity, the
+ *   substrate's existing out-of-range gather contract.
+ *
+ * No `Event` is materialised on either side or in the output.
+ *
+ * **Semantics are the event walk's, exactly.** The key comparison is
+ * `compareEventKeys` / `Interval.compare` restated over the buffers —
+ * `begin`, then `end`, then (interval keys only) `compareIntervalValues` on
+ * the labels — and the walk pairs equal keys **one to one** in order: a key
+ * that repeats `a` times on the left and `b` times on the right yields
+ * `min(a, b)` matched rows plus `|a − b|` one-sided rows, not `a·b`. A matched
+ * row carries the **left** key.
+ *
+ * Complexity: O(N + M) for the walk, plus O(R) per gathered column (R output
+ * rows). Pass-through columns cost nothing.
+ *
+ * The caller has already checked that the key kinds agree and that no value
+ * column name appears on both sides; `outSchema` is the left key column
+ * followed by the left then the right value columns.
+ */
+export function joinOp(left, right, joinType, outSchema) {
+    const lk = left.keys;
+    const rk = right.keys;
+    const n = lk.length;
+    const m = rk.length;
+    const keepLeft = joinType === 'left' || joinType === 'outer';
+    const keepRight = joinType === 'right' || joinType === 'outer';
+    // Exact for left / right (every row of the kept side is emitted once), an
+    // upper bound for inner / outer.
+    const capacity = joinType === 'left'
+        ? n
+        : joinType === 'right'
+            ? m
+            : joinType === 'inner'
+                ? Math.min(n, m)
+                : n + m;
+    const leftIdx = new Int32Array(capacity);
+    const rightIdx = new Int32Array(capacity);
+    const compare = keyComparator(lk, rk);
+    let i = 0;
+    let j = 0;
+    let len = 0;
+    let leftOnly = 0;
+    let rightOnly = 0;
+    while (i < n && j < m) {
+        const c = compare(i, j);
+        if (c === 0) {
+            leftIdx[len] = i;
+            rightIdx[len] = j;
+            len += 1;
+            i += 1;
+            j += 1;
+        }
+        else if (c < 0) {
+            if (keepLeft) {
+                leftIdx[len] = i;
+                rightIdx[len] = -1;
+                len += 1;
+                leftOnly += 1;
+            }
+            i += 1;
+        }
+        else {
+            if (keepRight) {
+                leftIdx[len] = -1;
+                rightIdx[len] = j;
+                len += 1;
+                rightOnly += 1;
+            }
+            j += 1;
+        }
+    }
+    if (keepLeft) {
+        for (; i < n; i += 1) {
+            leftIdx[len] = i;
+            rightIdx[len] = -1;
+            len += 1;
+            leftOnly += 1;
+        }
+    }
+    if (keepRight) {
+        for (; j < m; j += 1) {
+            leftIdx[len] = -1;
+            rightIdx[len] = j;
+            len += 1;
+            rightOnly += 1;
+        }
+    }
+    // A side's index is the identity iff all its rows were emitted and the
+    // other side contributed no one-sided rows between them (rows of one side
+    // are always emitted in ascending order).
+    const leftIdentity = len === n && rightOnly === 0;
+    const rightIdentity = len === m && leftOnly === 0;
+    const li = leftIdx.subarray(0, len);
+    const ri = rightIdx.subarray(0, len);
+    // A matched row carries the left key, so only the left key column is ever
+    // adopted. The right one is not a safe stand-in even when its index is the
+    // identity: equal keys need not be identical — interval labels compare with
+    // `localeCompare` (a precomposed and a decomposed é are equal), and
+    // timestamps with `-`, under which `0` and `-0` are equal.
+    const keys = leftIdentity ? lk : gatherKeys(lk, rk, li, ri);
+    const columns = new Map();
+    for (let c = 1; c < left.schema.length; c += 1) {
+        const name = left.schema[c].name;
+        const col = left.columns.get(name);
+        columns.set(name, leftIdentity ? col : col.sliceByIndices(li));
+    }
+    for (let c = 1; c < right.schema.length; c += 1) {
+        const name = right.schema[c].name;
+        const col = right.columns.get(name);
+        columns.set(name, rightIdentity ? col : col.sliceByIndices(ri));
+    }
+    return ColumnarStore.fromTrustedStore(outSchema, keys, columns);
+}
+/**
+ * The event walk's key order (`compareEventKeys`, plus `Interval.compare`'s
+ * label tiebreak) over the raw key buffers. Both columns are the same kind.
+ */
+function keyComparator(lk, rk) {
+    const lb = lk.begin;
+    const rb = rk.begin;
+    if (lk.kind === 'time' || lk.kind === 'value') {
+        return (i, j) => lb[i] - rb[j];
+    }
+    const le = lk.end;
+    const re = rk.end;
+    if (lk.kind === 'timeRange') {
+        return (i, j) => {
+            const d = lb[i] - rb[j];
+            return d !== 0 ? d : le[i] - re[j];
+        };
+    }
+    const ll = lk.labels;
+    const rl = rk.labels;
+    return (i, j) => {
+        const d = lb[i] - rb[j];
+        if (d !== 0)
+            return d;
+        const e = le[i] - re[j];
+        if (e !== 0)
+            return e;
+        return compareIntervalValues(ll.read(i), rl.read(j));
+    };
+}
+/**
+ * Builds the output key column row by row from whichever side has the row,
+ * preferring the left. Every `(begin, end, label)` triple is copied whole
+ * from one already-validated source row, so the per-row invariants (finite,
+ * `begin <= end`, defined label) hold by construction and the trusted
+ * factories skip re-checking them.
+ */
+function gatherKeys(lk, rk, li, ri) {
+    const len = li.length;
+    const lb = lk.begin;
+    const rb = rk.begin;
+    const begin = new Float64Array(len);
+    if (lk.kind === 'time' || lk.kind === 'value') {
+        for (let r = 0; r < len; r += 1) {
+            const a = li[r];
+            begin[r] = a >= 0 ? lb[a] : rb[ri[r]];
+        }
+        return lk.kind === 'time'
+            ? TimeKeyColumn.fromValidatedSubarray(begin, len)
+            : new ValueKeyColumn(begin, len);
+    }
+    const le = lk.end;
+    const re = rk.end;
+    const end = new Float64Array(len);
+    for (let r = 0; r < len; r += 1) {
+        const a = li[r];
+        if (a >= 0) {
+            begin[r] = lb[a];
+            end[r] = le[a];
+        }
+        else {
+            const b = ri[r];
+            begin[r] = rb[b];
+            end[r] = re[b];
+        }
+    }
+    if (lk.kind === 'timeRange') {
+        return TimeRangeKeyColumn.fromValidatedSubarray(begin, end, len);
+    }
+    const { labels, labelKind } = gatherLabels(lk, rk, li, ri);
+    return IntervalKeyColumn.fromValidatedSubarray(begin, end, labels, labelKind, len);
+}
+function gatherLabels(lk, rk, li, ri) {
+    const len = li.length;
+    let fromLeft = 0;
+    for (let r = 0; r < len; r += 1)
+        if (li[r] >= 0)
+            fromLeft += 1;
+    if (fromLeft === len) {
+        return {
+            labels: lk.labels.sliceByIndices(li),
+            labelKind: lk.labelKind,
+        };
+    }
+    if (fromLeft === 0) {
+        return {
+            labels: rk.labels.sliceByIndices(ri),
+            labelKind: rk.labelKind,
+        };
+    }
+    // Mixed-type labels never match (`compareIntervalValues` orders numbers
+    // before strings), so this is an outer join keeping one-sided rows from
+    // both. The event path rejected the same output when re-columnarising it.
+    if (lk.labelKind !== rk.labelKind) {
+        throw new RangeError(`join: cannot combine interval keys with ${lk.labelKind} labels and interval keys with ${rk.labelKind} labels — an interval-keyed series must use one label type throughout`);
+    }
+    if (lk.labelKind === 'number') {
+        const lv = lk.labels._values;
+        const rv = rk.labels._values;
+        const out = new Float64Array(len);
+        for (let r = 0; r < len; r += 1) {
+            const a = li[r];
+            out[r] = a >= 0 ? lv[a] : rv[ri[r]];
+        }
+        // Numeric interval labels are validated finite at construction.
+        return {
+            labels: new Float64Column(out, len, undefined, true),
+            labelKind: lk.labelKind,
+        };
+    }
+    const ll = lk.labels;
+    const rl = rk.labels;
+    const out = new Array(len);
+    for (let r = 0; r < len; r += 1) {
+        const a = li[r];
+        out[r] = (a >= 0 ? ll.read(a) : rl.read(ri[r]));
+    }
+    return {
+        labels: stringColumnFromArray(out, { forceDict: true }),
+        labelKind: lk.labelKind,
+    };
+}
+//# sourceMappingURL=join.js.map

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

@@ -619,6 +619,19 @@ export declare class TimeSeries<S extends SeriesSchema> {
      * Value columns from both series are included in the result and are optional because joined rows
      * may have missing values on either side. If both series use the same payload column name,
      * you can either rename one side before joining or use `{ onConflict: "prefix", prefixes: [...] }`.
+     *
+     * Keys pair **one to one** in order: a key that appears `a` times on the left and `b` times on
+     * the right gives `min(a, b)` matched rows plus `|a − b|` one-sided rows, not `a × b`. A matched
+     * row carries the left key.
+     *
+     * **Cost.** Column-native: one walk over the two key columns, then each output column is either
+     * the source column itself (no copy) or one gather. A side's columns pass through untouched
+     * whenever every one of its rows lands in the output once, in order, with nothing interleaved —
+     * always the left side of a `"left"` join and the right side of a `"right"` join, and both sides
+     * when the keys match one for one (`joinMany` over a shared grid). So the cost of a left join
+     * scales with the **other** side's width; to bring across only the columns you read, narrow it
+     * first — `select` and `rename` are themselves zero-copy:
+     * `bars.join(spy.select("close").rename({ close: "spy" }), { type: "left" })`.
      */
     join<Other extends SeriesSchema>(other: TimeSeries<Other>, options?: ErrorJoinOptions): TimeSeries<JoinSchema<S, Other>>;
     join<Other extends SeriesSchema, const Prefixes extends readonly [string, string]>(other: TimeSeries<Other>, options: PrefixJoinOptions<Prefixes>): TimeSeries<PrefixedJoinSchema<S, Other, Prefixes>>;

package/dist/batch/time-series.js

@@ -12,6 +12,7 @@ import { diffRateOp } from './operators/diff-rate.js';
 import { fillOp } from './operators/fill.js';
 import { mapOp } from './operators/map.js';
 import { shiftOp } from './operators/shift.js';
+import { joinOp } from './operators/join.js';
 import { collapseOp } from './operators/collapse.js';
 import { assertColumnValuesMatchKind, columnFromValuesByKind, } from './operators/column-builders.js';
 import { computeByColumn } from './by-column.js';
@@ -1499,46 +1500,10 @@ export class TimeSeries {
                 .slice(1)
                 .map((column) => ({ ...column, required: false })),
         ]);
-        const joinedEvents = [];
-        let leftIndex = 0;
-        let rightIndex = 0;
-        while (leftIndex < left.events.length || rightIndex < right.events.length) {
-            const leftEvent = left.events[leftIndex];
-            const rightEvent = right.events[rightIndex];
-            if (leftEvent && !rightEvent) {
-                if (joinType === 'left' || joinType === 'outer') {
-                    joinedEvents.push(leftEvent.merge({}));
-                }
-                leftIndex += 1;
-                continue;
-            }
-            if (rightEvent && !leftEvent) {
-                if (joinType === 'right' || joinType === 'outer') {
-                    joinedEvents.push(rightEvent.merge({}));
-                }
-                rightIndex += 1;
-                continue;
-            }
-            const comparison = leftEvent.key().compare(rightEvent.key());
-            if (comparison === 0) {
-                joinedEvents.push(leftEvent.merge(rightEvent.data()));
-                leftIndex += 1;
-                rightIndex += 1;
-            }
-            else if (comparison < 0) {
-                if (joinType === 'left' || joinType === 'outer') {
-                    joinedEvents.push(leftEvent.merge({}));
-                }
-                leftIndex += 1;
-            }
-            else {
-                if (joinType === 'right' || joinType === 'outer') {
-                    joinedEvents.push(rightEvent.merge({}));
-                }
-                rightIndex += 1;
-            }
-        }
-        return TimeSeries.#fromTrustedEvents(left.name, resultSchema, joinedEvents);
+        // Column-native: merge-walk the key buffers, then pass each column
+        // through or gather it. See `joinOp`.
+        const store = joinOp(left.#store.store, right.#store.store, joinType, resultSchema);
+        return TimeSeries.#fromTrustedStore(left.name, resultSchema, store);
     }
     /**
      * Example: `series.align(Sequence.every("1m"))`.

package/dist/live/series-store.js

@@ -357,12 +357,12 @@ function validateCachedEvent(rowIndex, cachedEvent, store, schemaValueNames) {
     //     kind-aware equality.
     // (b) when the field is **absent** from `cachedData`, the
     //     column at that row must read as `undefined` — i.e. the
-    //     event genuinely doesn't carry that column. This is the
-    //     outer-join shape: `series.join(other, { type: 'outer' })`
-    //     produces events whose data omits the other side's columns
-    //     for rows that had no match. Pre-2a TimeSeries treated this
-    //     as a row-API concern (the strict missing-field check
-    //     pre-dated outer-join via the columnar substrate); the
+    //     event genuinely doesn't carry that column. This shape was
+    //     admitted for the event-walking outer `join`, whose unmatched
+    //     rows omitted the other side's columns. `join` is column-native
+    //     now ([PND-JOINCOL]) and no longer produces it, but a caller-
+    //     supplied cache can, so the relaxation stands. Pre-2a
+    //     TimeSeries treated this as a row-API concern; the
     //     relaxation here keeps the original misalignment-detection
     //     property — a cached event whose data is missing a field
     //     for which the column DOES read a defined value still

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pond-ts",
-  "version": "0.71.0",
+  "version": "0.72.0",
   "description": "Typed time series for TypeScript: schema-driven TimeSeries + streaming LiveSeries with aggregate, rolling, align, fill, partitionBy and typed columns",
   "keywords": [
     "time-series",