한국어 | 日本語

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.

Quick start

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

What happens to the Sheet? The write commits to local SQLite immediately — the application request never waits on Google. When the sync service is enabled, Hikoutei later projects the entity to the registered Google Sheet in the background. Human edits made in the sheet are observed, validated, and either accepted back into SQLite or recorded as conflicts, never silently overwritten.

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.

When to use Hikoutei

Hikoutei is a good fit for:

• MVPs and prototypes where a spreadsheet is part of the product workflow.
• Internal tools and low-traffic administrative applications.
• Teams that want typed application data while keeping Sheets easy for people to inspect.
• Services that can use SQLite locally and accept asynchronous Sheet updates.

When to choose something else

Use a conventional database and direct Google APIs when you need:

• Strong transactions across many rows or services.
• High write throughput or many concurrent writers.
• Complex queries, joins, or reporting workloads.
• Multi-server or multi-region coordination.
• Immediate read-after-write consistency in Google Sheets.
• Google Sheets to be the primary database for the application.

Is Hikoutei the right abstraction for you?

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.

Google Sheets setup

Google Sheets synchronization is a service-side concern. Applications do not import a provider client, pass Sheet routes to createTypedSheets(), or choose an operation for each write — the root API accepts only dbName and entities. The sync runtime uses one internal Google Sheets API provider with a service account — no Apps Script deployment. Sync auto-start is selected by HIKOUTEI_SYNC_SPREADSHEET_URL plus GOOGLE_APPLICATION_CREDENTIALS; there is no public googleSheetsApi bootstrap option to configure.

Fastest path: install the gcloud CLI, then run npx hikoutei setup from your project directory. On an interactive terminal it offers (press Enter) to start gcloud auth login --enable-gdrive-access --force for you when the active account is missing or lacks Drive access — you only complete the browser approval yourself. (In --yes, CI, or non-TTY sessions, run that login command yourself first.) Setup then creates the project, service account, and key, creates a spreadsheet owned by your account, shares it with the service account as an Editor, verifies service-account access, and writes GOOGLE_APPLICATION_CREDENTIALS plus HIKOUTEI_SYNC_SPREADSHEET_URL into your .env. The human access token is used in memory only and never stored. Automatic setup runs on macOS and Linux; on Windows a non-dry-run is refused before any mutation and manual setup is available. Interrupted runs resume from a local checkpoint (.hikoutei-setup-state.json); a spreadsheet create whose outcome is unknown is reconciled by its creation marker on the next run and setup never creates a second spreadsheet (inspect Drive and rerun if setup reports sheet_create_uncertain, and a create rejected up front with HTTP 400/403 plus a confirmed-zero marker lookup rolls back to key_ready so a corrected rerun starts a fresh marker). Sharing is write-ahead too: spreadsheet_share_started is persisted before the idempotent SA writer permission ensure and spreadsheet_shared after it, so a crash between the remote permission mutation and the checkpoint write resumes the ensure on the next run and never creates a second spreadsheet. The service-account key is created under a write-ahead contract too: the user-managed key list is recorded as a baseline before the single gcloud key create, and key_create_started/key_ready checkpoints let a crashed run recover a staged or installed key instead of creating a second one. Only the invocation that just persisted key_create_started may issue the one key create; resumed runs are reconcile-only and, when no credential and no post-baseline key are visible, poll the key list plus staged/final evidence for up to two minutes (2, 4, 8, 16, 30, 30, 30 s) before failing with key_create_uncertain — the create is never retried automatically. An unmatched user-managed key with no local credential is never deleted automatically — setup fails with key_create_uncertain and you inspect the key list in the Google Cloud console before rerunning (a verified-absent state requires removing the setup state file to reset the key checkpoint); reused keys are enforced to owner-only mode 600. An exclusive lock directory (.hikoutei-setup-state.json.lock) prevents concurrent runs and is never removed automatically: a crash leaves an empty lock directory behind, and removing it manually is required only when you are certain no setup is running. Starting fresh requires removing or moving both the checkpoint and the key file, or passing --project to recover an existing key — checkpointed or identity-matched cloud resources are reused, and setup never deletes cloud resources. The manual steps below remain available for advanced setups.

Setup progress. hikoutei setup reports step-by-step progress to stderr across the ten setup phases (cloud auth, Drive access, project, APIs, service account, service-account key, spreadsheet, share, service-account access, output): an overall bar advances only when a phase actually completes — it is never an ETA and never guesses a percentage — and a detail line shows the bounded propagation checks (how many of the eight key/access checks have run) and the known 2, 4, 8, 16, 30, 30, 30 s waits, with a fixed working… label for unknown-duration steps. On an interactive terminal the four-line block redraws in place; in CI, non-TTY, or NO_COLOR sessions one static line is printed per phase/retry event with no control sequences. Progress pauses and the block is cleared during the interactive gcloud auth login handoff and resumes with the retry. Progress never prints credentials, tokens, keys, project ids, emails, paths, or raw command output, and it can never change the setup result or exit code; --dry-run prints the command plan only.

Read the full README on GitHub →