Skip to content

v0.29.0 - DataFrameState shared reference (2026-03-22)

What Changed?

This release introduces DataFrameState, a shared mutable object that holds all core DataFrame data (data, headers, length). All internal submodules now hold a reference to the same DataFrameState instance, so any mutation is immediately visible across all submodules without an explicit sync call. The internal _syncSubmodules() method has been removed entirely.

What's New

Main Feature: DataFrameState shared reference

What it does: Replaces the three separate private fields (_data, _headers, _length) in DataFrame with a single DataFrameState object. All submodules share the same reference, eliminating the need to propagate state changes manually.

How to use it: DataFrameState is now publicly exported and can be used for type annotations in tests or third-party extensions.

Code example:

TypeScript
import type { DataFrameState } from "gaslamp";

const state: DataFrameState = {
  data: new Map(),
  headers: [],
  length: 0,
};

Added

  • DataFrameState interface exported publicly from src/torch/dataframe/core/state.ts

Changed

  • All 12 DataFrame submodules now accept DataFrameState instead of individual data/headers/length arguments
  • DataFrameValidation now holds a DataFrameState reference instead of a plain headers array
  • DataFrameManipulation.reset() return type changed from object to void — resets state in place
  • updateReferences() in all submodules marked @deprecated — no longer called by DataFrame

Fixed

  • Stale state bug: submodules could hold a stale headers reference after fromMap() replaced the array. Fixed by sharing the DataFrameState object reference.

Is It Safe to Upgrade?

  • Breaking Changes: Yes
  • Backward Compatible: No

The constructor signatures of all internal submodule classes have changed. If you were constructing submodules directly (e.g. new DataFrameValidation(wright, headers)), update to pass a DataFrameState object instead. Normal DataFrame usage via the public API is unaffected.

Release Details

  • Date: 2026-03-22
  • Version: v0.29.0
  • gaslamp: version 71
  • pilotlamp: version 28
  • Files Changed: 156
  • Commits:
    • f298dc7 feat(torch): add DataFrameState interface and export it publicly
    • 8fea8f3 refactor(torch)!: add _state field to DataFrame as preparation for state migration
    • 4fc5fa4 refactor(torch)!: migrate all submodules to accept DataFrameState
    • c429bb0 refactor(torch)!: remove _data/_headers/_length fields and _syncSubmodules from DataFrame
    • 3b01d44 docs(torch): update docstrings for DataFrameState migration
    • 48b80c6 docs(torch): fix stale updateReferences docstrings in DataFrame submodules
    • 1fb4719 docs(torch): mark updateReferences as deprecated in all DataFrame submodules

Known Issues

  • updateReferences() still exists as dead code in all submodules. Will be removed in a future release.
  • Circular references between submodules and core/dataframe.ts remain (submodules call new DataFrame() to return results). No runtime impact — will be addressed in a separate issue.

Next Steps

  • Remove updateReferences() from all submodules (cleanup issue)
  • Investigate circular reference resolution via factory function injection