Skip to content

v0.44.1 - GroupedFrame Column-Oriented Refactor (2026-03-27)

What Changed?

This release refactors the internal implementation of GroupedFrame and BareFrame.groupBy to a column-oriented, index-based approach. No public API changes — existing code using groupBy, count, first, last, and agg continues to work unchanged. Memory usage for grouped operations is significantly reduced.

What's New

Main Feature: Column-Oriented GroupedFrame

What it does: Previously, groupBy converted all data to row Maps, then stored a separate BareFrame copy for each group. Now it works directly on columns, storing only row index arrays per group and a single reference to the source frame.

How to use it: No changes required — the public API is identical.

TypeScript
const df = BareFrame.fromColumns({
  dept:  ["eng", "eng", "hr"],
  score: [80, 90, 70],
});

df.groupBy(["dept"]).count();
// dept | count
// eng  | 2
// hr   | 1

df.groupBy(["dept"]).agg({
  score: (vals) => (vals as number[]).reduce((a, b) => a + b, 0),
});
// dept | score
// eng  | 170
// hr   | 70

Added

  • makeCompositeKey(): module-private helper that builds a type-prefixed, null-separated composite key string from column values at a given row index — replaces JSON.stringify for faster, collision-safe key generation
  • BareFrame._getColumn(): @internal accessor that returns the raw column array by reference, used by GroupedFrame aggregation methods without copying data

Changed

  • GroupedFrame constructor signature changed from (keys, groups: Map<string, BareFrame>) to (keys, source: BareFrame, indices: Map<string, number[]>) — @internal, no impact on user code
  • BareFrame.groupBy: rewrote to column-oriented loop; eliminates mapToRows() call during grouping
  • GroupedFrame.count / first / last / agg: rewrote to fetch values directly from source frame via row indices; eliminates per-group BareFrame allocation
  • GroupedFrame docstring and groupBy docstring updated to reflect the new internal design

Fixed

  • BareFrame._getColumn error message no longer exposes the internal method name (_getColumn) — replaced with [internal] prefix

Is It Safe to Upgrade?

  • Breaking Changes: No
  • Backward Compatible: Yes

All public methods (groupBy, count, first, last, agg) retain identical signatures and behavior.

Release Details

  • Date: 2026-03-27
  • Version: v0.44.1
  • gaslamp: version 96
  • pilotlamp: version 54
  • Files Changed: 1 (src/v2/frame.ts)
  • Commits:
    • 531711a8 fix(v2): hide internal method name from _getColumn error message
    • d3caa68a docs(v2): update GroupedFrame and groupBy docstrings for column-oriented design
    • 55b47582 refactor(v2): rewrite GroupedFrame to column-oriented index-based approach
    • 0b09f2ee refactor(v2): add makeCompositeKey helper and _getColumn accessor

Known Issues

  • None

Next Steps

  • Continue v2 migration: remaining src/torch/ methods not yet ported to src/v2/