@firtoz/drizzle-durable-sqlite 0.2.1 → 1.0.1

package/src/partial-sync-predicate-sql.ts

@@ -0,0 +1,157 @@
+import type { RangeCondition } from "@firtoz/collection-sync";
+import { exhaustiveGuard } from "@firtoz/maybe-error";
+import {
+	and,
+	eq,
+	getTableColumns,
+	gt,
+	gte,
+	lt,
+	lte,
+	ne,
+	type SQL,
+} from "drizzle-orm";
+import type { SQLiteColumn, SQLiteTable } from "drizzle-orm/sqlite-core";
+
+/** Column kind for predicate coercion and sort. */
+export type PartialSyncColumnKind = "text" | "integer";
+
+export type PartialSyncTableColumnConfig = {
+	kind: PartialSyncColumnKind;
+	/**
+	 * When kind is `integer`, use `Math.trunc` after `Number()` (grid coordinates).
+	 * Default false: finite number only.
+	 */
+	truncateInteger?: boolean;
+};
+
+/**
+ * Declares which table columns exist for predicates/sorts and how to coerce literals.
+ * `sortableColumns` must be a subset of keys in `columns`.
+ */
+export type PartialSyncTableConfig<TSortable extends string = string> = {
+	columns: Record<string, PartialSyncTableColumnConfig>;
+	sortableColumns: readonly TSortable[];
+};
+
+export function columnRefForPredicate(
+	table: SQLiteTable,
+	columnName: string,
+	columnConfig: PartialSyncTableConfig,
+): SQLiteColumn {
+	const meta = columnConfig.columns[columnName];
+	if (meta === undefined) {
+		throw new Error(`Unsupported predicate column: ${columnName}`);
+	}
+	const cols = getTableColumns(table);
+	const col = cols[columnName];
+	if (col === undefined) {
+		throw new Error(`Table has no column: ${columnName}`);
+	}
+	return col as SQLiteColumn;
+}
+
+export function coercePredicateScalar(
+	column: string,
+	value: unknown,
+	columnConfig: PartialSyncTableConfig,
+): string | number {
+	const meta = columnConfig.columns[column];
+	if (meta === undefined) {
+		throw new Error(`Unsupported predicate column: ${column}`);
+	}
+	if (meta.kind === "integer") {
+		const n = Number(value);
+		if (!Number.isFinite(n)) {
+			throw new Error(`Predicate ${column} value must be a finite number`);
+		}
+		return meta.truncateInteger === true ? Math.trunc(n) : n;
+	}
+	return String(value);
+}
+
+export function rangeConditionToSQL(
+	table: SQLiteTable,
+	condition: RangeCondition,
+	columnConfig: PartialSyncTableConfig,
+): SQL {
+	const col = columnRefForPredicate(table, condition.column, columnConfig);
+	switch (condition.op) {
+		case "eq":
+			return eq(
+				col,
+				coercePredicateScalar(condition.column, condition.value, columnConfig),
+			);
+		case "neq":
+			return ne(
+				col,
+				coercePredicateScalar(condition.column, condition.value, columnConfig),
+			);
+		case "gt":
+			return gt(
+				col,
+				coercePredicateScalar(condition.column, condition.value, columnConfig),
+			);
+		case "gte":
+			return gte(
+				col,
+				coercePredicateScalar(condition.column, condition.value, columnConfig),
+			);
+		case "lt":
+			return lt(
+				col,
+				coercePredicateScalar(condition.column, condition.value, columnConfig),
+			);
+		case "lte":
+			return lte(
+				col,
+				coercePredicateScalar(condition.column, condition.value, columnConfig),
+			);
+		case "between": {
+			const from = coercePredicateScalar(
+				condition.column,
+				condition.value,
+				columnConfig,
+			);
+			const to = coercePredicateScalar(
+				condition.column,
+				condition.valueTo,
+				columnConfig,
+			);
+			return and(gte(col, from), lte(col, to)) as SQL;
+		}
+		default:
+			exhaustiveGuard(condition.op);
+	}
+}
+
+export function predicateWhereFromConditions(
+	table: SQLiteTable,
+	conditions: RangeCondition[],
+	columnConfig: PartialSyncTableConfig,
+): SQL | undefined {
+	if (conditions.length === 0) return undefined;
+	const parts = conditions.map((c) =>
+		rangeConditionToSQL(table, c, columnConfig),
+	);
+	return parts.length === 1 ? parts[0] : (and(...parts) as SQL);
+}
+
+export function sortColumnFromConfig(
+	table: SQLiteTable,
+	columnName: string,
+	columnConfig: PartialSyncTableConfig,
+): SQLiteColumn {
+	if (!columnConfig.sortableColumns.includes(columnName as never)) {
+		throw new Error(`Unsupported sort column: ${columnName}`);
+	}
+	if (columnConfig.columns[columnName] === undefined) {
+		throw new Error(`Unknown column in sort: ${columnName}`);
+	}
+	const cols = getTableColumns(table);
+	const col = cols[columnName];
+	if (col === undefined) {
+		throw new Error(`Table has no column: ${columnName}`);
+	}
+	return col as SQLiteColumn;
+}

package/src/partial-sync-sqlite-db.ts

@@ -0,0 +1,8 @@
+import type { DrizzleSqliteDODatabase } from "drizzle-orm/durable-sqlite";
+
+/**
+ * Drizzle Durable Object SQLite database used by partial-sync helpers.
+ * (Bun/libsql drivers differ in `select` overloads; use DO SQLite in Workers.)
+ */
+export type PartialSyncSqliteDatabase<TSchema extends Record<string, unknown>> =
+	DrizzleSqliteDODatabase<TSchema>;

package/src/queryable-durable-object.ts

@@ -0,0 +1,413 @@
+import {
+	PartialSyncMutationHandler,
+	PartialSyncServerBridge,
+	createClientMessageSchema,
+	createServerMessageSchema,
+	DEFAULT_SYNC_COLLECTION_ID,
+	type PartialSyncServerBridgeStore,
+	type PartialSyncRowShape,
+	type RangeCondition,
+	type SyncClientMessage,
+	type SyncRange,
+	type SyncRangeSort,
+	type SyncServerBridgeStore,
+	type SyncServerMessage,
+} from "@firtoz/collection-sync";
+import type { SyncMessage } from "@firtoz/db-helpers";
+import {
+	ZodSession,
+	ZodWebSocketDO,
+	type ZodSessionOptions,
+} from "@firtoz/websocket-do";
+import type { DrizzleSqliteDODatabase } from "drizzle-orm/durable-sqlite";
+import { drizzle } from "drizzle-orm/durable-sqlite";
+import { migrate } from "drizzle-orm/durable-sqlite/migrator";
+import type { Context } from "hono";
+
+type SessionData = { clientId: string };
+
+type MutationSyncRow = PartialSyncRowShape;
+
+type SessionDispatch<TRow extends MutationSyncRow> = {
+	partialBridge: PartialSyncServerBridge<TRow>;
+	partialMutationHandler?: PartialSyncMutationHandler<TRow>;
+};
+
+type SessionSlot<TRow extends MutationSyncRow> = {
+	dispatch?: SessionDispatch<TRow>;
+	pending: SyncClientMessage[];
+};
+
+function createSessionCodecOptions<TItem extends PartialSyncRowShape>(
+	enableBufferMessages: boolean,
+	serializeJson?: (value: unknown) => string,
+	deserializeJson?: (raw: string) => unknown,
+): ZodSessionOptions<SyncClientMessage, SyncServerMessage<TItem>> {
+	const clientSchema = createClientMessageSchema();
+	const serverSchema = createServerMessageSchema<TItem>();
+	if (!enableBufferMessages) {
+		return {
+			clientSchema,
+			serverSchema,
+			enableBufferMessages: false,
+			...(serializeJson && deserializeJson
+				? { serializeJson, deserializeJson }
+				: {}),
+		};
+	}
+	return {
+		clientSchema,
+		serverSchema,
+		enableBufferMessages: true,
+	};
+}
+
+async function routeQueryableClientMessage<TRow extends MutationSyncRow>(
+	message: SyncClientMessage,
+	dispatch: SessionDispatch<TRow>,
+): Promise<void> {
+	const mid = message.collectionId ?? DEFAULT_SYNC_COLLECTION_ID;
+	switch (message.type) {
+		case "mutateBatch":
+		case "syncHello":
+			if (
+				dispatch.partialMutationHandler !== undefined &&
+				mid === dispatch.partialMutationHandler.collectionId
+			) {
+				await dispatch.partialMutationHandler.handleClientMessage(message);
+			}
+			return;
+		default:
+			if (mid === dispatch.partialBridge.collectionId) {
+				await dispatch.partialBridge.handleClientMessage(message);
+			}
+	}
+}
+
+class QueryableSession<
+	TItem extends PartialSyncRowShape,
+	TEnv extends Cloudflare.Env,
+> extends ZodSession<
+	SessionData,
+	SyncServerMessage<TItem>,
+	SyncClientMessage,
+	TEnv
+> {
+	public clientId: string;
+
+	constructor(
+		websocket: WebSocket,
+		sessions: Map<WebSocket, QueryableSession<TItem, TEnv>>,
+		options: ZodSessionOptions<SyncClientMessage, SyncServerMessage<TItem>>,
+		private readonly sessionSlot: SessionSlot<TItem>,
+	) {
+		const generatedClientId = crypto.randomUUID();
+		super(websocket, sessions, options, {
+			createData: () => ({ clientId: generatedClientId }),
+			handleValidatedMessage: async (message: SyncClientMessage) => {
+				this.clientId = message.clientId;
+				const dispatch = this.sessionSlot.dispatch;
+				if (dispatch === undefined) {
+					this.sessionSlot.pending.push(message);
+					return;
+				}
+				await routeQueryableClientMessage(message, dispatch);
+			},
+			handleClose: async () => {
+				const dispatch = this.sessionSlot.dispatch;
+				if (dispatch !== undefined) {
+					dispatch.partialBridge.removeClient(this.clientId);
+				}
+			},
+		});
+		this.clientId = generatedClientId;
+	}
+}
+
+export type QueryableDurableObjectConfig<
+	TSchema extends Record<string, unknown>,
+	TRow extends PartialSyncRowShape = PartialSyncRowShape,
+> = {
+	schema: TSchema;
+	migrations: Parameters<typeof migrate>[1];
+	queryChunkSize?: number;
+	seedInBackground?: boolean;
+	serializeJson?: (value: unknown) => string;
+	deserializeJson?: (raw: string) => unknown;
+	/**
+	 * When set, used as the partial-sync store instead of overriding
+	 * {@link QueryableDurableObject.queryRange}, {@link QueryableDurableObject.queryByOffset},
+	 * and {@link QueryableDurableObject.getTotalCount}.
+	 */
+	createPartialSyncStore?: (
+		db: DrizzleSqliteDODatabase<TSchema>,
+	) => PartialSyncServerBridgeStore<TRow>;
+	/**
+	 * Multiplex key for partial-sync WebSocket messages.
+	 * When using {@link PartialSyncMutationHandler} on the same socket, use the same id unless you multiplex multiple collections.
+	 */
+	collectionId?: string;
+	/**
+	 * Server-side narrowing of client predicate viewports (e.g. fog of war). Passed to
+	 * {@link PartialSyncServerBridge}.
+	 */
+	resolveClientVisibility?: (
+		clientId: string,
+		requestedConditions: RangeCondition[],
+	) => RangeCondition[] | Promise<RangeCondition[]>;
+	/**
+	 * Optional hints for rows that left the client's range during `rangeReconcile`. Return `null` for
+	 * fog of war (default when omitted).
+	 */
+	resolveMovedHint?: (
+		row: TRow,
+		range: SyncRange,
+	) => Record<string, unknown> | null | Promise<Record<string, unknown> | null>;
+};
+
+export abstract class QueryableDurableObject<
+	TRow extends PartialSyncRowShape,
+	TSchema extends Record<string, unknown>,
+	TEnv extends Cloudflare.Env = Cloudflare.Env,
+> extends ZodWebSocketDO<
+	QueryableSession<TRow, TEnv>,
+	SyncClientMessage,
+	SyncServerMessage<TRow>,
+	TEnv
+> {
+	protected db!: ReturnType<typeof drizzle>;
+	protected bridge!: PartialSyncServerBridge<TRow>;
+	protected partialMutationHandler?: PartialSyncMutationHandler<TRow>;
+
+	readonly app = this.getBaseApp().get("/health", (c: Context) => c.text("ok"));
+
+	constructor(
+		ctx: DurableObjectState,
+		env: TEnv,
+		config: QueryableDurableObjectConfig<TSchema, TRow>,
+	) {
+		let bridgeRef!: PartialSyncServerBridge<TRow>;
+		const sessionSlot: SessionSlot<TRow> = { pending: [] };
+		super(ctx, env, {
+			zodSessionOptions: (
+				sessionCtx: Context<{ Bindings: TEnv }> | undefined,
+			) => {
+				const useMsgpack =
+					sessionCtx !== undefined &&
+					new URL(sessionCtx.req.url).searchParams.get("transport") ===
+						"msgpack";
+				return createSessionCodecOptions<TRow>(
+					useMsgpack,
+					config.serializeJson,
+					config.deserializeJson,
+				);
+			},
+			createZodSession: (
+				_sessionCtx: Context<{ Bindings: TEnv }> | undefined,
+				websocket: WebSocket,
+				options: ZodSessionOptions<
+					SyncClientMessage,
+					SyncServerMessage<unknown>
+				>,
+			) =>
+				new QueryableSession<TRow, TEnv>(
+					websocket,
+					this.sessions as Map<WebSocket, QueryableSession<TRow, TEnv>>,
+					options as ZodSessionOptions<
+						SyncClientMessage,
+						SyncServerMessage<TRow>
+					>,
+					sessionSlot,
+				),
+		});
+
+		this.ctx.blockConcurrencyWhile(async () => {
+			const db = drizzle(ctx.storage, { schema: config.schema });
+			migrate(db, config.migrations);
+			this.db = db;
+
+			const queryByPredicate = this.queryByPredicate;
+			const getPredicateCount = this.getPredicateCount;
+			const changesSince = this.changesSince;
+
+			const store: PartialSyncServerBridgeStore<TRow> =
+				config.createPartialSyncStore !== undefined
+					? config.createPartialSyncStore(db)
+					: {
+							queryRange: (options) => this.queryRange(options),
+							queryByOffset: (options) => this.queryByOffset(options),
+							getTotalCount: async () => this.getTotalCount(),
+							getSortValue: (row, column) => this.getSortValue(row, column),
+							...(queryByPredicate !== undefined
+								? {
+										queryByPredicate: (opts: {
+											conditions: RangeCondition[];
+											sort?: SyncRangeSort;
+											limit?: number;
+											chunkSize: number;
+										}) => queryByPredicate.call(this, opts),
+									}
+								: {}),
+							...(getPredicateCount !== undefined
+								? {
+										getPredicateCount: (conditions: RangeCondition[]) =>
+											getPredicateCount.call(this, conditions),
+									}
+								: {}),
+							...(changesSince !== undefined
+								? {
+										changesSince: (opts: {
+											range: SyncRange;
+											sinceVersion: number;
+											chunkSize: number;
+										}) => changesSince.call(this, opts),
+									}
+								: {}),
+						};
+			const collectionId = config.collectionId ?? DEFAULT_SYNC_COLLECTION_ID;
+			bridgeRef = new PartialSyncServerBridge<TRow>({
+				store,
+				sendToClient: (clientId, message) =>
+					this.sendToClient(clientId, message),
+				queryChunkSize: config.queryChunkSize,
+				collectionId,
+				...(config.resolveClientVisibility !== undefined
+					? {
+							resolveClientVisibility: config.resolveClientVisibility,
+						}
+					: {}),
+				...(config.resolveMovedHint !== undefined
+					? { resolveMovedHint: config.resolveMovedHint }
+					: {}),
+			});
+			this.bridge = bridgeRef;
+
+			const mutationStore = this.createClientMutationSyncStore();
+			let partialMutationHandler: PartialSyncMutationHandler<TRow> | undefined;
+			if (mutationStore !== undefined) {
+				partialMutationHandler = new PartialSyncMutationHandler<TRow>({
+					store: mutationStore,
+					partialBridge: bridgeRef,
+					sendToClient: (clientId, message) =>
+						this.sendToClient(clientId, message),
+					collectionId,
+				});
+				this.partialMutationHandler = partialMutationHandler;
+			}
+
+			sessionSlot.dispatch = {
+				partialBridge: bridgeRef,
+				partialMutationHandler,
+			};
+			for (const message of sessionSlot.pending) {
+				await routeQueryableClientMessage(message, sessionSlot.dispatch);
+			}
+			sessionSlot.pending.length = 0;
+			if (config.seedInBackground) {
+				void this.seedData().catch((error: unknown) => {
+					console.error("Background seedData failed", error);
+				});
+				return;
+			}
+			await this.seedData();
+		});
+	}
+
+	protected queryRange(_options: {
+		sort: { column: string; direction: "asc" | "desc" };
+		limit: number;
+		afterCursor: unknown | null;
+		chunkSize: number;
+	}): AsyncIterable<TRow[]> {
+		const message =
+			"QueryableDurableObject: override queryRange() or pass createPartialSyncStore in config";
+		return {
+			[Symbol.asyncIterator](): AsyncIterator<TRow[]> {
+				return {
+					next: () => Promise.reject(new Error(message)),
+				};
+			},
+		};
+	}
+
+	protected queryByOffset(_options: {
+		sort: { column: string; direction: "asc" | "desc" };
+		limit: number;
+		offset: number;
+		chunkSize: number;
+	}): AsyncIterable<TRow[]> {
+		const message =
+			"QueryableDurableObject: override queryByOffset() or pass createPartialSyncStore in config";
+		return {
+			[Symbol.asyncIterator](): AsyncIterator<TRow[]> {
+				return {
+					next: () => Promise.reject(new Error(message)),
+				};
+			},
+		};
+	}
+
+	protected async getTotalCount(): Promise<number> {
+		throw new Error(
+			"QueryableDurableObject: override getTotalCount() or pass createPartialSyncStore in config",
+		);
+	}
+
+	protected queryByPredicate?(_options: {
+		conditions: RangeCondition[];
+		sort?: SyncRangeSort;
+		limit?: number;
+		chunkSize: number;
+	}): AsyncIterable<TRow[]>;
+
+	protected getPredicateCount?(_conditions: RangeCondition[]): Promise<number>;
+
+	protected changesSince?(_options: {
+		range: SyncRange;
+		sinceVersion: number;
+		chunkSize: number;
+	}): Promise<{ changes: SyncMessage<TRow>[]; totalCount: number } | null>;
+
+	protected getSortValue(row: TRow, column: string): unknown {
+		return (row as Record<string, unknown>)[column];
+	}
+
+	/**
+	 * When overridden to return a store, `mutateBatch` is handled by {@link PartialSyncMutationHandler}
+	 * (interest-scoped `rangePatch` + `ack` with `serverVersion: 0`). `syncHello` is not handled on this path.
+	 * Range traffic stays on {@link PartialSyncServerBridge}.
+	 */
+	protected createClientMutationSyncStore():
+		| SyncServerBridgeStore<TRow>
+		| undefined {
+		return undefined;
+	}
+
+	protected async seedData(): Promise<void> {}
+
+	async pushServerChanges(changes: SyncMessage<TRow>[]): Promise<void> {
+		await this.bridge.pushServerChanges(changes);
+	}
+
+	protected sendToClient(
+		clientId: string,
+		message: SyncServerMessage<TRow>,
+	): void {
+		for (const session of this.sessions.values()) {
+			const typedSession = session as QueryableSession<TRow, TEnv>;
+			if (typedSession.clientId !== clientId) continue;
+			typedSession.send(message);
+		}
+	}
+
+	protected broadcastExcept(
+		excludeClientId: string,
+		message: SyncServerMessage<TRow>,
+	): void {
+		for (const session of this.sessions.values()) {
+			const typedSession = session as QueryableSession<TRow, TEnv>;
+			if (typedSession.clientId === excludeClientId) continue;
+			typedSession.send(message);
+		}
+	}
+}