# GASsma

> GASsma は、Google スプレッドシートを Prisma ライクな型安全 API でデータベースのように操作できる Google Apps Script (GAS) ライブラリです。CRUD 操作・フィルタリング・ソート・ページネーション・集計・リレーション・ネストされた書き込みに対応しています。

ローカル開発では `npm i gassma`（clasp + バンドラ構成）でインストールできます。GAS ライブラリとして使う場合はスクリプト ID `1ZVuWMUYs4hVKDCcP3nVw74AY48VqLm50wRceKIQLFKL0wf4Hyou-FIBH` を追加してください。

以下のリンクは各ページの Markdown 版（ページ URL + `.md`）を指しています。`.md` を外すと HTML 版になります。英語版の目次は https://gassma.io/en/llms.txt にあります（各ページ URL の `/docs/` を `/en/docs/` に置き換えると英語版ページになります）。

## Getting Started

- [GASsma とは](https://gassma.io/docs/intro.md): 概要と動機: 素の GAS でのスプレッドシート操作が保守しにくい理由（getRange の指定ミスや数式インジェクション）と、GASsma がそれをどう解決するか
- [導入方法](https://gassma.io/docs/installation.md): GAS スクリプトエディタへの導入方法と、ローカル開発向けの npm でのインストール方法
- [基本](https://gassma.io/docs/reference/basic.md): GassmaClient の初期化、シートへのアクセス、コンストラクタオプション、共通クエリオプション（where, select, omit, orderBy, take, skip）

## Reading Data

- [findMany()](https://gassma.io/docs/reference/crud/read/findMany.md): where、orderBy、take/skip、カーソルページネーション、distinct を使って複数のレコードを取得する
- [findFirst()](https://gassma.io/docs/reference/crud/read/findFirst.md): where 条件に合致する最初のレコードを取得する。合致するものがなければ null を返す
- [findFirstOrThrow()](https://gassma.io/docs/reference/crud/read/findFirstOrThrow.md): findFirst と同様だが、レコードが見つからない場合に NotFoundError を投げる

## Writing Data

- [create()](https://gassma.io/docs/reference/crud/create/create.md): レコードを 1 件作成する。select/omit/include とネストされた書き込みに対応
- [createMany()](https://gassma.io/docs/reference/crud/create/createMany.md): 複数のレコードを一括作成し、作成件数を取得する
- [createManyAndReturn()](https://gassma.io/docs/reference/crud/create/createManyAndReturn.md): 複数のレコードを一括作成し、作成したレコードを返す
- [update()](https://gassma.io/docs/reference/crud/update/update.md): レコードを 1 件更新する。数値のアトミック操作（increment/decrement/multiply/divide）とネストされた書き込みに対応
- [updateMany()](https://gassma.io/docs/reference/crud/update/updateMany.md): 条件に合致するすべてのレコードを更新し、更新件数を取得する。limit に対応
- [updateManyAndReturn()](https://gassma.io/docs/reference/crud/update/updateManyAndReturn.md): 条件に合致するすべてのレコードを更新し、更新したレコードを返す
- [upsert()](https://gassma.io/docs/reference/crud/update/upsert.md): レコードが存在すれば更新し、存在しなければ作成する
- [delete()](https://gassma.io/docs/reference/crud/delete/delete.md): レコードを 1 件削除し、削除したレコードを返す
- [deleteMany()](https://gassma.io/docs/reference/crud/delete/deleteMany.md): 条件に合致するすべてのレコードを削除し、削除件数を取得する。limit に対応

## Aggregation

- [aggregate()](https://gassma.io/docs/reference/statistics/aggregate.md): _avg、_sum、_min、_max、_count などの集計を行う
- [count()](https://gassma.io/docs/reference/statistics/count.md): 条件に合致するレコードの件数を数える
- [groupBy()](https://gassma.io/docs/reference/statistics/groupBy.md): フィールドでレコードをグループ化してグループごとに集計し、having でグループを絞り込む

## Relations

- [リレーション定義](https://gassma.io/docs/reference/relation/definition.md): シート間の oneToMany・oneToOne・manyToOne・manyToMany リレーションの定義方法
- [include](https://gassma.io/docs/reference/relation/include.md): where/orderBy/select オプション、ネストした include、リレーションの _count を使って関連レコードを取得する
- [where リレーションフィルタ](https://gassma.io/docs/reference/relation/where-relation-filter.md): some/every/none（リストリレーション）と is/isNot（単一リレーション）で関連レコードによる絞り込みを行う
- [onDelete](https://gassma.io/docs/reference/relation/on-delete.md): 削除時の参照アクション（Cascade、SetNull、Restrict、NoAction）
- [Nested Write（create）](https://gassma.io/docs/reference/relation/nested-write.md): create の中で create/connect/connectOrCreate を使って関連レコードを書き込む
- [onUpdate](https://gassma.io/docs/reference/relation/on-update.md): 更新時の参照アクション（Cascade、SetNull、Restrict、NoAction）
- [Nested Write（update）](https://gassma.io/docs/reference/relation/nested-write-update.md): update の中で update/delete/deleteMany/disconnect/set を使って関連レコードを変更する

## Configuration

- [changeSettings()](https://gassma.io/docs/reference/settings/changeSettings.md): シートのデータ範囲（開始行・列範囲）を設定する
- [グローバル omit](https://gassma.io/docs/reference/config/global-omit.md): シートごとに、結果からデフォルトで除外するフィールドを設定する
- [defaults（@default）](https://gassma.io/docs/reference/config/defaults.md): 作成時にフィールド値を固定値または関数で自動設定する（@default）
- [updatedAt（@updatedAt）](https://gassma.io/docs/reference/config/updated-at.md): 作成・更新時にタイムスタンプを自動設定する（@updatedAt）
- [ignore / ignoreSheets（@ignore / @@ignore）](https://gassma.io/docs/reference/config/ignore.md): フィールドやシート全体をすべての操作の対象から除外する（@ignore / @@ignore）
- [map / mapSheets（@map / @@map）](https://gassma.io/docs/reference/config/map.md): コード側の名前をスプレッドシートのヘッダー名・シート名に対応付ける（@map / @@map）
- [autoincrement](https://gassma.io/docs/reference/config/autoincrement.md): LockService + PropertiesService を使ったフィールドの自動インクリメント（GAS のみ）
- [strictUndefinedChecks / Gassma.skip](https://gassma.io/docs/reference/config/strict-undefined-checks.md): Prisma の strictUndefinedChecks（Preview 機能）と Prisma.skip に相当する機能です。クエリ入力に紛れ込んだ意図しない undefined を実行時エラーとして検出し、フィールドを省略したい場合は Gassma.skip で明示的に指定できるようになります。

## Advanced

- [$extends（query）](https://gassma.io/docs/reference/client-extensions/query.md): $extends の query コンポーネントは、各操作の実行に割り込むクエリフックを登録するための機能です。Prisma のクライアント拡張（$extends の query）に相当します。フックの中で args を書き換える、結果を加工する、実際の操作を実行せずに短絡する、といった制御ができます。
- [$extends（result）](https://gassma.io/docs/reference/client-extensions/result.md): $extends の result コンポーネントは、クエリ結果のレコードに算出フィールド（computed fields）を追加するための機能です。Prisma のクライアント拡張（$extends の result）に相当します。既存のスカラーフィールドから新しいフィールドを計算し、結果に含めることができます。
- [$transaction（トランザクション）](https://gassma.io/docs/reference/transaction.md): $transaction でコールバック内の書き込みをまとめてコミットする。エラー時は 1 セルも書き込まれない。maxWait / timeout / rollback オプション
- [Prisma スキーマを利用したローカル開発](https://gassma.io/docs/reference/type-generation.md): gassma CLI（generate/init/validate/format）と gassma.config.ts を使い、Prisma 形式のスキーマから型安全なクライアントを生成する
- [書き込みの原子性と同時実行](https://gassma.io/docs/reference/write-atomicity.md): Nested write やカスケードは複数シートへの書き込みをバッファし、エラー時は 1 行も書かれない。この保証が及ばないケース（API 失敗・同時編集）と $transaction による対策
- [bootstrap（ローカル開発環境のセットアップ）](https://gassma.io/docs/reference/bootstrap.md): npx gassma bootstrap で clasp + esbuild + TypeScript + GASsma のローカル開発環境を一発でセットアップする
- [fields（列同士の比較）](https://gassma.io/docs/reference/fields.md): FieldRef を使って where 条件内で同じ行の列同士を比較する
- [migrate / db push（シートの同期）](https://gassma.io/docs/reference/migrate.md): npx gassma migrate / npx gassma db push で、スキーマに合わせてスプレッドシートのシートと列を同期する GAS 関数を生成する
- [raw（数式の書き込み）](https://gassma.io/docs/reference/raw.md): Gassma.raw で数式インジェクション対策の自動エスケープをセル単位で回避し、セルに数式をそのまま書き込む
- [エラー一覧](https://gassma.io/docs/reference/errors.md): GASsma が投げるエラークラスの一覧と発生条件

## Optional

- [llms-full.txt](https://gassma.io/llms-full.txt): 全ドキュメントページの本文を 1 ファイルに連結したもの
- [GitHub repository](https://github.com/akahoshi1421/gassma): ソースコード、Issue、サンプル
- [npm package](https://www.npmjs.com/package/gassma): パッケージの詳細とリリース履歴