@gasboost/replica 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gasboost
+
+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.md

@@ -0,0 +1,464 @@
+# @gasboost/replica
+
+Dexie と Zod を利用した、ブラウザ向けの型安全な IndexedDB レプリカです。
+
+`@gasboost/replica` は、Zod Schema で定義された Record を IndexedDB 上に保存し、ローカルレプリカとして扱うためのパッケージです。
+
+Query 処理は `@gasboost/query` と連携して行うため、Filter、Sort、Pagination、JOIN、Nested JOIN のロジックを Replica 側で重複実装しません。
+
+```text
+Remote Data
+   ↓
+Full Sync
+   ↓
+@gasboost/replica
+   ↓
+IndexedDB / Dexie
+   ↑
+Loader
+   ↑
+@gasboost/query
+```
+
+---
+
+## Features
+
+- Dexie を利用した IndexedDB ストレージ
+- Zod Schema からの型推論
+- 型安全な Table 名
+- 型安全な Primary Key
+- `put`
+- `bulkPut`
+- `delete`
+- `toArray`
+- Full Sync
+- Dexie Transaction による同期
+- `@gasboost/query` との統合
+- JOIN
+- Nested JOIN
+- Google Apps Script ランタイム非依存
+- SheetORM ランタイム非依存
+
+---
+
+# Installation
+
+```bash
+pnpm add @gasboost/replica @gasboost/query dexie zod
+```
+
+npm の場合:
+
+```bash
+npm install @gasboost/replica @gasboost/query dexie zod
+```
+
+---
+
+# Table Definition
+
+Replica では以下を使って Table を定義します。
+
+- Table 名
+- Zod Schema
+- Primary Key
+
+```ts
+import { z } from "zod";
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  active: z.boolean(),
+});
+
+const ReservationSchema = z.object({
+  id: z.string(),
+  userId: z.string(),
+});
+
+const tables = [
+  {
+    name: "users",
+    schema: UserSchema,
+    primaryKey: "id",
+  },
+  {
+    name: "reservations",
+    schema: ReservationSchema,
+    primaryKey: "id",
+  },
+] as const;
+```
+
+`primaryKey` には、対応する Zod Schema に存在する Column のみ指定できます。
+
+---
+
+# Replica の作成
+
+```ts
+import { createReplica } from "@gasboost/replica";
+
+const replica = createReplica({
+  name: "example-app",
+  tables,
+});
+```
+
+`name` は IndexedDB の Database 名として利用されます。
+
+各 Table は、定義された `primaryKey` を使って Dexie に登録されます。
+
+例えば、
+
+```ts
+{
+  name: "users",
+  primaryKey: "id",
+}
+```
+
+は概念的に次の Dexie Schema として登録されます。
+
+```text
+users: "id"
+```
+
+---
+
+# Table Access
+
+`table()` で Replica 内の Table を参照します。
+
+```ts
+const users = replica.table("users");
+```
+
+Table 名は Table Definition から型推論されます。
+
+```ts
+replica.table("users"); // OK
+replica.table("reservations"); // OK
+```
+
+定義されていない Table 名は TypeScript 上で拒否されます。
+
+---
+
+# Put
+
+Record を追加または更新します。
+
+```ts
+await replica.table("users").put({
+  id: "u1",
+  name: "Alice",
+  active: true,
+});
+```
+
+Record 型は、選択した Table の Zod Schema から推論されます。
+
+---
+
+# Bulk Put
+
+複数 Record をまとめて追加または更新します。
+
+```ts
+await replica.table("users").bulkPut([
+  {
+    id: "u1",
+    name: "Alice",
+    active: true,
+  },
+  {
+    id: "u2",
+    name: "Bob",
+    active: false,
+  },
+]);
+```
+
+---
+
+# Delete
+
+Primary Key を指定して Record を削除します。
+
+```ts
+await replica.table("users").delete("u1");
+```
+
+Primary Key の型は、Table Definition の `primaryKey` Column から推論されます。
+
+---
+
+# To Array
+
+Table 内の Record をすべて取得します。
+
+```ts
+const users = await replica.table("users").toArray();
+```
+
+戻り値の型は、対象 Table の Zod Schema から推論されます。
+
+---
+
+# Full Sync
+
+リモート側から取得した完全な Table データを、ローカル Replica へ同期できます。
+
+```ts
+await replica.sync("users", remoteUsers);
+```
+
+同期時には、
+
+- remote に存在する Record を local に反映
+- remote に存在しない Record を local から削除
+- 同期処理全体を Dexie Transaction 内で実行
+
+します。
+
+例えば、local に以下の Record があるとします。
+
+```ts
+await replica.table("users").bulkPut([
+  {
+    id: "u1",
+    name: "Old Alice",
+    active: true,
+  },
+  {
+    id: "u2",
+    name: "Deleted User",
+    active: false,
+  },
+]);
+```
+
+remote の完全データが以下だった場合、
+
+```ts
+await replica.sync("users", [
+  {
+    id: "u1",
+    name: "Alice",
+    active: true,
+  },
+]);
+```
+
+同期後の local は次の状態になります。
+
+```ts
+[
+  {
+    id: "u1",
+    name: "Alice",
+    active: true,
+  },
+];
+```
+
+remote に存在しない `u2` は local から削除されます。
+
+空配列を同期すると Table は空になります。
+
+```ts
+await replica.sync("users", []);
+```
+
+---
+
+# Query Integration
+
+`@gasboost/replica` は `@gasboost/query` と直接連携できます。
+
+```ts
+import { Query } from "@gasboost/query";
+
+const query = new Query<typeof tables, "users">({
+  tableName: "users",
+})
+  .and("active", "=", [true])
+  .orderBy("name", "asc");
+```
+
+Replica に対して Query を実行します。
+
+```ts
+const users = await replica.find(query);
+```
+
+Replica 自身は Filter や Sort のロジックを持ちません。
+
+内部では IndexedDB から Record を取得し、`Query.resolve()` に渡します。
+
+```text
+replica.find(query)
+      ↓
+query.resolve(loader)
+      ↓
+replica.table(name).toArray()
+```
+
+これにより、異なる Storage Adapter 間で Query semantics を共有できます。
+
+---
+
+# JOIN
+
+JOIN の評価は `@gasboost/query` が担当します。
+
+```ts
+const query = new Query<typeof tables, "users">({
+  tableName: "users",
+}).join("id", "reservations", "userId");
+```
+
+```ts
+const users = await replica.find(query);
+```
+
+結果:
+
+```ts
+[
+  {
+    id: "u1",
+    name: "Alice",
+    active: true,
+    reservations: [
+      {
+        id: "r1",
+        userId: "u1",
+      },
+    ],
+  },
+];
+```
+
+Replica 側に JOIN Engine は持ちません。
+
+Replica は `@gasboost/query` に Record を提供するだけです。
+
+---
+
+# Nested JOIN
+
+Nested JOIN も `@gasboost/query` によって解決されます。
+
+```ts
+const reservations = new Query<typeof tables, "reservations">({
+  tableName: "reservations",
+}).join("staffId", "staffs", "id");
+
+const users = new Query<typeof tables, "users">({
+  tableName: "users",
+}).join("id", "reservations", "userId", reservations);
+```
+
+```ts
+const result = await replica.find(users);
+```
+
+Nested JOIN は `Query.resolve()` によって bottom-up に解決されます。
+
+```text
+staffs
+  ↓
+reservations
+  ↓
+users
+```
+
+---
+
+# Architecture
+
+`@gasboost/replica` は Storage の責務だけを持ちます。
+
+```text
+@gasboost/replica
+  - IndexedDB 初期化
+  - Dexie Table
+  - put
+  - bulkPut
+  - delete
+  - toArray
+  - Full Sync
+  - Query Loader
+
+@gasboost/query
+  - Filter
+  - Sort
+  - Offset
+  - Limit
+  - JOIN
+  - Nested JOIN
+  - Query Resolution
+```
+
+この責務分離により、ローカル Storage とリモート Storage の間で Query 処理を重複実装せずに済みます。
+
+---
+
+# Shared Schemas
+
+Server と Browser で同じ Table Definition を共有できます。
+
+```ts
+export const tables = [
+  {
+    name: "users",
+    schema: UserSchema,
+    primaryKey: "id",
+  },
+] as const;
+```
+
+```text
+Server / GAS
+     ↓
+ shared tables
+     ↑
+Browser / Replica
+```
+
+Shared Schema を置く Module には、以下のような Runtime 固有依存を含めないことを推奨します。
+
+- `SpreadsheetApp`
+- `CacheService`
+- GAS Handler
+- Browser 固有の Application Code
+
+これにより、Server Runtime が Frontend Bundle に混入することを防ぎます。
+
+---
+
+# 対象外
+
+`@gasboost/replica` core では以下を扱いません。
+
+- Firebase Realtime Database 同期
+- 端末間リアルタイム同期
+- Firebase Authentication
+- Row Level Security
+- Offline Mutation Queue
+- Conflict Resolution
+- Incremental Sync
+- Secondary Index を利用した Query 最適化
+- React Hooks
+
+これらは Replica core の上に別レイヤーとして追加できます。
+
+---
+
+# License
+
+MIT

package/dist/Replica.d.ts

@@ -0,0 +1,16 @@
+import type { Query } from "@gasboost/query";
+import { ReplicaTable } from "./ReplicaTable";
+import { type ReplicaRecord, type ReplicaTableByName, type ReplicaTableDefinition } from "./ReplicaTableDefinition";
+type PrimaryKey<T extends readonly ReplicaTableDefinition[], N extends T[number]["name"]> = ReplicaRecord<T, N>[ReplicaTableByName<T, N>["primaryKey"] & keyof ReplicaRecord<T, N>];
+export declare class Replica<T extends readonly ReplicaTableDefinition[]> {
+    private readonly db;
+    private readonly tables;
+    constructor({ name, tables }: {
+        name: string;
+        tables: T;
+    });
+    table<N extends T[number]["name"]>(name: N): ReplicaTable<ReplicaRecord<T, N>, PrimaryKey<T, N>>;
+    sync<N extends T[number]["name"]>(name: N, records: ReplicaRecord<T, N>[]): Promise<void>;
+    find<N extends T[number]["name"]>(query: Query<T, N>): Promise<Record<string, unknown>[]>;
+}
+export {};

package/dist/Replica.js

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Replica = void 0;
+const dexie_1 = __importDefault(require("dexie"));
+const ReplicaTable_1 = require("./ReplicaTable");
+class Replica {
+    db;
+    tables;
+    constructor({ name, tables }) {
+        this.tables = tables;
+        this.db = new dexie_1.default(name);
+        const schema = Object.fromEntries(tables.map((table) => [table.name, table.primaryKey]));
+        this.db.version(1).stores(schema);
+    }
+    table(name) {
+        return new ReplicaTable_1.ReplicaTable(this.db.table(name));
+    }
+    async sync(name, records) {
+        const table = this.db.table(name);
+        await this.db.transaction("rw", table, async () => {
+            await table.clear();
+            if (records.length > 0) {
+                await table.bulkPut(records);
+            }
+        });
+    }
+    async find(query) {
+        return query.resolve(async (name) => {
+            return this.db.table(name).toArray();
+        });
+    }
+}
+exports.Replica = Replica;

package/dist/ReplicaTable.d.ts

@@ -0,0 +1,9 @@
+import type { Table } from "dexie";
+export declare class ReplicaTable<RecordType, KeyType> {
+    private readonly table;
+    constructor(table: Table<RecordType, KeyType>);
+    put(record: RecordType): Promise<void>;
+    bulkPut(records: RecordType[]): Promise<void>;
+    delete(key: KeyType): Promise<void>;
+    toArray(): Promise<RecordType[]>;
+}

package/dist/ReplicaTable.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReplicaTable = void 0;
+class ReplicaTable {
+    table;
+    constructor(table) {
+        this.table = table;
+    }
+    async put(record) {
+        await this.table.put(record);
+    }
+    async bulkPut(records) {
+        await this.table.bulkPut(records);
+    }
+    async delete(key) {
+        await this.table.delete(key);
+    }
+    async toArray() {
+        return this.table.toArray();
+    }
+}
+exports.ReplicaTable = ReplicaTable;

package/dist/ReplicaTableDefinition.d.ts

@@ -0,0 +1,9 @@
+import type { TableDefinition } from "@gasboost/query";
+import type { z } from "zod";
+export type ReplicaTableDefinition<N extends string = string, S extends z.ZodObject<any> = z.ZodObject<any>, PK extends Extract<keyof z.infer<S>, string> = Extract<keyof z.infer<S>, string>> = TableDefinition<N, S> & {
+    readonly primaryKey: PK;
+};
+export type ReplicaTableByName<T extends readonly ReplicaTableDefinition[], N extends T[number]["name"]> = Extract<T[number], {
+    name: N;
+}>;
+export type ReplicaRecord<T extends readonly ReplicaTableDefinition[], N extends T[number]["name"]> = z.infer<ReplicaTableByName<T, N>["schema"]>;

package/dist/ReplicaTableDefinition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/createReplica.d.ts

@@ -0,0 +1,6 @@
+import { Replica } from "./Replica";
+import type { ReplicaTableDefinition } from "./ReplicaTableDefinition";
+export declare function createReplica<T extends readonly ReplicaTableDefinition[]>({ name, tables, }: {
+    name: string;
+    tables: T;
+}): Replica<T>;

package/dist/createReplica.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReplica = createReplica;
+const Replica_1 = require("./Replica");
+function createReplica({ name, tables, }) {
+    return new Replica_1.Replica({
+        name,
+        tables,
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./createReplica";

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./createReplica"), exports);

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@gasboost/replica",
+  "version": "0.1.0",
+  "description": "Type-safe IndexedDB replica powered by Dexie and Zod",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gasboost/db.git",
+    "directory": "packages/replica"
+  },
+  "license": "MIT",
+  "author": "tiger-oshima",
+  "keywords": [
+    "indexeddb",
+    "dexie",
+    "replica",
+    "offline",
+    "zod",
+    "typescript",
+    "type-safe"
+  ],
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "dexie": "^4.4.6",
+    "zod": "^4.5.4",
+    "@gasboost/query": "0.1.2"
+  },
+  "devDependencies": {
+    "fake-indexeddb": "^6.2.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "pack:check": "pnpm pack"
+  }
+}