gas-spreadsheet-object-mapper

English | 日本語


Google Apps Scriptにて、スプレッドシートに対する型付きのCRUDを実現するパッケージです。

型定義にはTypeScriptのtypeではなくclassを使用するため、JavaScriptでも恩恵を受けることができます。

Usage

前提

- claspを導入済みでローカルでGoogleAppsScriptの開発を行う環境がある。
- esbuild等のバンドラーを導入済みでnpmパッケージを使用したコードをビルドできる環境がある。

スプレッドシートにシートを追加

スプレッドシートに読み書き対象となる表を作成します。

- 1行目に必ずカラム名を記入してください。
- プライマリキーとなるカラム（ユニークなstringまたはnumber）を1つ用意する必要があります。

!image

Install

``shell
npm install @fumigoro/gas-spreadsheet-object-mapper
`

データのclassを定義

@SpreadSheetColumnデコレーターを使用して、各メンバとスプレッドシート上のカラム名をマッピングします。

- メンバー変数idは必ず定義し、プライマリキーとなるスプレッドシートのカラム名とマッピングしてください。idの型はstringまたはnumberのみ利用できます。
- カラム名には日本語も使用できます。
- スプレッドシート側のカラムの順序とメンバーの定義順序を一致させる必要はありません。

`ts
import { SpreadSheetColumn } from "@fumigoro/gas-spreadsheet-object-mapper";

class User {
@SpreadSheetColumn('ID')
id: number;

@SpreadSheetColumn('Name')
name: string;

@SpreadSheetColumn('Age')
age: number;

// このようにして、スプレッドシートから値を読み込む際のパース関数や書き込む際のシリアライズ関数を追加することも可能です。
@SpreadSheetColumn('CreatedAt', {
parser: (value: any) => new Date(value),
serializer: (value: any) => value.toISOString()
})
createdAt: Date;
}
`

SpreadSheetMapperインスタンスの作成

定義したデータクラスを用いてSpreadSheetMapperインスタンスを作成します。

SpreadSheetMapperはそのコンストラクタ内で全ての行のデータを読み出してメモリ上に持ちます。

`ts
import { SpreadSheetMapper } from "@fumigoro/gas-spreadsheet-object-mapper";

const spreadSheetId = 'YOUR_SPREADSHEET_ID';
const sheetName = 'Users';
const userSheetMapper = new SpreadSheetMapper(spreadSheetId, sheetName, User);
`

データのCRUD

$3

SpreadSheetMapperインスタンスがメモリ上に持つ全てのデータを返します。

`ts
const users = userSheetMapper.list();
`

$3

SpreadSheetMapperインスタンスがメモリ上に持つ全てのデータから、idが一致するデータを返します。

`ts
const user = userSheetMapper.get('target_user_id');
`

$3

idが一致する行を更新し、スプレッドシートに書き込みます。
SpreadSheetMapperインスタンスがメモリ上にもつデータも更新されます。

`ts
userSheetMapper.updateAndSave({ id: 1, name: 'Jone', age: 36, createdAt: new Date() });
`

$3

新しいデータを挿入し、スプレッドシートに書き込みます。

`ts
userSheetMapper.createAndSave({ id: 4, name: 'Bob', age: 10, createdAt: new Date() });
`

$3

idが一致するデータを削除します。
SpreadSheetMapperインスタンスが持つデータとスプレッドシート両方から削除されます。
スプレッドシートにおいても行ごと削除され上に詰められます。

`ts
userSheetMapper.deleteAndSave(4);
``