First Steps - 5 Minute Quickstart¶

Let's get you up and running with gaslamp in just 5 minutes! Each example below is ready to copy and paste into your Google Apps Script project.

What You'll Learn¶

By the end of this guide, you'll know how to:

Read data from a sheet into a BareFrame
Define a validation schema with FlameGuards
Validate data with FlameFrame.from
Filter and transform data with BareFrame
Write results back to sheets

Prerequisites¶

gaslamp installed in your GAS project (Installation Guide)
A Google Sheets document (any will work)

Step 1: Your First FlameFrame¶

Copy and paste this function, then run it:

JavaScript

function step1_firstFlameFrame() {
  // Step 1: Prepare data — headers in the first row
  const data = [
    ['product',  'price', 'category'],
    ['Laptop',    1200,   'Electronics'],
    ['Phone',      800,   'Electronics'],
    ['Desk',       150,   'Furniture'],
    ['Chair',       75,   'Furniture'],
  ];

  // Step 2: Create a BareFrame from the 2D array
  const df = gaslamp.BareFrame.fromArrays(data);

  // Step 3: Define a validation schema
  const schema = {
    product:  gaslamp.FlameGuards.isString,
    price:    gaslamp.FlameGuards.isNumber,
    category: gaslamp.FlameGuards.isString,
  };

  // Step 4: Validate with FlameFrame
  const { passed, failed } = gaslamp.FlameFrame.from(df, schema);

  // Step 5: Check for validation errors
  if (failed.length > 0) {
    console.warn('Validation errors found:');
    console.error(failed.display());
    return;
  }

  // Step 6: Use the validated frame
  console.log('Our data:');
  console.log(passed.display());

  console.log(`Rows: ${passed.length}, Columns: ${passed.headers.length}`);
  console.log(`Column names: ${passed.headers}`);
}

Expected output: A formatted table with your data plus basic info.

Step 2: Read from Google Sheets¶

Create some data in a Google Sheets document, then run this:

JavaScript

function step2_readFromSheet() {
  // Read from the active sheet
  // fromSheet() reads all data and treats the first row as headers
  const df = gaslamp.BareFrame.fromSheet(SpreadsheetApp.getActiveSheet());

  // Define a schema matching your sheet's columns
  const schema = {
    name:  gaslamp.FlameGuards.isString,
    score: gaslamp.FlameGuards.isNumber,
  };

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

  if (failed.length > 0) {
    console.warn('Validation errors found:');
    console.error(failed.display());
    return;
  }

  console.log('Data from sheet:');
  console.log(passed.display());

  console.log(`Found ${df.length} rows with columns: ${df.headers}`);
}

What this does: Reads all data from the active sheet, validates types, and displays the result.

Step 3: Filter and Write to New Sheet¶

This example filters data and writes the result to a new sheet:

JavaScript

function step3_filterAndExport() {
  const data = [
    ['item',    'price', 'quantity', 'category'],
    ['Laptop',   1200,    2,         'Electronics'],
    ['Phone',     800,    5,         'Electronics'],
    ['Tablet',    400,    3,         'Electronics'],
    ['Desk',      150,    1,         'Furniture'],
    ['Chair',      75,    4,         'Furniture'],
  ];

  const schema = {
    item:     gaslamp.FlameGuards.isString,
    price:    gaslamp.FlameGuards.isNumber,
    quantity: gaslamp.FlameGuards.isNumber,
    category: gaslamp.FlameGuards.isString,
  };

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

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

  // Use BareFrame for data operations
  const expensive = df
    .filter((row) => row.get('price') > 300)
    .withColumn('total', (row) => row.get('price') * row.get('quantity'));

  console.log('Expensive items with totals:');
  console.log(expensive.display());

  // Write to a new sheet
  const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = spreadsheet.getSheetByName('Expensive Items')
    ?? spreadsheet.insertSheet('Expensive Items');

  expensive.toSheet(sheet);

  console.log(`Sheet URL: ${spreadsheet.getUrl()}`);
}

What this does: Validates data, filters rows and adds a calculated column using BareFrame, then writes to a sheet.

Congratulations¶

You've just learned the core workflow:

Read data with BareFrame.fromSheet or BareFrame.fromArrays
Define a schema with FlameGuards
Validate with FlameFrame.from(df, schema)
Check errors with failed.length and inspect failed.display() for full table output
Transform with passed using BareFrame methods
Write to sheets with .toSheet(sheet)

Key Concepts¶

Defining a Schema¶

JavaScript

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

Available guards: isString, isNumber, isBoolean, isNull, isStringOrNumber

Creating a BareFrame¶

JavaScript

// From a 2D array (headers in first row)
const df = gaslamp.BareFrame.fromArrays(data);

// From a sheet
const df = gaslamp.BareFrame.fromSheet(sheet);

// From a column object
const df = gaslamp.BareFrame.fromColumns({ name: ['Alice', 'Bob'], age: [25, 30] });

Validating with FlameFrame¶

JavaScript

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

Common Transformations¶

All transformations use BareFrame methods:

JavaScript

// Use df for pre-validation transformations
const filtered = df.filter((row) => row.get('age') > 18);
const selected = df.select(['name', 'age']);
const dropped = df.drop(['internal_id']);
const withCol = df.withColumn(
  'fullName',
  (row) => `${row.get('firstName')} ${row.get('lastName')}`,
);
const renamed = df.rename({ name: 'fullName' });

// After validation, use passed for post-validation work
const validFiltered = passed.filter((row) => row.get('age') > 18);

Sheet Integration¶

JavaScript

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

// passed is a BareFrame with validated rows only
// Write to sheet (clears existing content by default)
passed.toSheet(sheet);

// Append without clearing
passed.toSheet(sheet, { clear: false, header: false, startRow: sheet.getLastRow() + 1 });

Next Steps¶

Now that you know the basics:

Try practical workflows - Common business scenarios
Understand the design philosophy - Learn why gaslamp is designed this way
Explore user guides - Comprehensive documentation on all features
Browse cookbooks - Real-world examples and patterns

Troubleshooting¶

"gaslamp is not defined": Check that gaslamp is properly installed (Installation Guide)

failed.length > 0: Use failed.display() to see which cells failed

Empty results: Check your filter conditions with console.log() statements

Sheet errors: Verify you have permission to create/modify sheets

Ready for real-world examples? Check out Practical Workflows!