@firtoz/drizzle-durable-sqlite 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# @firtoz/drizzle-durable-sqlite
+
+## 0.2.0
+
+### Minor Changes
+
+- [`b714ebb`](https://github.com/firtoz/fullstack-toolkit/commit/b714ebbb62ec0e3c3aa56c4105e7499fac11d1e5) Thanks [@firtoz](https://github.com/firtoz)! - Extract shared SQLite TanStack sync backend (`createSqliteTableSyncBackend`, IR→Drizzle helpers, `SQLOperation` types) into `@firtoz/drizzle-utils`. Add `@firtoz/drizzle-durable-sqlite` for Durable Object SQLite collections (`durableSqliteCollectionOptions`). Refactor `@firtoz/drizzle-sqlite-wasm` to use the shared backend with `driverMode: "async"`. `durableSqliteCollectionOptions` accepts optional `readyPromise` (defaults to immediate readiness). README documents the class-field Hono pattern, `app.fetch(request, env)` for bindings, optional `on-demand` + `preload` vs eager + `onFirstReady`, and `honoDoFetcherWithName` without a separate exported app type. Restore JSDoc on `DrizzleSqliteCollectionConfig` (`debug`, `checkpoint`, `interceptor`) for editor tooltips. Align `createStandaloneCollection` generics with `InsertToSelectSchema` from `@firtoz/drizzle-utils`.
+
+### Patch Changes
+
+- Updated dependencies [[`b714ebb`](https://github.com/firtoz/fullstack-toolkit/commit/b714ebbb62ec0e3c3aa56c4105e7499fac11d1e5)]:
+  - @firtoz/drizzle-utils@1.1.0
+
+## 0.1.0
+
+Initial release: TanStack DB collection options for Drizzle on Cloudflare Durable Object SQLite.

package/README.md

@@ -0,0 +1,211 @@
+# @firtoz/drizzle-durable-sqlite
+
+TanStack DB collection configuration for **Drizzle ORM** on **Cloudflare Durable Object SQLite** (`drizzle-orm/durable-sqlite`). This mirrors [`@firtoz/drizzle-sqlite-wasm`](../drizzle-sqlite-wasm) for the browser (SQLite WASM + workers), but targets Workers/DOs only—no React provider, no OPFS, no Web Workers.
+
+## Install
+
+```bash
+bun add @firtoz/drizzle-durable-sqlite @firtoz/drizzle-utils drizzle-orm @tanstack/db
+bun add -d drizzle-kit @cloudflare/workers-types
+```
+
+**Optional** (only for the [Hono + Zod example](#tanstack-db-collection-and-crud-from-a-durable-object) and a typed [`honoDoFetcher`](https://github.com/firtoz/fullstack-toolkit/tree/main/packages/hono-fetcher) client):
+
+```bash
+bun add hono zod @hono/zod-validator @firtoz/hono-fetcher
+```
+
+## Drizzle Kit
+
+Use the durable-sqlite driver so generated migrations match DO storage:
+
+```typescript
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+	schema: "./src/schema.ts",
+	out: "./drizzle",
+	dialect: "sqlite",
+	driver: "durable-sqlite",
+});
+```
+
+## Wrangler
+
+- Import SQL as text for the migrator ([Drizzle DO docs](https://orm.drizzle.team/docs/connect-cloudflare-do)).
+- Use `new_sqlite_classes` for SQLite-backed Durable Objects.
+
+```jsonc
+{
+	"rules": [
+		{ "type": "Text", "globs": ["**/*.sql"], "fallthrough": true }
+	],
+	"migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyDurableObject"] }]
+}
+```
+
+## Durable Object initialization
+
+**Recommended for generic DOs:** run migrations inside `ctx.blockConcurrencyWhile` so the schema is ready before `fetch` or alarms. Example:
+
+```typescript
+import { DurableObject } from "cloudflare:workers";
+import { drizzle } from "drizzle-orm/durable-sqlite";
+import { migrate } from "drizzle-orm/durable-sqlite/migrator";
+import migrations from "../drizzle/migrations.js";
+import * as schema from "./schema";
+
+export class MyDurableObject extends DurableObject {
+	private db!: ReturnType<typeof drizzle<typeof schema>>;
+
+	constructor(ctx: DurableObjectState, env: Env) {
+		super(ctx, env);
+		this.ctx.blockConcurrencyWhile(async () => {
+			const db = drizzle(ctx.storage, { schema });
+			migrate(db, migrations);
+			this.db = db;
+		});
+	}
+}
+```
+
+[`@firtoz/chat-agent-drizzle`](../chat-agent-drizzle) uses a different pattern: `ChatAgentBase` calls a synchronous `dbInitialize()` hook (see `DrizzleChatAgent`). Use `blockConcurrencyWhile` when you are not on that agent base class.
+
+## TanStack DB collection and CRUD from a Durable Object
+
+Use `durableSqliteCollectionOptions` with tables built via `syncableTable` from `@firtoz/drizzle-utils` (same as WASM). The DO SQLite driver is **sync**; the shared backend uses synchronous transactions and `.all()` / `.run()` for mutations (see `@firtoz/drizzle-utils` `createSqliteTableSyncBackend` with `driverMode: "sync"`).
+
+`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()`).
+
+Example `schema.ts`:
+
+```typescript
+import { syncableTable } from "@firtoz/drizzle-utils";
+import { text } from "drizzle-orm/sqlite-core";
+
+export const todosTable = syncableTable("todos", {
+	title: text("title").notNull(),
+});
+
+export const schema = { todosTable };
+```
+
+Example Durable Object: migrate in `blockConcurrencyWhile`, create the TanStack collection, then define a [Hono](https://hono.dev/) app as a **class field** (chained `.get(…)`, `.post(…)`, …) and forward `fetch` to it—the same shape as the [Durable Object snippet in `@firtoz/hono-fetcher`](../hono-fetcher/README.md).
+
+Route handlers only run when a request is handled; Workers finish your constructor’s `blockConcurrencyWhile` work **before** the first `fetch`, so `this.todos` is always assigned before any handler runs. Pass **`this.env`** into `app.fetch` so `c.env` matches `Bindings: Env` (middleware, secrets, etc.). Use [`zValidator`](https://github.com/honojs/middleware/tree/main/packages/zod-validator) so JSON bodies and `:id` params are validated; [`honoDoFetcherWithName`](../hono-fetcher/README.md) can infer request/response types from that app without a separate exported `App` type.
+
+For `syncMode: "on-demand"`, `await collection.preload()` inside `blockConcurrencyWhile` if you want rows loaded before serving. For `syncMode: "eager"`, you can wait for the first sync with `await new Promise<void>((resolve) => collection.onFirstReady(() => resolve()))` after `preload()`.
+
+A minimal vitest + DO setup lives in [`tests/drizzle-durable-sqlite-test`](https://github.com/firtoz/fullstack-toolkit/tree/main/tests/drizzle-durable-sqlite-test).
+
+```typescript
+import { DurableObject } from "cloudflare:workers";
+import { zValidator } from "@hono/zod-validator";
+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 { 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>;
+
+export class TodosDurableObject extends DurableObject<Env> {
+	private db!: DrizzleSqliteDODatabase<typeof schema>;
+	private todos!: TodosCollection;
+	app = new Hono<{ Bindings: Env }>()
+		.get("/todos", (c) => c.json({ todos: this.todos.toArray }))
+		.post(
+			"/todos",
+			zValidator("json", z.object({ title: z.string() })),
+			async (c) => {
+				const { title } = c.req.valid("json");
+				const tx = this.todos.insert([{ title }]);
+				await tx.isPersisted.promise;
+				return c.json({ ok: true as const }, 201);
+			},
+		)
+		.patch(
+			"/todos/:id",
+			zValidator("param", z.object({ id: z.string() })),
+			zValidator(
+				"json",
+				z.object({ title: z.string().optional() }),
+			),
+			async (c) => {
+				const { id } = c.req.valid("param");
+				const { title } = c.req.valid("json");
+				const tx = this.todos.update(id, (draft) => {
+					if (title !== undefined) draft.title = title;
+				});
+				await tx.isPersisted.promise;
+				return c.json(this.todos.state.get(id) ?? null);
+			},
+		)
+		.delete(
+			"/todos/:id",
+			zValidator("param", z.object({ id: z.string() })),
+			async (c) => {
+				const { id } = c.req.valid("param");
+				const tx = this.todos.delete([id]);
+				await tx.isPersisted.promise;
+				return new Response(null, { status: 204 });
+			},
+		)
+		.notFound((c) => c.text("Not found", 404));
+
+	constructor(ctx: DurableObjectState, env: Env) {
+		super(ctx, env);
+
+		this.ctx.blockConcurrencyWhile(async () => {
+			const db = drizzle(ctx.storage, { schema });
+			migrate(db, migrations);
+			this.db = db;
+
+			const todos = createCollection(
+				durableSqliteCollectionOptions({
+					drizzle: db,
+					tableName: "todosTable",
+					syncMode: "eager",
+				}),
+			);
+			this.todos = todos;
+			todos.preload(); // Preload to ensure the data's in the collection from storage.
+			await new Promise<void>((resolve) => todos.onFirstReady(() => resolve()));
+		});
+	}
+
+	fetch(request: Request) {
+		return this.app.fetch(request, this.env);
+	}
+}
+```
+
+**Typed client from your worker** (same idea as [Durable Objects in `@firtoz/hono-fetcher`](../hono-fetcher/README.md)):
+
+```typescript
+import { honoDoFetcherWithName } from "@firtoz/hono-fetcher";
+
+const api = honoDoFetcherWithName(env.TODOS, "my-list");
+
+await api.post({
+	url: "/todos",
+	body: { title: "Buy milk" },
+});
+
+const list = await api.get({ url: "/todos" });
+const data = await list.json();
+```
+
+`body` / response inference follows your `zValidator` + `c.json` shapes; use `params: { id: "…" }` on `/todos/:id` routes. If inference ever fails to pick up the DO’s `app` type, pass an explicit generic, e.g. `honoDoFetcherWithName<InstanceType<typeof TodosDurableObject>["app"]>(…)`.
+
+Adjust paths (`../drizzle/migrations.js`, `./schema`) and `Env` to match your worker. To return the created row from `POST`, read from `this.todos.state` / `toArray` after `isPersisted` and return `c.json(…)` with a shape that matches what you want the fetcher to infer.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,82 @@
+{
+	"name": "@firtoz/drizzle-durable-sqlite",
+	"version": "0.2.0",
+	"description": "TanStack DB collections backed by Drizzle on Cloudflare Durable Object SQLite",
+	"main": "./src/index.ts",
+	"module": "./src/index.ts",
+	"types": "./src/index.ts",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts",
+			"require": "./src/index.ts"
+		},
+		"./durableSqliteCollectionOptions": {
+			"types": "./src/durable-sqlite-collection.ts",
+			"import": "./src/durable-sqlite-collection.ts",
+			"require": "./src/durable-sqlite-collection.ts"
+		},
+		"./*": {
+			"types": "./src/*.ts",
+			"import": "./src/*.ts",
+			"require": "./src/*.ts"
+		}
+	},
+	"files": [
+		"src/**/*.ts",
+		"!src/**/*.test.ts",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"typecheck": "tsc --noEmit -p ./tsconfig.json",
+		"lint": "biome check --write src",
+		"lint:ci": "biome ci src",
+		"format": "biome format src --write"
+	},
+	"keywords": [
+		"typescript",
+		"cloudflare",
+		"durable-objects",
+		"sqlite",
+		"drizzle",
+		"tanstack-db"
+	],
+	"author": "Firtina Ozbalikchi <firtoz@github.com>",
+	"license": "MIT",
+	"homepage": "https://github.com/firtoz/fullstack-toolkit#readme",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/firtoz/fullstack-toolkit.git",
+		"directory": "packages/drizzle-durable-sqlite"
+	},
+	"bugs": {
+		"url": "https://github.com/firtoz/fullstack-toolkit/issues"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@cloudflare/workers-types": "^4.20260317.1",
+		"@tanstack/db": "^0.5.33",
+		"drizzle-orm": "^0.45.1",
+		"drizzle-valibot": ">=0.4.0",
+		"valibot": ">=1.3.1"
+	},
+	"dependencies": {
+		"@firtoz/db-helpers": "^2.0.0",
+		"@firtoz/drizzle-utils": "^1.1.0"
+	},
+	"devDependencies": {
+		"@cloudflare/workers-types": "^4.20260317.1",
+		"@tanstack/db": "^0.5.33",
+		"drizzle-orm": "^0.45.1",
+		"drizzle-valibot": "^0.4.2",
+		"typescript": "^6.0.2",
+		"valibot": "^1.3.1"
+	}
+}

package/src/durable-sqlite-collection.ts

@@ -0,0 +1,138 @@
+import type {
+	InferSchemaOutput,
+	SyncMode,
+	CollectionConfig,
+} from "@tanstack/db";
+import type { Table } from "drizzle-orm";
+import type { DrizzleSqliteDODatabase } from "drizzle-orm/durable-sqlite";
+import type { CollectionUtils } from "@firtoz/db-helpers";
+import type {
+	SelectSchema,
+	InsertToSelectSchema,
+	TableWithRequiredFields,
+	BaseSyncConfig,
+} from "@firtoz/drizzle-utils";
+import {
+	createSyncFunction,
+	createInsertSchemaWithIdDefault,
+	createGetKeyFunction,
+	createCollectionConfig,
+	createSqliteTableSyncBackend,
+	type SQLOperation,
+	type SQLInterceptor,
+} from "@firtoz/drizzle-utils";
+export type { SQLOperation, SQLInterceptor };
+
+/**
+ * Drizzle database type for `drizzle-orm/durable-sqlite` (Cloudflare DO SQLite).
+ */
+export type AnyDurableSqliteDatabase = DrizzleSqliteDODatabase<
+	Record<string, unknown>
+>;
+
+export type DurableDrizzleSchema<TDrizzle extends AnyDurableSqliteDatabase> =
+	TDrizzle["_"]["fullSchema"];
+
+export interface DurableSqliteCollectionConfig<
+	TDrizzle extends AnyDurableSqliteDatabase,
+	TTableName extends ValidTableNames<DurableDrizzleSchema<TDrizzle>>,
+> {
+	drizzle: TDrizzle;
+	tableName: ValidTableNames<DurableDrizzleSchema<TDrizzle>> extends never
+		? {
+				$error: "The schema needs to include at least one table that uses the syncableTable function.";
+			}
+		: TTableName;
+	/**
+	 * Await before running sync queries (e.g. migrations finishing). Omit or leave undefined to use an already-resolved promise (no extra wait).
+	 */
+	readyPromise?: Promise<void>;
+	syncMode?: SyncMode;
+	debug?: boolean;
+	interceptor?: SQLInterceptor;
+}
+
+export type ValidTableNames<TSchema extends Record<string, unknown>> = {
+	[K in keyof TSchema]: TSchema[K] extends TableWithRequiredFields ? K : never;
+}[keyof TSchema];
+
+export type DurableSqliteCollectionConfigResult<TTable extends Table> = Omit<
+	CollectionConfig<
+		InferSchemaOutput<SelectSchema<TTable>>,
+		string,
+		InsertToSelectSchema<TTable>
+	>,
+	"utils"
+> & {
+	schema: InsertToSelectSchema<TTable>;
+	utils: CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>;
+};
+
+/**
+ * TanStack DB collection configuration for a table stored in Durable Object SQLite via Drizzle.
+ *
+ * Uses `driverMode: "sync"` internally: DO SQLite runs `transactionSync`, so mutations use
+ * `.all()` / `.run()` inside a synchronous transaction callback (see `createSqliteTableSyncBackend` in `@firtoz/drizzle-utils`).
+ */
+export function durableSqliteCollectionOptions<
+	const TDrizzle extends AnyDurableSqliteDatabase,
+	const TTableName extends string &
+		ValidTableNames<DurableDrizzleSchema<TDrizzle>>,
+	TTable extends DurableDrizzleSchema<TDrizzle>[TTableName] &
+		TableWithRequiredFields,
+>(
+	config: DurableSqliteCollectionConfig<TDrizzle, TTableName>,
+): DurableSqliteCollectionConfigResult<TTable> {
+	const tableName = config.tableName as string &
+		ValidTableNames<DurableDrizzleSchema<TDrizzle>>;
+
+	const table = config.drizzle._.fullSchema[tableName] as TTable;
+
+	const backend = createSqliteTableSyncBackend({
+		drizzle: config.drizzle,
+		table,
+		tableName: config.tableName as string,
+		debug: config.debug,
+		interceptor: config.interceptor,
+		driverMode: "sync",
+	});
+
+	const baseSyncConfig: BaseSyncConfig<TTable> = {
+		table,
+		readyPromise: config.readyPromise ?? Promise.resolve(),
+		syncMode: config.syncMode,
+		debug: config.debug,
+	};
+
+	const syncResult = createSyncFunction(baseSyncConfig, backend);
+
+	const schema = createInsertSchemaWithIdDefault(table);
+
+	return createCollectionConfig({
+		schema,
+		getKey: createGetKeyFunction<TTable>(),
+		syncResult,
+		onInsert: config.debug
+			? async (params) => {
+					console.log("onInsert", params);
+					// biome-ignore lint/style/noNonNullAssertion: defined when sync runs
+					await syncResult.onInsert!(params);
+				}
+			: undefined,
+		onUpdate: config.debug
+			? async (params) => {
+					console.log("onUpdate", params);
+					// biome-ignore lint/style/noNonNullAssertion: defined when sync runs
+					await syncResult.onUpdate!(params);
+				}
+			: undefined,
+		onDelete: config.debug
+			? async (params) => {
+					console.log("onDelete", params);
+					// biome-ignore lint/style/noNonNullAssertion: defined when sync runs
+					await syncResult.onDelete!(params);
+				}
+			: undefined,
+		syncMode: config.syncMode,
+	});
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export {
+	durableSqliteCollectionOptions,
+	type AnyDurableSqliteDatabase,
+	type DurableDrizzleSchema,
+	type DurableSqliteCollectionConfig,
+	type DurableSqliteCollectionConfigResult,
+	type ValidTableNames,
+	type SQLOperation,
+	type SQLInterceptor,
+} from "./durable-sqlite-collection";