Skip to content

v0.37.0 - Flame Validation System for v2 (2026-03-23)

What Changed?

This release introduces the complete Flame validation system for the v2 module as a single self-contained file (src/v2/flame.ts). It consolidates FlameFactory and FlameForge statics from v1 into a unified FlameWright object, and adds GAS-scoped type guards, duck-type checks for Spreadsheet objects, and assertion/explanation helpers. All exports are re-exported from src/v2/index.ts for public access.

What's New

Main Feature: src/v2/flame.ts — Unified Flame Validation

What it does: Provides runtime type safety for GAS environments in a single module. Replaces the multi-file flamewright/ structure with a streamlined, GAS-focused API.

How to use it:

TypeScript
import { FlameGuards, FlameWright, ensure, explain } from "./v2";

// Basic type guard
if (FlameGuards.isString(value)) {
  Logger.log(value.toUpperCase());
}

// Schema validation
const isUser = FlameWright.fromSchema({
  name: FlameGuards.isString,
  age: FlameGuards.isNumber,
});

// Assertion with error context
ensure(input, FlameGuards.isString, { at: "processRow", label: "name" });

// Field-level error reporting
const errors = explain({ name: 123 }, { name: FlameGuards.isString, age: FlameGuards.isNumber });
// ["name: invalid (123)", "age: missing"]

Added

  • Flame<T> and FlameRecord<T> — core type guard signatures
  • FlameGuards — predefined guards for primitives (isString, isNumber, isBoolean, isNull, isUndefined), objects (isPlainObject, isArray, isMap, isValidDate), and GAS sheet values (isEmptyString, isStringOrNumber, isTable)
  • FlameWright — unified factory and schema utilities (arrayOf, mapOf, recordOf, enumOf, instanceOf, inRange, anyOf, nullable, fromSchema, partial, extend)
  • FlameGaslets — duck-type guards for GAS objects (isSheet, isSpreadsheet) using typeof obj["method"] === "function" checks
  • FlameOptions — options interface for error messages (at, label)
  • ensure — validates and returns a typed value, throws TypeError on failure
  • assert — narrows type in-place, throws TypeError on failure
  • explain — returns field-level error messages for schema validation
  • getTypeOf — returns a GAS-scoped type name string
  • getValuePreviewOf — returns a human-readable value preview with Map/Set support

Changed

  • FlameGaslets (was FlameGaslet internally) — aligned naming with existing FlameGaslets in flame.gaslets.ts
  • FlameWright replaces FlameFactory + FlameForge static methods — is prefix removed from factory methods (arrayOf instead of isArrayOf, etc.)
  • recordOf drops keyGuard argument — object keys are always string in GAS contexts

Is It Safe to Upgrade?

  • Breaking Changes: No
  • Backward Compatible: Yes

The new src/v2/flame.ts is additive. Existing v1 flamewright/ modules are unchanged.

Release Details

  • Date: 2026-03-23
  • Version: v0.37.0
  • gaslamp: version 80
  • pilotlamp: version 37
  • Files Changed: 10
  • Commits:
    • c2d4025 docs(v2/flame): add proper docstrings
    • a02b1d5 feat(v2/index): re-export flame.ts public API
    • 760dc7b feat(v2/flame): add simplified getTypeOf
    • 702aa2c feat(v2/flame): export getValuePreviewOf as standalone utility
    • 418f5c1 feat(v2/flame): add validation utilities
    • c2f518d feat(v2/flame): add FlameGaslets with minimal GAS duck-type guards
    • 4865fec feat(v2/flame): add FlameWright merging FlameFactory and FlameForge statics
    • 5ae9767 feat(v2/flame): add FlameGuards with GAS-scoped type guards
    • 07f1e12 feat(v2): add core Flame type definitions

Known Issues

  • FlameWright and FlameGaslets use as const — generic methods (partial, extend) may have reduced type inference in complex TypeScript contexts, but this has no impact in GAS runtime usage.

Next Steps

  • Add FlameTorch guards for DataFrame/Series types as v2 DataFrame implementation progresses.
  • Consider adding src/v2/flame.ts to the main bundle once v2 is stabilized.