User Guides¶

gaslamp is a Google Apps Script library that brings pandas/polars-style DataFrame operations and runtime type safety to a JavaScript-only environment.

This guide explains why gaslamp exists, what problems it solves, and which feature to reach for first.

Why gaslamp?¶

Google Sheets data arrives as a raw 2D array when you call getValues(). Working with index numbers instead of column names is error-prone and hard to read.

gaslamp solves this by wrapping that raw data in a BareFrame — a DataFrame that lets you access and manipulate data by column name.

JavaScript

// Standard approach: index numbers
const values = sheet.getDataRange().getValues();
const age = values[1][2];  // Which row? Which column? Unclear.

// With gaslamp: column names
const df = gaslamp.BareFrame.fromSheet(sheet);
const ages = df.col("age");  // Clear and readable.

Start here. A single call to BareFrame.fromSheet is all you need to get going.

What You Can Do with BareFrame¶

Once your data is in a BareFrame, common sheet operations become straightforward:

JavaScript

const df = gaslamp.BareFrame.fromSheet(sheet);

// Extract only the columns you need
const subset = df.select(["name", "age"]);

// Get only rows where age >= 18
const adults = df.filter(row => row.get("age") >= 18);

// The same condition using Expression
const adults2 = df.filter(gaslamp.Expression.col("age").ge(18).toFunction());

// Count records by category
const summary = df.groupBy(["category"]).count();

// Aggregate time-series data by week
const weekly = df.resampleBy("date", "1w").sum(["price"]);

For the full operation reference, see DataFrame and Google Sheets.

Adding Validation with FlameFrame¶

When data comes from a spreadsheet, it may not match what your code expects. FlameFrame adds a validation step on top of BareFrame, so type errors are caught immediately when you read the data.

JavaScript

const schema = {
  name: gaslamp.FlameGuards.isString,
  age:  gaslamp.FlameGuards.isNumber,
};

const df = gaslamp.BareFrame.fromSheet(sheet);
const { passed, failed } = gaslamp.FlameFrame.from(df, schema);

if (failed.length > 0) {
  console.error(failed.display());
}

FlameFrame is not a replacement for BareFrame — it is a validation layer you add when you need it. You can use BareFrame freely and introduce FlameFrame at any point.

For the full validation reference, see FlameFrame and Schema Validation.

Standalone Type Checking with FlameWright¶

FlameWright and FlameGuards work independently of DataFrames entirely. Since Google Apps Script does not support TypeScript at runtime, type checking must happen in code. These tools let you validate any value, anywhere:

JavaScript

function processValue(value) {
  if (gaslamp.FlameGuards.isNumber(value)) {
    return value * 2;
  }
  throw new Error("Expected a number");
}

For the full type validation reference, see FlameWright: Runtime Type Validation.

Getting Started¶

Begin with the guide that matches what you want to do:

DataFrame and Google Sheets — Read and write sheet data with BareFrame
Inspecting Data — Inspect DataFrame contents with toString, toTableString, display
Extracting Columns — Select DataFrame columns with select
Filtering Rows — Filter DataFrame rows with filter
Grouping Rows — Group DataFrame rows by columns with groupBy
Resampling by Time — Group DataFrame rows by time with resampleBy
Pivoting Data — Transform long-format data to wide-format with pivot
Unfolding Column Groups — Expand side-by-side column groups into rows with unfoldColumns
Expression Filtering — chainable filter conditions
FlameFrame and Schema Validation — add type validation to your workflow
FlameWright: Runtime Type Validation — validate any value at runtime
getTypeOf: Safe Type Checking — type detection across GAS script boundaries
Migration Guide — transitioning from raw GAS API, plain arrays, or pandas

Deeper Understanding¶

If you're curious about the design philosophy behind gaslamp's architecture, see the Conceptual Guides:

BareFrame-First Design — Why transformation and validation are separate concerns
GroupedFrame and Aggregation — Why grouping and aggregation are separate operations
Expressions and Predicates — Why filters are built, not evaluated on the fly
FlameFrame and Validation — Why validation is a gate, not a transformer
LazyFrame and Deferred Evaluation — Why we defer evaluation to apply optimizations
FlameWright and Runtime Type Safety — Why type guards are essential in GAS

These guides explain the why behind each feature, helping you extend and maintain the library with confidence.