Skip to content

v0.44.0 - Add unfoldColumns to BareFrame and FlameFrame (2026-03-25)

What Changed?

This release adds the unfoldColumns() method to both BareFrame and FlameFrame. It converts wide-format data with grouped columns into long-format rows, replacing the v1 explodeBy* family of methods. The v1 explodeByColumnGroups, explodeByPattern, and explodeByHeaders methods are now deprecated.

What's New

Main Feature: unfoldColumns()

What it does: Expands repeated column groups (e.g., multiple people, questions, or time periods) from wide format into long format, where each group becomes a separate row.

How to use it:

TypeScript
const df = BareFrame.fromColumns({
  timestamp: ["2024-03-25"],
  email: ["a@example.com"],
  person1_name: ["Alice"],
  person1_age: [30],
  person2_name: ["Bob"],
  person2_age: [25],
});

const unfolded = df.unfoldColumns({
  fixedHeaders: ["timestamp", "email"],
  groups: [
    ["person1_name", "person1_age"],
    ["person2_name", "person2_age"],
  ],
  groupHeaders: ["name", "age"],
});
// timestamp   | email         | name  | age
// 2024-03-25  | a@example.com | Alice | 30
// 2024-03-25  | a@example.com | Bob   | 25

Permissive vs strict mode:

permissive (default) strict
Missing columns in groups filled with null throws Error
Group size mismatch filled with null throws Error

Use strict: true for ETL pipelines or data quality checks where structure errors should fail early.

Added

  • UnfoldOptions type in src/v2/frame.ts (@since 0.44.0)
  • BareFrame.unfoldColumns(options: UnfoldOptions) in src/v2/frame.ts (@since 0.44.0)
  • FlameFrame.unfoldColumns(options: UnfoldOptions) in src/v2/flameframe.ts (@since 0.44.0) — validates fixedHeaders against the schema, then delegates to BareFrame

Changed

  • Nothing

Fixed

  • Nothing

Deprecated

  • DataFrameV1.explodeByColumnGroups() — use BareFrame.unfoldColumns() instead
  • DataFrameV1.explodeByPattern() — use BareFrame.unfoldColumns() instead
  • DataFrameV1.explodeByHeaders() — use BareFrame.unfoldColumns() instead

Is It Safe to Upgrade?

  • Breaking Changes: No
  • Backward Compatible: Yes

The v1 explodeBy* methods are deprecated but not yet removed. Existing code continues to work.

Release Details

  • Date: 2026-03-25
  • Version: v0.44.0
  • gaslamp: v95
  • pilotlamp: v52
  • Files Changed: 193
  • Commits:
    • ad923d8c feat(v2): add unfoldColumns method to BareFrame
    • e50f1aa3 test(v2): add unfoldColumns tests to frame.test.ts
    • b02f1b49 feat(v2): add unfoldColumns wrapper to FlameFrame
    • d91f41b0 test(v2): add unfoldColumns tests to flameframe.test.ts
    • e64f3279 docs(v2): update UnfoldOptions description to include FlameFrame
    • 94cd0539 docs(v2): add @since 0.44.0 to UnfoldOptions and unfoldColumns
    • c0f2d8c4 docs(legacy): add explodeBy* deprecation entries (since 0.44.0) to v1 README
    • 2db11260 docs(torch): add @deprecated Since 0.44.0 to explodeBy* methods
    • 5f0d3a2f docs(api): regenerate TypeDoc for 0.44.0
    • f811fd66 build: bundle gaslamp for 0.44.0

Known Issues

  • None

Next Steps

  • Remove deprecated explodeBy* methods in a future release
  • Add FlameFrame.unfoldColumns() result re-validation via FlameFrame.from()