Skip to content

v0.31.0 - LazyFrame and GAS-First Design Patterns (2026-03-22)

What Changed?

This release introduces LazyFrame, a lazy evaluation wrapper around DataFrame that queues operations and executes them only when collect() is called. It also establishes the GAS-First Argument Design Pattern as an official design guideline, and fixes Expression to follow the centralized GAS global namespace registration pattern.

What's New

Main Feature: LazyFrame

What it does: LazyFrame allows you to chain filter, select, and withColumn operations without executing them immediately. All operations are applied in order when collect() is called, returning a new DataFrame.

How to use it:

TypeScript
// Using a plain function
const result = LazyFrame.from(df)
  .filter((row) => (row.get('age') as number) > 18)
  .select(['name', 'age'])
  .collect();

// Using Expression.toFunction()
const result = LazyFrame.from(df)
  .filter(new Expression('age').gt(18).toFunction())
  .select(['name', 'age'])
  .collect();

Notes:

  • LazyFrame.from(df) is the only public entry point — the constructor is private.
  • withColumn is queued but not yet executed in collect(). Requires Series integration.
  • LazyFrame accepts plain functions (FilterFn, MapFn) rather than Expression directly, following the GAS-First Argument Design Pattern.

Added

  • LazyFrame class in src/torch/lazyframe/ — lazy evaluation wrapper around DataFrame
  • LazyFrame.from(df, options?) — static factory, the only public entry point
  • LazyFrame.filter(fn) — queue a filter operation using a predicate function
  • LazyFrame.select(cols) — queue a column selection operation
  • LazyFrame.withColumn(name, fn) — queue a column add/replace operation (stub)
  • LazyFrame.collect() — execute all queued operations and return a DataFrame
  • LazyFrame registered in GAS global namespace via src/index.ts
  • Expression registered in GAS global namespace via src/index.ts (was missing)
  • GAS-First Argument Design Pattern documented in docs/dev/patterns.md

Changed

  • LazyFrame moved from src/torch/dataframe/lazy/ to src/torch/lazyframe/ — it is a wrapper around DataFrame, not a part of it
  • LazyFrame.filter() and LazyFrame.withColumn() now accept plain JS functions instead of Expression objects
  • src/torch/index.ts updated: removed duplicate dataframe/patterns export, fixed Expression example API

Fixed

  • Expression: removed non-compliant declare const globalThis: any pattern; registration moved to src/index.ts

Is It Safe to Upgrade?

  • Breaking Changes: Yes

  • Backward Compatible: No

  • LazyFrame.filter() previously accepted Expression; it now accepts (row: Map<string, unknown>) => boolean. Replace expr with expr.toFunction() at call sites.

  • LazyFrame.withColumn() previously accepted Expression; it now accepts (value: unknown) => unknown.

Release Details

  • Date: 2026-03-22
  • Version: v0.31.0
  • gaslamp: version 74
  • pilotlamp: version 31
  • Files Changed: 131
  • Commits:
    • e77e83d feat(gas): register LazyFrame in GAS global namespace
    • c573402 refactor(torch): move LazyFrame to src/torch/lazyframe/
    • c8fb30a refactor(lazy): replace Expression with function types in filter and withColumn
    • ae0ac36 feat(lazy): implement collect() with filter and select operations
    • f69f036 feat(lazy): add private constructor with source DataFrame
    • 106a2aa fix(expression): move globalThis registration to src/index.ts
    • 7f9e0e2 docs(patterns): add GAS-First Argument Design Pattern section

Known Issues

  • withColumn is queued but not executed in collect(). Requires Series integration.
  • DataFrame.join() only supports a single join column. Multi-column joins are not yet supported.
  • fromCSV() and fromJSON() are not yet implemented.
  • transpose() is not yet implemented.

Next Steps

  • Implement withColumn in LazyFrame.collect() via Series integration
  • Multi-column join support
  • Expand test coverage for LazyFrame operations