Spreadsheet DB

한국어 | 日本語

Hikoutei とは？

Hikoutei は、ローカルの SQLite をバックエンドとする型付きエンティティ API を TypeScript アプリケーションに提供し、コミットされた変更を非同期で Google Sheets に同期します。

通常の読み書きで、アプリケーションが Google Sheets の応答を待つことはありません。Sheets は、確認、運用、軽量な人間同士の共同作業に引き続き利用できます。

Hikoutei は Sheets API の薄いラッパーでも、PostgreSQL の代替でもありません。また、Google Sheets をアプリケーションの正式なデータベースとして扱うこともありません。信頼できる唯一の情報源は SQLite であり、Sheets は人が利用するためのビューです。

Hikoutei を選ぶ理由

• Sheet の行を手作業で変換する代わりに、型付きエンティティを定義できます。
• Google Sheets の応答を待たずに、ローカルの SQLite を通じて読み書きできます。
• コミットされた変更をバックグラウンドで Sheets に同期できます。
• 予期しない列の変更や重複するヘッダーを検出できます。
• 競合する更新時に、Sheet の新しい編集内容を上書きしないようにできます。

Hikoutei は google-spreadsheet や @googleapis/sheets の代替ではなく、それらの一段上に位置します。スプレッドシートへの直接アクセスのみが必要な場合は、API クライアントを直接使用してください。

機能	Hikoutei	google-spreadsheet	@googleapis/sheets
型付きエンティティモデル	✅	❌	❌
ローカルアプリケーションでの高速な読み取り	✅	❌	❌
Sheets への非同期反映	✅	❌	❌
永続的な書き込みリトライと重複排除	✅	❌	❌
競合を考慮した Sheet の更新	✅	❌	❌
行とセルの直接操作	制限あり	✅	✅
Google Sheets API への完全なアクセス	プロバイダーのみ	一部	✅

インストール

npm install hikoutei @mikro-orm/core @mikro-orm/sql

ライブラリをインストールしても Google Cloud には接続しません。デフォルトではローカル（SQLite）のみで動作します。Sheet の同期が必要な場合に限り、以下のセットアップコマンドを実行してください。

セットアップ（Google Sheets 同期）

初回のみ、対話形式で行います。gcloud CLI をインストールしてから、次を実行してください。

npx hikoutei setup

これにより Cloud プロジェクト、サービスアカウント、キー、スプレッドシートが作成され、.env も自動で書き込まれます。HIKOUTEI_SYNC_SPREADSHEET_URL が設定されていない場合、createTypedSheets() はローカル（SQLite）のみで動作します。詳細、認証情報プール、クォータに関するガイダンス、手動セットアップについては、Google Sheets のセットアップをご覧ください。

使い方

スカラーエンティティを定義し、リクエストごとに作成されるマネージャーを通じて、ローカルの SQLite を信頼できるデータソースとして利用します。

import { createTypedSheets, defineTypedSheetsEntity } from "hikoutei";

const User = defineTypedSheetsEntity({
  name: "User",
  tableName: "users",
  properties: {
    id: { type: "string", primary: true },
    name: { type: "string" },
    age: { type: "number" },
    active: { type: "boolean" },
  },
});

const hikoutei = await createTypedSheets({
  dbName: "./hikoutei.sqlite",
  entities: [User],
});

const em = hikoutei.em.fork();
const user = em.create(User, { id: "u1", name: "Ada", age: 36, active: true });
em.persist(user);
await em.flush();

user.name = "Ada Lovelace";
await em.flush();

const loaded = await em.findOne(User, { id: "u1" });
if (loaded !== null) {
  em.remove(loaded);
  await em.flush();
}

その他の読み取り、トランザクション、演算子については、クイックスタートをご覧ください。

書き込みは直ちにローカルの SQLite にコミットされるため、リクエストが Google の応答を待つことはありません。Sheet 上の人による編集はポーリングを通じて取り込まれ、SQLite に反映されるか競合として記録されます。黙って上書きされることはありません。アウトボックス、配信、競合処理を含むパイプライン全体については、書き込みと同期のフローをご覧ください。

詳細情報

• クイックスタート — インストール、ORM のライフサイクル、同期のセットアップ。
• アーキテクチャ — ローカルストアと Sheet ビュー。
• 書き込みと同期のフロー — 配信と復旧。
• 制限事項 — 別の方法を選ぶべき場合。
• プロジェクトの状況とロードマップ — 完了した内容と今後の予定。

ライセンス

Hikoutei は MIT ライセンスのもとで公開されています。