Skip to content

v0.47.0 - DataFrame API Consistency (2026-03-27)

What Changed?

This release unifies the method signatures across BareFrame, FlameFrame, and LazyFrame. Column-related parameters are renamed to header / headers throughout, and positional boolean/string arguments are replaced with options objects (SortOptions, DuplicateOptions, HowOptions, JoinOptions). No new features are added — this is a pure API consistency refactor.

What's New

Main Feature: Unified options-object API

What it does: Replaces bare positional arguments (e.g. sort("age", false)) with named options objects (e.g. sort("age", { ascending: false })). Also renames column-name parameters to header / headers so the intent is immediately clear at the call site.

How to use it:

TypeScript
// sort
df.sort("age");                         // ascending (default)
df.sort("age", { ascending: false });   // descending

// join
df.join(other, "id");                   // inner join (default)
df.join(other, "id", { how: "left" });  // left join

// deduplication
df.isDuplicated();
df.isDuplicated({ headers: ["name"], keep: "none" });
df.dropDuplicatedRows({ keep: "last" });

// withColumn / getColumn
df.withColumn("doubled", (row) => (row.get("age") as number) * 2);
df.getColumn("name");

Added

  • SortOptions type — wraps ascending?: boolean for sort
  • DuplicateOptions type — wraps headers?: string[] and keep?: KeepOptions for deduplication methods
  • HowOptions type alias — "inner" | "left" | "right" | "outer" for join type
  • JoinOptions type — wraps how?: HowOptions for join

Changed

  • sort(by, ascending?) → sort(header, options: SortOptions)
  • join(other, on, how?) → join(other, on, options: JoinOptions)
  • isDuplicated(headers?, keep?) → isDuplicated(options: DuplicateOptions)
  • findDuplicatedRows(headers?, keep?) → findDuplicatedRows(options: DuplicateOptions)
  • dropDuplicatedRows(headers?, keep?) → dropDuplicatedRows(options: DuplicateOptions)
  • withColumn(name, mapper) → withColumn(header, mapper) (BareFrame, FlameFrame, LazyFrame)
  • getColumn(name) / _getColumn(name) → getColumn(header) / _getColumn(header)
  • groupBy(keys) → groupBy(headers)
  • LazyOp internal withColumn variant field: name → header

Fixed

  • None

Is It Safe to Upgrade?

  • Breaking Changes: Yes
  • Backward Compatible: No

Call sites that pass positional arguments to sort, join, isDuplicated, findDuplicatedRows, or dropDuplicatedRows must be updated to use options objects. Parameter renames (name → header, by → header, keys → headers) are TypeScript-only and do not affect runtime behavior — positional call sites remain valid JS.

Release Details

  • Date: 2026-03-27
  • Version: v0.47.0
  • gaslamp: clasp version 101
  • pilotlamp: clasp version 59
  • Files Changed: 4
  • Commits:
    • 75c3cf3e refactor(v2/frame): rename sort by->header and groupBy keys->headers
    • 0af160a9 refactor(v2/frame): introduce SortOptions and DuplicateOptions
    • 66358af0 docs(v2/frame): improve docstrings for HowOptions, JoinOptions, and join
    • 96a3a647 refactor(v2/frame): introduce HowOptions and JoinOptions for join method
    • 07576661 refactor(v2): rename parameter name -> header in column methods

Known Issues

  • None

Next Steps

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