Spreadsheet DB

한국어 | 日本語

什么是 Hikoutei？

Hikoutei 为 TypeScript 应用提供由本地 SQLite 支持的带类型实体 API，并将已提交的更改异步同步到 Google Sheets。

应用执行常规读写时无需等待 Google Sheets。Sheets 仍可用于查看、运营和轻量级人工协作。

Hikoutei 不是原始 Sheets API 封装，也不是 PostgreSQL 的替代品， 并且不会将 Google Sheets 视为权威的应用数据库。SQLite 是事实来源；Sheets 是面向用户的视图。

为什么选择 Hikoutei？

• 定义带类型的实体，而不必手动转换 Sheet 行。
• 通过本地 SQLite 读写，无需等待 Google Sheets。
• 在后台将已提交的更改同步到 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 许可证 发布。