# GASsma

> GASsma is a Google Apps Script (GAS) library that lets you operate Google Sheets like a database with a Prisma-like, type-safe API. It provides CRUD operations, filtering, sorting, pagination, aggregation, relations, and nested writes on spreadsheet data.

Install with `npm i gassma` for local development (clasp + bundler), or add it as a GAS library with Script ID `1ZVuWMUYs4hVKDCcP3nVw74AY48VqLm50wRceKIQLFKL0wf4Hyou-FIBH`.

The links below point to the Markdown version of each page (page URL + `.md`); remove the `.md` suffix for the HTML version. The Japanese index is available at https://gassma.io/llms.txt (replace `/en/docs/` with `/docs/` in any URL for the Japanese page).

## Getting Started

- [What is GASsma](https://gassma.io/en/docs/intro.md): Overview and motivation: why plain GAS spreadsheet code is hard to maintain (getRange counting mistakes, formula injection) and how GASsma solves it
- [Installation](https://gassma.io/en/docs/installation.md): How to install GASsma in the GAS script editor or via npm for local development
- [Basic](https://gassma.io/en/docs/reference/basic.md): Initializing GassmaClient, accessing sheets, constructor options, and the common query options (where, select, omit, orderBy, take, skip)

## Reading Data

- [findMany()](https://gassma.io/en/docs/reference/crud/read/findMany.md): Get multiple records with where, orderBy, take/skip, cursor pagination, and distinct
- [findFirst()](https://gassma.io/en/docs/reference/crud/read/findFirst.md): Get the first record matching a where filter, or null if none matches
- [findFirstOrThrow()](https://gassma.io/en/docs/reference/crud/read/findFirstOrThrow.md): Like findFirst but throws NotFoundError when no record matches

## Writing Data

- [create()](https://gassma.io/en/docs/reference/crud/create/create.md): Create a single record; supports select/omit/include and nested writes
- [createMany()](https://gassma.io/en/docs/reference/crud/create/createMany.md): Create multiple records at once and get the created count
- [createManyAndReturn()](https://gassma.io/en/docs/reference/crud/create/createManyAndReturn.md): Create multiple records and return the created records
- [update()](https://gassma.io/en/docs/reference/crud/update/update.md): Update a single record; supports atomic number operations (increment/decrement/multiply/divide) and nested writes
- [updateMany()](https://gassma.io/en/docs/reference/crud/update/updateMany.md): Update all matching records and get the updated count; supports limit
- [updateManyAndReturn()](https://gassma.io/en/docs/reference/crud/update/updateManyAndReturn.md): Update all matching records and return the updated records
- [upsert()](https://gassma.io/en/docs/reference/crud/update/upsert.md): Update a record if it exists, otherwise create it
- [delete()](https://gassma.io/en/docs/reference/crud/delete/delete.md): Delete a single record and return it
- [deleteMany()](https://gassma.io/en/docs/reference/crud/delete/deleteMany.md): Delete all matching records and get the deleted count; supports limit

## Aggregation

- [aggregate()](https://gassma.io/en/docs/reference/statistics/aggregate.md): Compute aggregations such as _avg, _sum, _min, _max, and _count
- [count()](https://gassma.io/en/docs/reference/statistics/count.md): Count records matching a filter
- [groupBy()](https://gassma.io/en/docs/reference/statistics/groupBy.md): Group records by fields, aggregate per group, and filter groups with having

## Relations

- [Relation Definition](https://gassma.io/en/docs/reference/relation/definition.md): Defining oneToMany, oneToOne, manyToOne, and manyToMany relations between sheets
- [include](https://gassma.io/en/docs/reference/relation/include.md): Fetch related records with where/orderBy/select options, nested include, and relation _count
- [where Relation Filter](https://gassma.io/en/docs/reference/relation/where-relation-filter.md): Filter by related records using some/every/none (list relations) and is/isNot (single relations)
- [onDelete](https://gassma.io/en/docs/reference/relation/on-delete.md): Referential actions on delete (Cascade, SetNull, Restrict, NoAction)
- [Nested Write (create)](https://gassma.io/en/docs/reference/relation/nested-write.md): Write related records inside create using create/connect/connectOrCreate
- [onUpdate](https://gassma.io/en/docs/reference/relation/on-update.md): Referential actions on update (Cascade, SetNull, Restrict, NoAction)
- [Nested Write (update)](https://gassma.io/en/docs/reference/relation/nested-write-update.md): Modify related records inside update using update/delete/deleteMany/disconnect/set

## Configuration

- [changeSettings()](https://gassma.io/en/docs/reference/settings/changeSettings.md): Configure the data range of a sheet (start row and column range)
- [Global omit](https://gassma.io/en/docs/reference/config/global-omit.md): Exclude fields from results by default per sheet
- [defaults (@default)](https://gassma.io/en/docs/reference/config/defaults.md): Auto-set field values on create with static values or functions (@default)
- [updatedAt (@updatedAt)](https://gassma.io/en/docs/reference/config/updated-at.md): Auto-set timestamps on create/update (@updatedAt)
- [ignore / ignoreSheets (@ignore / @@ignore)](https://gassma.io/en/docs/reference/config/ignore.md): Exclude fields or whole sheets from all operations (@ignore / @@ignore)
- [map / mapSheets (@map / @@map)](https://gassma.io/en/docs/reference/config/map.md): Map code-side names to spreadsheet headers and sheet names (@map / @@map)
- [autoincrement](https://gassma.io/en/docs/reference/config/autoincrement.md): Auto-increment fields using LockService + PropertiesService (GAS only)
- [strictUndefinedChecks / Gassma.skip](https://gassma.io/en/docs/reference/config/strict-undefined-checks.md): This feature corresponds to Prisma's strictUndefinedChecks (Preview feature) and Prisma.skip. It detects unintended undefined values that slip into query inputs as runtime errors, and lets you explicitly omit a field with Gassma.skip.

## Advanced

- [$extends (query)](https://gassma.io/en/docs/reference/client-extensions/query.md): The query component of $extends lets you register query hooks that intercept the execution of each operation. It corresponds to Prisma's client extensions (the query component of $extends). Inside a hook you can rewrite args, transform the result, or short-circuit without running the actual operation.
- [$extends (result)](https://gassma.io/en/docs/reference/client-extensions/result.md): The result component of $extends lets you add computed fields to the records in query results. It corresponds to Prisma's client extensions (the result component of $extends). You can compute new fields from existing scalar fields and include them in the result.
- [$transaction (Transactions)](https://gassma.io/en/docs/reference/transaction.md): Commit all writes inside a callback at once with $transaction. On error, not a single cell is written. maxWait / timeout / rollback options
- [Local Development with Prisma Schema](https://gassma.io/en/docs/reference/type-generation.md): Generate a type-safe client from a Prisma-format schema with the gassma CLI (generate/init/validate/format) and gassma.config.ts
- [Write Atomicity and Concurrency](https://gassma.io/en/docs/reference/write-atomicity.md): Nested writes and cascades buffer their writes across multiple sheets; on error, not a single row is written. Cases this guarantee does not cover (API failures, concurrent edits) and how $transaction helps
- [bootstrap (Local Development Environment Setup)](https://gassma.io/en/docs/reference/bootstrap.md): Set up a local development environment with clasp + esbuild + TypeScript + GASsma in one shot with npx gassma bootstrap
- [fields (Column Comparison)](https://gassma.io/en/docs/reference/fields.md): Compare columns within the same row in where filters using FieldRef
- [migrate / db push (Syncing Sheets)](https://gassma.io/en/docs/reference/migrate.md): Generate a GAS function that syncs your spreadsheet's sheets and columns with the schema using npx gassma migrate / npx gassma db push
- [raw (Writing Formulas)](https://gassma.io/en/docs/reference/raw.md): Use Gassma.raw to opt out of formula-injection escaping per cell and write a formula as-is
- [Error List](https://gassma.io/en/docs/reference/errors.md): List of error classes thrown by GASsma and when they occur

## Optional

- [llms-full.txt](https://gassma.io/en/llms-full.txt): The full content of every documentation page concatenated into a single file
- [GitHub repository](https://github.com/akahoshi1421/gassma): Source code, issues, and examples
- [npm package](https://www.npmjs.com/package/gassma): Package details and release history