Hikoutei

Keep your app fast with SQLite. Keep your workflow visible in Google Sheets.

A typed repository and safe write layer for Google Sheets-backed MVPs: your application reads and writes local SQLite through typed entities, and committed changes are asynchronously projected to Google Sheets for human review and lightweight collaboration.

npm · Quick start · Issues

What is Hikoutei?

Hikoutei gives TypeScript applications a typed entity API backed by local SQLite, then asynchronously synchronizes committed changes to Google Sheets.

Your application does not wait on Google Sheets for normal reads and writes. Sheets remains available for inspection, operations, and lightweight human collaboration.

Hikoutei is not a raw Sheets API wrapper, not a replacement for PostgreSQL, and it does not treat Google Sheets as the authoritative application database. SQLite is the source of truth; Sheets is the human-facing view.

Why Hikoutei?

Define typed entities instead of manually converting Sheet rows.
Read and write through local SQLite without waiting for Google Sheets.
Synchronize committed changes to Sheets in the background.
Detect unexpected column changes and duplicate headers.
Avoid overwriting newer Sheet edits during conflicting updates.

Hikoutei does not replace google-spreadsheet or @googleapis/sheets — it sits one level above them. If you only need raw spreadsheet access, use the API client directly.

Capability	Hikoutei	google-spreadsheet	@googleapis/sheets
Typed entity model	✅	❌	❌
Fast local application reads	✅	❌	❌
Async projection to Sheets	✅	❌	❌
Durable write retry and deduplication	✅	❌	❌
Conflict-aware Sheet updates	✅	❌	❌
Direct row and cell manipulation	Limited	✅	✅
Full Google Sheets API access	Provider only	Partial	✅

Installation

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

Installing the library does not touch Google Cloud — it runs local-only (SQLite) by default. Run the setup command below only when you want Sheet sync.

Setup (Google Sheets sync)

One-time, interactive. Install the gcloud CLI, then:

npx hikoutei setup

This creates the Cloud project, service account, key, and spreadsheet, and writes .env for you. Without HIKOUTEI_SYNC_SPREADSHEET_URL, createTypedSheets() stays local-only (SQLite). Details, credential pools, quota guidance, and manual setup: Google Sheets setup.

Usage

Define a scalar entity and use the local SQLite authority through a request-local manager.

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();
}

More reads, transactions, and operators: Quick start.

Writes commit to local SQLite immediately — the request never waits on Google. Human edits in the Sheet flow back through polling — accepted into SQLite or recorded as conflicts, never silently overwritten. The full pipeline (outbox, delivery, conflict handling) is covered in Write and synchronization flow.