Skip to content

v0.66.0 - FlameFrame API Refinements (2026-04-05)

What Changed?

This release refines the FlameFrame API based on user feedback from v0.65.0. The failed return value is now explicitly typed as BareFrame for semantic clarity, and the schema parameter is made required to enforce type safety. All documentation and examples are unified to show the complete { passed, failed } return pattern consistently.

What's New

Clarified Return Type: failed as BareFrame

What it does: The FlameFrame.from() method now returns failed as a plain BareFrame instead of FlameFrame<never>. This better reflects the semantic meaning: invalid rows are schema-free and should be treated as plain DataFrames.

How to use it: The API remains unchanged — failed still has all BareFrame methods available. This is purely a type refinement that makes the intent clearer.

Code example:

TypeScript
const { passed, failed } = FlameFrame.from(df, schema);

// passed: FlameFrame<T> with schema attached
// failed: BareFrame (no schema, just error details)
if (failed.length > 0) {
  Logger.log(failed.toString()); // works as before
}

Required Schema Parameter

What changed: The _schema field in FlameFrame is now required (no longer optional). This enforces that every FlameFrame instance must have a schema attached.

Why: Since failed returns a BareFrame without schema, FlameFrame instances always carry a schema. This makes the type system more precise and prevents accidental schema-less frames.

Added

  • Comprehensive refactoring guide for FlameFrame API changes in v0.65.0
  • Deprecation notice for toDataFrame() method in docstring (v0.65.0+ makes it unnecessary)

Changed

  • BREAKING: failed return type changed from FlameFrame<never> to BareFrame
  • BREAKING: _schema field is now required in FlameFrame constructor
  • schema getter return type: FlameRecord<T> | undefined → FlameRecord<T>
  • All code examples unified to show { passed, failed } destructuring pattern
  • Error message format now uses semicolon delimiter for better CSV compatibility: row: 0; name: got number

Fixed

  • Updated all documentation examples to show correct { passed, failed } pattern
  • Clarified that failed is BareFrame (schema-free) in API documentation
  • Fixed docstring examples to match actual return types

Is It Safe to Upgrade?

  • Breaking Changes: Minor (type refinements only, behavior unchanged)
  • Backward Compatible: Type-level only; runtime behavior is identical

For most users: No action needed. If you were already using { passed, failed } destructuring, this upgrade is safe and improves type clarity.

If you relied on failed being a FlameFrame<never>: You may see TypeScript errors. The fix is simple: treat failed as BareFrame and don't access .schema on it.

Release Details

  • Date: 2026-04-05
  • Version: v0.66.0
  • gaslamp GAS version: 125
  • pilotlamp GAS version: 83
  • Files Changed: 5
  • Key Commits:
    • 8e285c66 refactor(flameframe): change failed return type from FlameFrame<never> to BareFrame
    • 778ef10d refactor(flameframe): make schema parameter required
    • 018b1131 docs(flameframe): unify FlameFrame.from examples to always return {passed, failed}
    • 4c82ebeb docs(flameframe): mark toDataFrame as deprecated since v0.65.0

Migration from v0.65.0

No migration steps needed. This is a type refinement release.

If TypeScript reports errors about failed.schema, remove that access:

TypeScript
// Before (v0.65.0)
const { passed, failed } = FlameFrame.from(df, schema);
console.log(failed.schema); // ✗ No longer available

// After (v0.66.0)
const { passed, failed } = FlameFrame.from(df, schema);
// failed is BareFrame, use it directly without accessing schema

Known Issues

None.

Next Steps

  • Continue refinements to FlameFrame based on user feedback
  • Explore additional validation patterns for complex schemas