hikoutei 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ManddarinShop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,135 @@
+[English](README.md) | [한국어](README.ko.md)
+
+<div align="center">
+
+# Hikoutei
+
+**Google Sheets を利用する MVP 向けの型付きリポジトリと安全な書き込みレイヤー**
+
+<a href="https://www.npmjs.com/package/hikoutei">npm パッケージ</a> ·
+<a href="https://github.com/ManddarinShop/Hikoutei/issues">Issues</a> ·
+<a href="apps-script/gateway/Code.gs">Apps Script Gateway</a>
+
+[![npm version](https://img.shields.io/npm/v/hikoutei?style=flat-square)](https://www.npmjs.com/package/hikoutei)
+[![license](https://img.shields.io/npm/l/hikoutei?style=flat-square)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+</div>
+
+Hikoutei は、TypeScript と Node.js のアプリケーションで Google Sheets を
+MVP や社内ワークフローの人間向けの画面として利用できるようにします。
+アプリケーションは型付きエンティティとローカル SQLite を使い、付属の
+Apps Script Gateway を通して変更を Google Sheets へ非同期に届けられます。
+
+Hikoutei の対象は意図的に限定されています。汎用データベースの代替、
+Prisma/JPA のクローン、汎用 Google Sheets API ラッパーを目的としていません。
+
+## Hikoutei が提供するもの
+
+- エンティティ中心のライフサイクル: 作成、検索、変更、永続化、削除、flush。
+- Sheet データに対する型付きフィールドマッピングとランタイム検証。
+- リモートのスプレッドシート要求を待たないローカル SQLite の読み取り。
+- 人による確認や軽い共同作業に使える非同期 Google Sheets ビュー。
+- 予期しないスキーマ変更や新しいデータを上書きする問題への保護。
+
+## インストール
+
+プロジェクトと npm パッケージ名は `hikoutei` です。
+
+```sh
+npm install hikoutei @mikro-orm/core @mikro-orm/sql
+```
+
+MikroORM パッケージはルートパッケージの optional peer dependency ですが、
+Hikoutei の組み込み SQLite アダプターを使う場合は必要です。
+
+## クイックスタート
+
+エンティティマッピングを定義したら、リクエスト単位の manager でエンティティを
+操作します。完全なマッピングと Gateway の設定は
+[クイックスタートガイド](docs/quick-start.md)を参照してください。
+
+```ts
+import { initializeMappedTypedSheetsOrm } from "hikoutei/mikro-orm";
+import { User } from "./entities/User.js";
+import { userMapping } from "./mappings/userMapping.js";
+
+const hikoutei = await initializeMappedTypedSheetsOrm({
+  dbName: "./hikoutei.sqlite",
+  entities: [User],
+  mappings: [userMapping],
+  writer: { writerId: "users-service" },
+});
+
+const em = hikoutei.em.fork();
+const user = em.create(User, { id: "u1", name: "Ada" });
+em.persist(user);
+await em.flush();
+
+user.name = "Ada Lovelace";
+await em.flush();
+```
+
+`flush()` はローカルのアプリケーション状態を更新し、設定済みの Sheet ビューへ
+反映する作業を予約します。リモートへの配信は非同期なので、[設定ガイド](docs/quick-start.md)
+に従って sync worker を実行し、Gateway をプロビジョニングしてください。
+
+## Hikoutei が適しているケース
+
+- スプレッドシートがプロダクトの業務フローの一部である MVP とプロトタイプ。
+- 社内ツールと低トラフィックの管理アプリケーション。
+- 型付きのアプリケーションデータを保ちながら、Sheets を人が簡単に確認したい
+  チーム。
+- ローカル SQLite を使うことができ、Sheets の非同期更新を受け入れられるサービス。
+
+## 別のツールを選ぶべきケース
+
+次の要件がある場合は、通常のデータベースと Google API の直接利用を検討してください。
+
+- 複数行または複数サービスにまたがる強いトランザクション。
+- 高い書き込みスループット、または多数の同時書き込み。
+- 複雑なクエリ、JOIN、レポート処理。
+- マルチサーバーまたはマルチリージョンの調整。
+- Google Sheets で即時の read-after-write 整合性が必要。
+- Google Sheets をアプリケーションの主データベースにする必要がある。
+
+## Google Sheets の設定
+
+1. サーバーアプリケーションでエンティティと Sheet のマッピングを定義します。
+2. [`apps-script/gateway/Code.gs`](apps-script/gateway/Code.gs) を Google Apps
+   Script Web App としてデプロイします。
+3. サーバーから登録済みのタブと範囲をプロビジョニングします。
+4. 保留中の変更を配信する sync worker を実行します。
+
+Gateway のシークレットはサーバーだけに保管してください。ブラウザコードに
+含めたり、Git にコミットしたりしないでください。
+
+## ドキュメント
+
+- [クイックスタート](docs/quick-start.md) — インストール、マッピング、Gateway 設定。
+- [アーキテクチャ](docs/architecture.md) — ローカルストアと Sheet ビューの関係。
+- [書き込みと同期の流れ](docs/write-and-synchronization-flow.md) — 非同期配信と復旧動作。
+- [開発ガイド](docs/development.md) — ローカル開発とテストコマンド。
+- [ベンチマーク記録](docs/sync-bulk-write-benchmark.md) — 日付ごとの測定結果と制約。
+
+## 制限事項
+
+- Google Sheets にはクォータ、レイテンシー、Apps Script の実行時間制限があります。
+- Sheet の更新は非同期なので、アプリケーションはローカル状態を読み取るべきです。
+- SQLite はサービスにローカルなもので、分散調整レイヤーではありません。
+- スキーマ変更、手動編集、競合する変更に対する運用方針は、アプリケーション側で
+  別途決める必要があります。
+
+## ロードマップ
+
+- Google Sheets から意図的なユーザー編集を取り込む機能を完成させる。
+- update/delete の競合処理と表示を改善する。
+- レジストリと Apps Script デプロイ用のセットアップツールを追加する。
+- 公開パッケージのリリースを安定化する。
+
+現在の作業については [open issues](https://github.com/ManddarinShop/Hikoutei/issues)
+を参照してください。
+
+## ライセンス
+
+Hikoutei は [MIT License](LICENSE) の下で公開されています。

package/README.ko.md

@@ -0,0 +1,138 @@
+[English](README.md) | [日本語](README.ja.md)
+
+<div align="center">
+
+# Hikoutei
+
+**Google Sheets 기반 MVP를 위한 타입 안전 리포지토리 및 안전한 쓰기 계층**
+
+<a href="https://www.npmjs.com/package/hikoutei">npm 패키지</a> ·
+<a href="https://github.com/ManddarinShop/Hikoutei/issues">이슈</a> ·
+<a href="apps-script/gateway/Code.gs">Apps Script Gateway</a>
+
+[![npm version](https://img.shields.io/npm/v/hikoutei?style=flat-square)](https://www.npmjs.com/package/hikoutei)
+[![license](https://img.shields.io/npm/l/hikoutei?style=flat-square)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+</div>
+
+Hikoutei는 TypeScript와 Node.js 애플리케이션에서 Google Sheets를 MVP 또는
+내부 업무 흐름의 사람이 읽기 쉬운 화면으로 사용할 수 있게 합니다. 애플리케이션은
+타입이 지정된 엔티티와 로컬 SQLite를 사용하고, 포함된 Apps Script Gateway를
+통해 변경 내용을 Google Sheets에 비동기적으로 전달할 수 있습니다.
+
+Hikoutei의 범위는 의도적으로 작습니다. 범용 데이터베이스 대체재, Prisma/JPA
+클론, 범용 Google Sheets API 래퍼를 목표로 하지 않습니다.
+
+## Hikoutei가 제공하는 것
+
+- 엔티티 중심 생명주기: 생성, 조회, 변경, `persist`, `remove`, `flush`.
+- Sheet 데이터에 대한 타입 필드 매핑과 런타임 검증.
+- 원격 스프레드시트 요청을 기다리지 않는 로컬 SQLite 조회.
+- 사람이 검토하고 가볍게 협업할 수 있는 비동기 Google Sheets 뷰.
+- 예상하지 못한 스키마 변경과 최신 데이터를 덮어쓰는 문제에 대한 보호.
+
+## 설치
+
+프로젝트와 npm 패키지 이름은 모두 `hikoutei`입니다.
+
+```sh
+npm install hikoutei @mikro-orm/core @mikro-orm/sql
+```
+
+MikroORM 패키지는 루트 패키지의 선택적 peer dependency이지만, Hikoutei의
+기본 SQLite 어댑터를 사용할 때는 필요합니다.
+
+## 빠른 시작
+
+엔티티 매핑을 정의한 후 요청 단위 manager로 엔티티를 다룹니다. 전체 매핑과
+Gateway 설정은 [빠른 시작 가이드](docs/quick-start.md)에 있습니다.
+
+```ts
+import { initializeMappedTypedSheetsOrm } from "hikoutei/mikro-orm";
+import { User } from "./entities/User.js";
+import { userMapping } from "./mappings/userMapping.js";
+
+const hikoutei = await initializeMappedTypedSheetsOrm({
+  dbName: "./hikoutei.sqlite",
+  entities: [User],
+  mappings: [userMapping],
+  writer: { writerId: "users-service" },
+});
+
+const em = hikoutei.em.fork();
+const user = em.create(User, { id: "u1", name: "Ada" });
+em.persist(user);
+await em.flush();
+
+user.name = "Ada Lovelace";
+await em.flush();
+```
+
+`flush()`는 로컬 애플리케이션 상태를 변경하고 설정된 Sheet 뷰에 반영할 작업을
+예약합니다. 원격 전달은 비동기이므로 [설정 가이드](docs/quick-start.md)에 따라
+sync worker를 실행하고 Gateway를 프로비저닝해야 합니다.
+
+## Hikoutei를 사용하기 좋은 경우
+
+- 스프레드시트가 제품 업무 흐름의 일부인 MVP와 프로토타입.
+- 내부 도구와 저트래픽 관리 애플리케이션.
+- 타입이 지정된 애플리케이션 데이터를 유지하면서 사람이 Sheets를 쉽게
+  확인해야 하는 팀.
+- 로컬 SQLite를 사용할 수 있고 Sheets의 비동기 업데이트를 허용할 수 있는
+  서비스.
+
+## 다른 도구를 선택해야 하는 경우
+
+다음 요구사항이 있다면 일반적인 데이터베이스와 직접적인 Google API 사용을
+검토하세요.
+
+- 여러 행 또는 여러 서비스에 걸친 강한 트랜잭션.
+- 높은 쓰기 처리량 또는 많은 동시 작성자.
+- 복잡한 쿼리, 조인, 리포팅 작업.
+- 멀티 서버 또는 멀티 리전 조정.
+- Google Sheets에서 즉시 쓰기 후 읽기 일관성이 필요한 경우.
+- 애플리케이션의 기본 데이터베이스로 Google Sheets를 사용해야 하는 경우.
+
+## Google Sheets 설정
+
+1. 서버 애플리케이션에서 엔티티와 Sheet의 매핑을 정의합니다.
+2. [`apps-script/gateway/Code.gs`](apps-script/gateway/Code.gs)를 Google Apps
+   Script Web App으로 배포합니다.
+3. 서버에서 등록된 탭과 범위를 프로비저닝합니다.
+4. 대기 중인 변경 내용을 전달하는 sync worker를 실행합니다.
+
+Gateway 시크릿은 서버에만 보관하세요. 브라우저 코드에 넣거나 Git에 커밋하지
+마세요.
+
+## 문서
+
+- [빠른 시작](docs/quick-start.md) — 설치, 매핑, Gateway 설정.
+- [아키텍처](docs/architecture.md) — 로컬 저장소와 Sheet 화면의 관계.
+- [쓰기 및 동기화 흐름](docs/write-and-synchronization-flow.md) — 비동기 전달과
+  복구 동작.
+- [개발 가이드](docs/development.md) — 로컬 개발 및 테스트 명령.
+- [벤치마크 기록](docs/sync-bulk-write-benchmark.md) — 날짜별 측정 결과와
+  한계.
+
+## 제한사항
+
+- Google Sheets에는 quota, 지연 시간, Apps Script 실행 시간 제한이 있습니다.
+- Sheet 업데이트는 비동기이므로 애플리케이션은 로컬 상태를 읽어야 합니다.
+- SQLite는 서비스에 로컬이며 분산 조정 계층이 아닙니다.
+- 스키마 변경, 수동 편집, 충돌하는 변경에 대한 운영 정책은 애플리케이션이
+  별도로 정해야 합니다.
+
+## 로드맵
+
+- Google Sheets에서 의도적인 사용자 편집을 수집하는 기능 완성.
+- update/delete 충돌 처리와 표시 개선.
+- 레지스트리 및 Apps Script 배포를 위한 설정 도구 추가.
+- 공개 패키지 릴리스 안정화.
+
+현재 작업은 [open issues](https://github.com/ManddarinShop/Hikoutei/issues)
+에서 확인할 수 있습니다.
+
+## 라이선스
+
+Hikoutei는 [MIT License](LICENSE)로 배포됩니다.

package/README.md

@@ -0,0 +1,143 @@
+[한국어](README.ko.md) | [日本語](README.ja.md)
+
+<div align="center">
+
+# Hikoutei
+
+**Typed repository and safe write layer for Google Sheets-backed MVPs.**
+
+<a href="https://www.npmjs.com/package/hikoutei">npm package</a> ·
+<a href="https://github.com/ManddarinShop/Hikoutei/issues">Issues</a> ·
+<a href="apps-script/gateway/Code.gs">Apps Script gateway</a>
+
+[![npm version](https://img.shields.io/npm/v/hikoutei?style=flat-square)](https://www.npmjs.com/package/hikoutei)
+[![license](https://img.shields.io/npm/l/hikoutei?style=flat-square)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+</div>
+
+Hikoutei helps TypeScript and Node.js applications use Google Sheets as a
+human-friendly part of an MVP or internal workflow. Your application works
+with typed entities and local SQLite; changes can be delivered to Google
+Sheets asynchronously through the included Apps Script gateway.
+
+Hikoutei is intentionally focused. It is not a general-purpose database
+replacement, a Prisma/JPA clone, or a general Google Sheets API wrapper.
+
+## Why Hikoutei?
+
+- Entity-oriented lifecycle: create, find, mutate, persist, remove, and flush.
+- Typed field mappings with runtime validation for Sheet data.
+- Local SQLite reads for application workflows that should not wait on a remote
+  spreadsheet request.
+- Asynchronous Google Sheets views for human review and lightweight
+  collaboration.
+- Protection against common spreadsheet problems such as unexpected schema
+  changes and accidentally overwriting newer changes.
+
+## Installation
+
+The project and npm package are both called `hikoutei`.
+
+```sh
+npm install hikoutei @mikro-orm/core @mikro-orm/sql
+```
+
+The MikroORM packages are optional peer dependencies of the root package, but
+are required when using Hikoutei's built-in SQLite adapter.
+
+## Quick start
+
+After defining an entity mapping, use a request-local manager to work with
+entities. A complete mapping and gateway setup are shown in the
+[Quick start guide](docs/quick-start.md).
+
+```ts
+import { initializeMappedTypedSheetsOrm } from "hikoutei/mikro-orm";
+import { User } from "./entities/User.js";
+import { userMapping } from "./mappings/userMapping.js";
+
+const hikoutei = await initializeMappedTypedSheetsOrm({
+  dbName: "./hikoutei.sqlite",
+  entities: [User],
+  mappings: [userMapping],
+  writer: { writerId: "users-service" },
+});
+
+const em = hikoutei.em.fork();
+const user = em.create(User, { id: "u1", name: "Ada" });
+em.persist(user);
+await em.flush();
+
+user.name = "Ada Lovelace";
+await em.flush();
+```
+
+`flush()` updates the local application state and schedules the configured
+Sheet view. Remote delivery is asynchronous, so start the sync worker
+and provision the gateway as described in the [setup guide](docs/quick-start.md).
+
+## 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.
+
+## Google Sheets setup
+
+1. Define the entity-to-Sheet mapping in your server application.
+2. Deploy [`apps-script/gateway/Code.gs`](apps-script/gateway/Code.gs) as a
+   Google Apps Script Web App.
+3. Provision the registered tabs and ranges from the server.
+4. Run the sync worker that delivers pending changes.
+
+Keep the gateway secret on the server. Do not put it in browser code or commit
+it to Git.
+
+## Documentation
+
+- [Quick start](docs/quick-start.md) — installation, mapping, and gateway setup.
+- [Architecture](docs/architecture.md) — how the local store and Sheet views
+  fit together.
+- [Write and synchronization flow](docs/write-and-synchronization-flow.md) —
+  asynchronous delivery and recovery behavior.
+- [Development](docs/development.md) — local development and test commands.
+- [Benchmark notes](docs/sync-bulk-write-benchmark.md) — dated measurements
+  and their limitations.
+
+## Limitations
+
+- Google Sheets has quota, latency, and Apps Script execution limits.
+- Sheet updates are asynchronous; the application should read its local state.
+- SQLite is local to the service and is not a distributed coordination layer.
+- Schema changes, manual edits, and conflicting updates still need an
+  operational policy from the application.
+
+## Roadmap
+
+- Complete ingestion of intentional user edits from Google Sheets.
+- Improve update/delete conflict handling and presentation.
+- Add setup tooling for registry and Apps Script deployment.
+- Stabilize the public package release.
+
+See the [open issues](https://github.com/ManddarinShop/Hikoutei/issues)
+for current work.
+
+## License
+
+Hikoutei is released under the [MIT License](LICENSE).