Skip to content

v0.48.0 - Multi-Column Sort (2026-03-27)

What Changed?

This release replaces the single-column sort(header, options?) method with sortBy(headers, options?), enabling multi-column sorting with per-column ascending/descending control. SortOptions.ascending is now boolean[] only — the previous boolean scalar form is removed.

What's New

Main Feature: Multi-column sort with sortBy

What it does: Sorts a BareFrame by one or more columns. Each column can independently be sorted ascending or descending. Null values are always placed at the end regardless of sort direction.

How to use it:

TypeScript
// Single column (ascending, default)
df.sortBy(["age"]);

// Single column (descending)
df.sortBy(["age"], { ascending: [false] });

// Multi-column: primary sort by dept (asc), secondary by age (desc)
df.sortBy(["dept", "age"], { ascending: [true, false] });

Remarks:

  • The order of headers determines sort priority (left = primary).
  • The caller is responsible for ensuring ascending matches the column order in headers.
  • If ascending is provided, its length must equal headers.length; otherwise an error is thrown.

Added

  • None

Changed

  • sort(header, options?: SortOptions) → sortBy(headers: string[], options?: SortOptions)
  • SortOptions.ascending type: boolean | boolean[] → boolean[]

Fixed

  • None

Is It Safe to Upgrade?

  • Breaking Changes: Yes
  • Backward Compatible: No

Call sites using sort(header, options?) must be updated to sortBy([header], options?). Call sites passing ascending: false (boolean scalar) must be updated to ascending: [false] (array).

Release Details

  • Date: 2026-03-27
  • Version: v0.48.0
  • gaslamp: clasp version 102
  • pilotlamp: clasp version 60
  • Files Changed: 3
  • Commits:
    • bb4b78a9 docs(v2/frame): add @remarks about caller responsibility for sort order
    • 6c1f818f docs(v2/frame): update sortBy docstring with accurate params and examples
    • 49d18eca refactor(v2/frame): restrict SortOptions.ascending to boolean[] only
    • 0a6684da feat(v2/frame): validate ascending array length in sortBy
    • c062f0e1 feat(v2/frame): replace sort with sortBy supporting multi-column sorting

Known Issues

  • None

Next Steps

  • Consider applying the same options-object pattern to toSheet (currently uses an inline object type without a named alias)