Skip to content

v0.68.0 - Symbol.toStringTag Type Detection (2026-04-06)

What Changed?

This release standardizes type detection across all gaslamp frame classes using ES6's Symbol.toStringTag. The new implementation enables reliable type identification in Google Apps Script, even across script boundaries where instanceof fails. All existing code continues to work unchanged — this is a pure improvement to type safety without breaking changes.

What's New

Main Feature: Symbol.toStringTag Implementation for Safe Type Detection

What it does: All gaslamp frame classes (BareFrame, FlameFrame, GroupedFrame, LazyFrame, ForgeFrame, Expression) now implement Symbol.toStringTag, enabling reliable type detection via Object.prototype.toString.call(). The getTypeOf() function has been updated to extract these tags and return the type name as a lowercase string.

How to use it: The usage pattern remains the same — call getTypeOf() to detect frame types safely:

TypeScript
const df = BareFrame.fromSheet(sheet);
const type = getTypeOf(df);  // Returns "bareframe"

if (type === "bareframe") {
  Logger.log("It's a BareFrame!");
} else if (type === "flameframe") {
  Logger.log("It's a FlameFrame!");
}

Code example:

TypeScript
// Before: unreliable instanceof across script boundaries
if (value instanceof Date) { /* may fail in GAS */ }

// After: reliable Symbol.toStringTag detection (works everywhere)
if (getTypeOf(value) === "date") { /* always works */ }

// Works with gaslamp frame types too
if (getTypeOf(df) === "bareframe") { /* safe across boundaries */ }

Added

  • Symbol.toStringTag getter to BareFrame class
  • Symbol.toStringTag getter to FlameFrame class
  • Symbol.toStringTag getter to GroupedFrame class
  • Symbol.toStringTag getter to LazyFrame class
  • Symbol.toStringTag getter to ForgeFrame class
  • Symbol.toStringTag getter to Expression class
  • Enhanced getTypeOf() documentation with gaslamp frame type examples
  • Updated docs/guides/gettypeof.md with comprehensive DataFrame type detection guide

Changed

  • getTypeOf() now uses Object.prototype.toString.call() with regex parsing for universal type extraction
  • getTypeOf() documentation expanded to cover gaslamp frame types

Fixed

  • Type detection now works reliably across GAS script boundaries (resolves #161)
  • Eliminates instanceof dependency for internal type checking

Is It Safe to Upgrade?

  • Breaking Changes: No
  • Backward Compatible: Yes

Fully backward compatible. All existing type detection code continues to work. The internal implementation improvement provides better reliability with no API changes.

Release Details

  • Date: 2026-04-06
  • Version: v0.68.0
  • gaslamp: 128
  • pilotlamp: 86
  • Files Changed: 8 (6 src files + 2 docs)
  • Commits:
  • 3896afe5 feat: implement Symbol.toStringTag for type detection standardization (#161)
  • 39433e17 docs: update getTypeOf guide for Symbol.toStringTag implementation
  • 5c3aad0c chore: update uv.lock and VERSIONS.toml

Known Issues

None. All tests pass (466 passing tests).

Next Steps

  • Consider adding convenience guards like FlameGuards.isBareFrame() in future releases
  • Monitor GAS boundary detection behavior in production environments