Conceptual Guides

This section explains the philosophy and concepts behind gaslamp's design. If you're extending or maintaining the library, read these guides to understand why things were built this way, not just how to use them.

Design Philosophy

gaslamp solves a core tension: Google Apps Script is simple but fragile. It's easy to write scripts, hard to write them correctly at scale.

Standard GAS code:

• Works with messy, unpredictable data (is this a string or a Date?)
• Uses manual loops and error-prone transformations
• Lacks type safety and validation
• Breaks silently when assumptions change

gaslamp's approach:

• Separate concerns: Raw data at the boundary, normalized data inside
• Use the right shape: Different data orientations for different tasks
• Build safely: Expressions, schemas, and validation to catch errors early
• Keep it simple: Pure functions, no hidden state, easy to extend

Each guide explores one piece of this philosophy. Read them to understand the "why" so you can extend or improve the library with confidence.

Guides

Start with BareFrame-First Design to understand the root principle. Then explore the rest in order.

• BareFrame-First Design — Why transformation and validation are separate concerns (foundation)
• Cell and Primitive Types — Why we separate raw GAS data from normalized data
• Data Orientation and Conversion — Why we support multiple data shapes and how to convert between them
• FlameWright and Runtime Type Safety — Why type guards are essential in GAS
• Expressions and Predicates — Why complex filters are built, not evaluated on the fly
• GroupedFrame and Aggregation — Why grouping and aggregation are separate operations
• LazyFrame and Deferred Evaluation — Why we defer evaluation to apply optimizations
• FlameFrame and Validation — Why validation is a gate, not a transformer
• ForgeFrame and Statistical Analysis — Why histograms are a specialized DataFrame operation