Skip to content

gaslamp v0.24.0 Release Notes

  • Released: 2025-09-11
  • gaslamp: 63 - v0.24.0
  • pilotlamp: 20 - v0.24.0

🎉 Major Changes

🏗️ Complete DataFrame Architecture Refactoring (Issue #137)

Comprehensive DataFrame modularization - Successfully completed Phase 2 modular architecture implementation with significant code organization improvements:

  • Analysis Module: Extracted statistical operations, grouping, and mathematical computations
  • Output Module: Centralized conversion, display, and slicing functionality
  • Transformation Module: Modularized data manipulation, structure, and basic operations
  • Access Module: Dedicated row and column access patterns
  • Pattern Integration: Complete design patterns integration with improved maintainability
TypeScript
// Enhanced modular structure
import {
  DataFrameAnalysis,    // Statistics, grouping, operations
  DataFrameOutput,      // Conversion, display, slicing
  DataFrameTransform,   // Manipulation, structure, basic ops
  DataFrameAccess       // Row/column access patterns
} from 'torch/dataframe';

🔧 Sheet Module Refactoring (Issue #138)

Gaslets module reorganization - Complete refactoring of the monolithic sheet.ts (602 lines) into focused, maintainable modules:

  • sheet-dataframe.ts: DataFrame conversion utilities for Google Sheets integration
  • sheet-artisan.ts: Enhanced SheetArtisan class with improved error handling
  • sheet-legacy.ts: Deprecated functions with proper @deprecated tags for backward compatibility
  • sheet.ts: Integration module with clean re-exports and globalThis compatibility
TypeScript
// New focused imports available
import {
  SheetArtisan,                    // Enhanced sheet management
  readDataFrameFromSheet,          // Sheet → DataFrame conversion
  writeDataFrameToSheet,           // DataFrame → Sheet writing
  readDataFrameFromRange,          // Range → DataFrame conversion
  writeDataFrameToRange            // DataFrame → Range writing
} from 'gaslets/sheet';

🚀 Enhanced Features

✨ Google Apps Script Compatibility Improvements

Critical GAS environment fixes - Resolved major compatibility issues affecting DataFrame creation methods:

  • fromObject() Method: Now works correctly in GAS environment with proper type validation
  • fromMap() Method: Fixed Map type checking for GAS compatibility
  • Type Guards Enhancement: FlameWright validation system improved for cross-environment consistency
  • Factory Pattern Fix: Exported required Factory classes for GAS bundle compatibility
TypeScript
// Now working correctly in GAS environment
const objectData = { name: ["Alice", "Bob"], age: [25, 30] };
const mapData = new Map([["name", ["Alice", "Bob"]], ["age", [25, 30]]]);

// All methods now work in both Node.js and GAS
const dfFromObject = new gaslamp.DataFrame().fromObject(objectData);  ✅
const dfFromMap = new gaslamp.DataFrame().fromMap(mapData);            ✅
const dfFromArrays = new gaslamp.DataFrame().fromArrays(arrayData);   ✅

🐛 Critical Bug Fixes

FlameWright Type Validation

  • Fixed instanceof Issues: Replaced instanceof checks with Object.prototype.toString.call() for GAS compatibility
  • Fixed Prototype Chain Issues: Replaced Object.getPrototypeOf() comparison with toString-based type checking
  • Factory Class Export: Added missing Factory class exports to torch/index.ts for GAS accessibility
  • Cross-Environment Consistency: Ensured identical behavior between Node.js and Google Apps Script environments

Sheet Module Integration

  • AfterGlow Logging: Fixed error logging format in SheetArtisan ({ values: [error] } instead of { error })
  • Backward Compatibility: Maintained all existing functionality while improving code organization
  • Import Resolution: Resolved all module dependency issues after refactoring
  • Type Safety: Enhanced TypeScript compliance across all refactored modules

🔧 Architecture Improvements

DataFrame Modular Design

  • Phase 2 Implementation: Complete extraction of analysis, output, transformation, and access modules
  • Separation of Concerns: Clear functional boundaries between different DataFrame capabilities
  • Maintainability: Significantly improved code organization with focused responsibilities
  • Extensibility: Enhanced ability to add new features without affecting core DataFrame class

Sheet Module Organization

  • Focused Modules: Each module handles specific functionality (DataFrame ops, sheet management, legacy support)
  • Clean Integration: Main sheet.ts acts as a clean integration layer with proper re-exports
  • Documentation: Comprehensive TypeDoc documentation for all refactored modules
  • Testing: Unit tests created for GAS environment compatibility verification

🧪 Testing & Quality

Comprehensive Test Coverage

  • ✅ All Tests Pass: Complete test suite with 49 test suites, 584 total tests
  • ✅ GAS Environment Tests: New comprehensive test suites for GAS compatibility
  • ✅ FlameGuards Validation: Enhanced type validation testing across environments
  • ✅ Module Integration: Cross-module integration testing completed

Test Results

JavaScript
// GAS Environment Test Results
✅ DataFrame.fromArrays: Working correctly
✅ DataFrame.fromObject: Fixed and working
✅ DataFrame.fromMap: Fixed and working
✅ Empty object/Map handling: Both working
✅ FlameGuards type validation: All passing

Quality Assurance

  • ✅ Cross-Environment Compatibility: Verified behavior consistency between Node.js and GAS
  • ✅ Backward Compatibility: 100% existing functionality preserved
  • ✅ Type Safety: Enhanced TypeScript strict mode compliance
  • ✅ Error Handling: Improved validation and error reporting across modules

🔍 Technical Implementation Details

FlameWright Type System Enhancement

Problem: instanceof and Object.getPrototypeOf() behave differently in GAS environment, causing validation failures in MapDataFrameFactory and ObjectDataFrameFactory.

Solution: Implemented GAS-compatible type checking using Object.prototype.toString.call():

TypeScript
// Before (Node.js only)
function isMap(value: unknown): value is Map<unknown, unknown> {
  return value instanceof Map;  // ❌ Fails in GAS
}

function isPlainObject(value: unknown): value is Record<string, unknown> {
  return Object.getPrototypeOf(value) === Object.prototype;  // ❌ Fails in GAS
}

// After (Cross-environment compatible)
function isMap(value: unknown): value is Map<unknown, unknown> {
  return Object.prototype.toString.call(value) === "[object Map]";  // ✅ Works everywhere
}

function isPlainObject(value: unknown): value is Record<string, unknown> {
  const objectTag = Object.prototype.toString.call(value);
  return objectTag === "[object Object]";  // ✅ Works everywhere
}

Sheet Module Architecture

Before: Monolithic 602-line src/gaslets/sheet.ts with mixed concerns After: Four focused modules with clear separation:

  1. sheet-dataframe.ts: DataFrame ↔ Sheet conversion utilities
  2. sheet-artisan.ts: Sheet management with enhanced SheetArtisan class
  3. sheet-legacy.ts: Deprecated functions with @deprecated tags
  4. sheet.ts: Clean integration layer with re-exports

Factory Pattern Integration

Enhancement: Exported all required Factory classes in src/torch/index.ts:

TypeScript
// Added to torch/index.ts for GAS compatibility
export * from "./dataframe/patterns";  // Exports MapDataFrameFactory, ObjectDataFrameFactory, etc.

🚀 Migration Guide

For GAS Users (Critical)

DataFrame Creation Methods Now Work: The most commonly requested features are now fully functional:

TypeScript
// These now work correctly in GAS environment
const df1 = new gaslamp.DataFrame().fromObject({
  name: ["Alice", "Bob"],
  age: [25, 30]
});

const df2 = new gaslamp.DataFrame().fromMap(new Map([
  ["name", ["Alice", "Bob"]],
  ["age", [25, 30]]
]));

For Sheet Module Users

Backward Compatibility Maintained: All existing code continues to work unchanged:

TypeScript
// Existing code continues to work
const artisan = new gaslamp.SheetArtisan();
const df = gaslamp.readDataFrameFromSheet(sheet);

// Enhanced functionality available
import { SheetArtisan } from 'gaslets/sheet-artisan';  // For advanced usage

For Advanced Users

New Modular Architecture: Enhanced maintainability and extensibility:

TypeScript
// Access specific functionality modules
import { DataFrameAnalysis } from 'torch/dataframe/analysis';
import { DataFrameOutput } from 'torch/dataframe/output';
import { DataFrameTransform } from 'torch/dataframe/transformation';

👥 Contributors

  • @shotakaha - Complete DataFrame architecture refactoring, Sheet module reorganization, and GAS compatibility fixes
  • Documentation: https://gaslamp.readthedocs.io/
  • Repository: https://gitlab.com/qumasan/gaslamp

Full Changelog: v0.23.0...v0.24.0