@firtoz/drizzle-durable-sqlite 0.2.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @firtoz/drizzle-durable-sqlite
 
+## 1.0.0
+
+### Major Changes
+
+- [#64](https://github.com/firtoz/fullstack-toolkit/pull/64) [`556555a`](https://github.com/firtoz/fullstack-toolkit/commit/556555a2e09030a8658be8c07b5881e72be64b2f) Thanks [@firtoz](https://github.com/firtoz)! - **Breaking:** Shared TanStack collection row type is `DrizzleSqliteTableCollection` from `@firtoz/drizzle-utils` — remove `DrizzleSqliteCollection` / `DurableSqliteCollection` type exports from the wasm and durable packages and import from `@firtoz/drizzle-utils` instead. Align bridge/session row types with `PartialSyncRowShape`.
+
+  **`@firtoz/drizzle-durable-sqlite`:** `SyncableDurableObject` / `QueryableDurableObject`, Drizzle partial sync store (`createDrizzlePartialSyncStore`) with scoped `changesSince`, `getRow`, visibility and `rangeReconcile` hooks, `PartialSyncMutationHandler`, `applyDurableMutationIntents`, queued WS message handling, optional `seedInBackground`, and integration with `PartialSyncServerBridge` / `SyncServerBridge` as documented in the package.
+
+  **`@firtoz/drizzle-sqlite-wasm`:** `createSyncedSqliteCollection`, optional `workerOpenOptions` for worker `Start` / provider hooks, table sync upsert on `id` for replayed inserts, and receive-sync persist key alignment with generic sync.
+
+### Patch Changes
+
+- Updated dependencies [[`afb1873`](https://github.com/firtoz/fullstack-toolkit/commit/afb187331bebb1f0231f6615c5b74989191cf30d), [`556555a`](https://github.com/firtoz/fullstack-toolkit/commit/556555a2e09030a8658be8c07b5881e72be64b2f), [`556555a`](https://github.com/firtoz/fullstack-toolkit/commit/556555a2e09030a8658be8c07b5881e72be64b2f), [`556555a`](https://github.com/firtoz/fullstack-toolkit/commit/556555a2e09030a8658be8c07b5881e72be64b2f), [`556555a`](https://github.com/firtoz/fullstack-toolkit/commit/556555a2e09030a8658be8c07b5881e72be64b2f)]:
+  - @firtoz/collection-sync@1.0.0
+  - @firtoz/db-helpers@2.1.0
+  - @firtoz/drizzle-utils@1.2.0
+  - @firtoz/websocket-do@7.1.0
+
+## 0.2.1
+
+### Patch Changes
+
+- [`8b839f2`](https://github.com/firtoz/fullstack-toolkit/commit/8b839f2227f50409af649aab87178e039aad55dc) Thanks [@firtoz](https://github.com/firtoz)! - Export collection helper types for Drizzle-backed TanStack DB collections so users can declare collection variables with preserved select and insert inference from table schemas.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -15,9 +15,12 @@ bun add -d drizzle-kit @cloudflare/workers-types
 bun add hono zod @hono/zod-validator @firtoz/hono-fetcher
 ```
 
-## Drizzle Kit
+## Drizzle Kit (Required)
 
-Use the durable-sqlite driver so generated migrations match DO storage:
+Drizzle Kit migrations are mandatory for Durable Object SQLite setups in this toolkit.
+Do not skip migrations and do not rely on ad-hoc runtime table creation.
+
+Use this exact durable-sqlite driver config so generated migrations match DO storage:
 
 ```typescript
 import { defineConfig } from "drizzle-kit";
@@ -30,6 +33,15 @@ export default defineConfig({
 });
 ```
 
+Then generate migrations:
+
+```bash
+bun run db:generate
+```
+
+`db:generate` should run `drizzle-kit generate` and write SQL files under `./drizzle`.
+Keep `drizzle/migrations.js` and `drizzle/migrations.d.ts` in sync with the generated SQL files.
+
 ## Wrangler
 
 - Import SQL as text for the migrator ([Drizzle DO docs](https://orm.drizzle.team/docs/connect-cloudflare-do)).
@@ -44,9 +56,9 @@ export default defineConfig({
 }
 ```
 
-## Durable Object initialization
+## Durable Object initialization (migrate first)
 
-**Recommended for generic DOs:** run migrations inside `ctx.blockConcurrencyWhile` so the schema is ready before `fetch` or alarms. Example:
+Run migrations in `ctx.blockConcurrencyWhile` before handling requests so schema is ready before `fetch` or alarms. Example:
 
 ```typescript
 import { DurableObject } from "cloudflare:workers";
@@ -77,7 +89,9 @@ Use `durableSqliteCollectionOptions` with tables built via `syncableTable` from
 
 `tableName` must be the **property name** on your Drizzle schema object (e.g. `export const schema = { todosTable }` → `tableName: "todosTable"`), not the SQLite table name string.
 
-If something else must finish before sync runs (e.g. a migration promise), pass `readyPromise`. When omitted, the collection treats storage as ready immediately (same as `Promise.resolve()`).
+If something else must finish before sync runs, pass `readyPromise`. This is not a replacement for Drizzle migrations; run `migrate(db, migrations)` first in your DO initialization.
+
+For explicit collection type annotations, use `DrizzleSqliteTableCollection<TTable>` from `@firtoz/drizzle-utils` (same shape as WASM SQLite collections).
 
 Example `schema.ts`:
 
@@ -107,13 +121,14 @@ import { createCollection } from "@tanstack/db";
 import type { DrizzleSqliteDODatabase } from "drizzle-orm/durable-sqlite";
 import { drizzle } from "drizzle-orm/durable-sqlite";
 import { migrate } from "drizzle-orm/durable-sqlite/migrator";
+import { durableSqliteCollectionOptions } from "@firtoz/drizzle-durable-sqlite";
+import type { DrizzleSqliteTableCollection } from "@firtoz/drizzle-utils";
 import { Hono } from "hono";
 import { z } from "zod";
-import { durableSqliteCollectionOptions } from "@firtoz/drizzle-durable-sqlite";
 import migrations from "../drizzle/migrations.js";
 import * as schema from "./schema";
 
-type TodosCollection = ReturnType<typeof createCollection>;
+type TodosCollection = DrizzleSqliteTableCollection<typeof schema.todosTable>;
 
 export class TodosDurableObject extends DurableObject<Env> {
 	private db!: DrizzleSqliteDODatabase<typeof schema>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-durable-sqlite",
-	"version": "0.2.0",
+	"version": "1.0.0",
 	"description": "TanStack DB collections backed by Drizzle on Cloudflare Durable Object SQLite",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -30,7 +30,7 @@
 		"CHANGELOG.md"
 	],
 	"scripts": {
-		"typecheck": "tsc --noEmit -p ./tsconfig.json",
+		"typecheck": "tsgo --noEmit -p ./tsconfig.json",
 		"lint": "biome check --write src",
 		"lint:ci": "biome ci src",
 		"format": "biome format src --write"
@@ -61,21 +61,25 @@
 		"access": "public"
 	},
 	"peerDependencies": {
-		"@cloudflare/workers-types": "^4.20260317.1",
-		"@tanstack/db": "^0.5.33",
-		"drizzle-orm": "^0.45.1",
+		"@cloudflare/workers-types": "^4.20260329.1",
+		"@tanstack/db": "^0.6.1",
+		"drizzle-orm": "^0.45.2",
 		"drizzle-valibot": ">=0.4.0",
 		"valibot": ">=1.3.1"
 	},
 	"dependencies": {
-		"@firtoz/db-helpers": "^2.0.0",
-		"@firtoz/drizzle-utils": "^1.1.0"
+		"@firtoz/collection-sync": "^1.0.0",
+		"@firtoz/db-helpers": "^2.1.0",
+		"@firtoz/drizzle-utils": "^1.2.0",
+		"@firtoz/maybe-error": "^1.5.2",
+		"@firtoz/websocket-do": "^7.1.0"
 	},
 	"devDependencies": {
-		"@cloudflare/workers-types": "^4.20260317.1",
-		"@tanstack/db": "^0.5.33",
-		"drizzle-orm": "^0.45.1",
+		"@cloudflare/workers-types": "^4.20260329.1",
+		"@tanstack/db": "^0.6.1",
+		"drizzle-orm": "^0.45.2",
 		"drizzle-valibot": "^0.4.2",
+		"hono": "^4.12.9",
 		"typescript": "^6.0.2",
 		"valibot": "^1.3.1"
 	}

package/src/drizzle-mutation-store.ts

@@ -0,0 +1,105 @@
+import type { SyncServerBridgeStore } from "@firtoz/collection-sync";
+import type { SyncMessage } from "@firtoz/db-helpers";
+import { exhaustiveGuard } from "@firtoz/maybe-error";
+import { eq, getTableColumns } from "drizzle-orm";
+import type { SQLiteTable } from "drizzle-orm/sqlite-core";
+import type { DrizzleChangelogHelper } from "./drizzle-partial-sync-changelog";
+import type { PartialSyncSqliteDatabase } from "./partial-sync-sqlite-db";
+
+export type CreateDrizzleMutationStoreOptions<
+	TSchema extends Record<string, unknown>,
+	TRow extends { id: string | number },
+> = {
+	db: PartialSyncSqliteDatabase<TSchema>;
+	table: SQLiteTable;
+	changelogHelper: DrizzleChangelogHelper<TSchema>;
+	/** Columns to copy from `update` message.value into SET (excluding id). */
+	updateColumns: readonly (keyof TRow & string)[];
+};
+
+export function createDrizzleMutationStore<
+	TSchema extends Record<string, unknown>,
+	TRow extends { id: string | number },
+>(
+	options: CreateDrizzleMutationStoreOptions<TSchema, TRow>,
+): SyncServerBridgeStore<TRow> {
+	const { db, table, changelogHelper, updateColumns } = options;
+	const tableColumns = getTableColumns(table);
+	const idCol = tableColumns.id;
+	if (idCol === undefined) {
+		throw new Error("Mutation table must have an id column");
+	}
+
+	return {
+		applySyncMessages: async (messages: SyncMessage<TRow>[]) => {
+			for (const message of messages) {
+				switch (message.type) {
+					case "insert":
+						await db
+							.insert(table)
+							.values(message.value as Record<string, unknown>);
+						await changelogHelper.append(
+							"insert",
+							String(message.value.id),
+							message.value,
+						);
+						break;
+					case "update": {
+						const setPayload: Record<string, unknown> = {};
+						const v = message.value as Record<string, unknown>;
+						for (const col of updateColumns) {
+							setPayload[col] = v[col];
+						}
+						await db
+							.update(table)
+							.set(setPayload as never)
+							.where(eq(idCol, message.value.id as never));
+						await changelogHelper.append("update", String(message.value.id), {
+							value: message.value,
+							previousValue: message.previousValue,
+						});
+						break;
+					}
+					case "delete": {
+						const existing = await db
+							.select()
+							.from(table)
+							.where(eq(idCol, message.key as never))
+							.limit(1);
+						const prev = existing[0];
+						await db.delete(table).where(eq(idCol, message.key as never));
+						await changelogHelper.append(
+							"delete",
+							String(message.key),
+							prev ?? null,
+						);
+						break;
+					}
+					case "truncate":
+						await changelogHelper.deleteAll();
+						await db.delete(table);
+						break;
+					default:
+						exhaustiveGuard(message);
+				}
+			}
+		},
+
+		getSnapshotMessages: async () => {
+			const rows = await db.select().from(table);
+			return rows.map((row) => ({
+				type: "insert" as const,
+				value: row as TRow,
+			}));
+		},
+
+		getRow: async (key: string | number) => {
+			const rows = await db
+				.select()
+				.from(table)
+				.where(eq(idCol, key as never))
+				.limit(1);
+			return rows[0] as TRow | undefined;
+		},
+	};
+}

package/src/drizzle-partial-sync-changelog.ts

@@ -0,0 +1,65 @@
+import { getTableColumns, gt } from "drizzle-orm";
+import type { SQLiteTable } from "drizzle-orm/sqlite-core";
+import type { PartialSyncSqliteDatabase } from "./partial-sync-sqlite-db";
+
+export type ChangelogOperation = "insert" | "update" | "delete";
+
+export type DrizzleChangelogHelperOptions<
+	TSchema extends Record<string, unknown>,
+> = {
+	db: PartialSyncSqliteDatabase<TSchema>;
+	changelogTable: SQLiteTable;
+	serializeJson: (value: unknown) => string;
+};
+
+export function createDrizzleChangelogHelper<
+	TSchema extends Record<string, unknown>,
+>(options: DrizzleChangelogHelperOptions<TSchema>) {
+	const cols = getTableColumns(options.changelogTable);
+	const rowIdCol = cols.rowId;
+	const operationCol = cols.operation;
+	const versionCol = cols.version;
+	if (
+		rowIdCol === undefined ||
+		operationCol === undefined ||
+		versionCol === undefined
+	) {
+		throw new Error(
+			"changelogTable must have rowId, operation, and version columns",
+		);
+	}
+
+	return {
+		append: async (
+			operation: ChangelogOperation,
+			rowId: string,
+			payload: unknown,
+		): Promise<void> => {
+			const version = new Date();
+			await options.db.insert(options.changelogTable).values({
+				rowId,
+				operation,
+				version,
+				payloadJson:
+					payload === null || payload === undefined
+						? null
+						: options.serializeJson(payload),
+			} as Record<string, unknown>);
+		},
+
+		selectAfterVersion: async (sinceVersionMs: number) => {
+			const rows = await options.db
+				.select()
+				.from(options.changelogTable)
+				.where(gt(versionCol, new Date(sinceVersionMs)));
+			return rows;
+		},
+
+		deleteAll: async (): Promise<void> => {
+			await options.db.delete(options.changelogTable);
+		},
+	};
+}
+
+export type DrizzleChangelogHelper<TSchema extends Record<string, unknown>> =
+	ReturnType<typeof createDrizzleChangelogHelper<TSchema>>;