@firtoz/drizzle-utils 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @firtoz/drizzle-utils
 
+## 1.2.1
+
+### Patch Changes
+
+- [#70](https://github.com/firtoz/fullstack-toolkit/pull/70) [`138c394`](https://github.com/firtoz/fullstack-toolkit/commit/138c3944b491ebf2e76b7f2c00d651fd5d788bac) Thanks [@firtoz](https://github.com/firtoz)! - Raise TanStack DB peer range to `>=0.6.3` where applicable. `createGenericCollectionConfig` now sets `defaultIndexType: BasicIndex` and `autoIndex: "eager"` so Drizzle-backed collections match pre-0.6 indexing defaults for `orderBy`/`limit` live queries. Re-enable `DeduplicatedLoadSubset` (`USE_DEDUPE`) with `@tanstack/db` 0.6.4.
+
+- Updated dependencies [[`138c394`](https://github.com/firtoz/fullstack-toolkit/commit/138c3944b491ebf2e76b7f2c00d651fd5d788bac)]:
+  - @firtoz/db-helpers@2.1.1
+
+## 1.2.0
+
+### Minor 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)! - **`@firtoz/drizzle-utils`:** Export `DrizzleSqliteTableCollection`; extend `BaseSyncConfig` / `createCollectionConfig` for typed `getSyncPersistKey` and `getKey` as `IdOf<TTable>`; avoid executing `syncableTable` default functions during table definition for Worker/DO globals; export collection helper types for Drizzle-backed TanStack collections.
+
+  **`@firtoz/drizzle-indexeddb` (major):** `deferLocalPersistence`, `handleBatchPut`, and related collection options; `receiveSync` persistence aligned with generic sync and partial-sync traffic; remove debug ingest usage. **Breaking** alongside the `@firtoz/drizzle-utils` sync/collection typing changes above (including `DrizzleSqliteTableCollection` and `BaseSyncConfig` expectations).
+
+### Patch Changes
+
+- Updated dependencies [[`556555a`](https://github.com/firtoz/fullstack-toolkit/commit/556555a2e09030a8658be8c07b5881e72be64b2f)]:
+  - @firtoz/db-helpers@2.1.0
+
 ## 1.1.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-utils",
-	"version": "1.1.0",
+	"version": "1.2.1",
 	"description": "Shared utilities and types for Drizzle-based packages",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -25,7 +25,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"
@@ -53,19 +53,19 @@
 		"access": "public"
 	},
 	"peerDependencies": {
-		"@tanstack/db": ">=0.5.33",
-		"drizzle-orm": ">=0.45.1",
+		"@tanstack/db": ">=0.6.3",
+		"drizzle-orm": ">=0.45.2",
 		"drizzle-valibot": ">=0.4.0",
 		"valibot": ">=1.3.1"
 	},
 	"devDependencies": {
-		"@tanstack/db": "^0.5.33",
-		"drizzle-orm": "^0.45.1",
+		"@tanstack/db": "^0.6.4",
+		"drizzle-orm": "^0.45.2",
 		"drizzle-valibot": "^0.4.2",
 		"valibot": "^1.3.1"
 	},
 	"dependencies": {
-		"@firtoz/db-helpers": "^2.0.0",
+		"@firtoz/db-helpers": "^2.1.1",
 		"@firtoz/maybe-error": "^1.5.2"
 	}
 }

package/src/collection-utils.ts

@@ -108,7 +108,7 @@ export const USE_DEDUPE = _USE_DEDUPE;
  * Extends the generic (Drizzle-free) config with a Drizzle table reference.
  */
 export interface BaseSyncConfig<TTable extends Table>
-	extends GenericBaseSyncConfig {
+	extends GenericBaseSyncConfig<InferSchemaOutput<SelectSchema<TTable>>> {
 	table: TTable;
 }
 
@@ -236,10 +236,9 @@ export function createInsertSchemaWithIdDefault<TTable extends Table>(
  * Standard getKey function for collections
  */
 export function createGetKeyFunction<TTable extends Table>() {
-	return (item: InferSchemaOutput<SelectSchema<TTable>>) => {
-		const id = (item as { id: string }).id;
-		return id;
-	};
+	type TItem = InferSchemaOutput<SelectSchema<TTable>>;
+	type TKey = IdOf<TTable>;
+	return (item: TItem): TKey => (item as { id: TKey }).id;
 }
 
 /**
@@ -251,7 +250,7 @@ export function createCollectionConfig<
 	TSchema extends v.GenericSchema<unknown>,
 >(config: {
 	schema: TSchema;
-	getKey: (item: InferSchemaOutput<SelectSchema<TTable>>) => string;
+	getKey: (item: InferSchemaOutput<SelectSchema<TTable>>) => IdOf<TTable>;
 	syncResult: SyncFunctionResult<TTable>;
 	onInsert?: CollectionConfig<
 		InferSchemaOutput<SelectSchema<TTable>>,
@@ -270,17 +269,30 @@ export function createCollectionConfig<
 	>["onDelete"];
 	syncMode?: SyncMode;
 }): Omit<
-	CollectionConfig<InferSchemaOutput<SelectSchema<TTable>>, string, TSchema>,
+	CollectionConfig<
+		InferSchemaOutput<SelectSchema<TTable>>,
+		IdOf<TTable>,
+		TSchema,
+		CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>
+	>,
 	"utils"
 > & {
 	schema: TSchema;
 	utils: CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>;
 } {
 	type TItem = InferSchemaOutput<SelectSchema<TTable>>;
-	type ReturnType = Omit<CollectionConfig<TItem, string, TSchema>, "utils"> & {
+	type ReturnType = Omit<
+		CollectionConfig<TItem, IdOf<TTable>, TSchema, CollectionUtils<TItem>>,
+		"utils"
+	> & {
 		schema: TSchema;
 		utils: CollectionUtils<TItem>;
 	};
 
-	return createGenericCollectionConfig<TItem, TSchema>(config) as ReturnType;
+	const { getKey: getId, ...rest } = config;
+	return createGenericCollectionConfig<TItem, TSchema>({
+		...rest,
+		// Generic sync is typed with string keys; runtime id may be number — same value as Drizzle row id.
+		getKey: (item: TItem) => getId(item) as string,
+	}) as ReturnType;
 }

package/src/drizzle-sqlite-table-collection.ts

@@ -0,0 +1,29 @@
+import type { CollectionUtils } from "@firtoz/db-helpers";
+import type {
+	Collection,
+	InferSchemaInput,
+	InferSchemaOutput,
+} from "@tanstack/db";
+import type {
+	IdOf,
+	InsertToSelectSchema,
+	SelectSchema,
+} from "./collection-utils";
+import type { TableWithRequiredFields } from "./syncableTable";
+
+/**
+ * TanStack {@link Collection} for a syncable Drizzle SQLite table (`syncableTable` columns).
+ *
+ * Shared by `@firtoz/drizzle-sqlite-wasm` (async driver) and `@firtoz/drizzle-durable-sqlite`
+ * (Durable Object sync driver). Import this type from `@firtoz/drizzle-utils` rather than
+ * duplicating it per package.
+ */
+export type DrizzleSqliteTableCollection<
+	TTable extends TableWithRequiredFields,
+> = Collection<
+	InferSchemaOutput<SelectSchema<TTable>>,
+	IdOf<TTable>,
+	CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>,
+	InsertToSelectSchema<TTable>,
+	InferSchemaInput<InsertToSelectSchema<TTable>>
+>;

package/src/index.ts

@@ -49,6 +49,8 @@ export {
 
 export type { TableWithRequiredFields } from "./syncableTable";
 
+export type { DrizzleSqliteTableCollection } from "./drizzle-sqlite-table-collection";
+
 export type {
 	SQLOperation,
 	SQLInterceptor,

package/src/sqlite-table-sync/sqlite-table-sync-backend.ts

@@ -1,5 +1,7 @@
+import type { ReceiveSyncDurableOp } from "@firtoz/db-helpers";
+import { exhaustiveGuard } from "@firtoz/maybe-error";
 import type { InferSchemaOutput } from "@tanstack/db";
-import { and, eq, type SQL } from "drizzle-orm";
+import { and, eq, getTableColumns, sql, type SQL } from "drizzle-orm";
 import type {
 	SQLiteInsertValue,
 	SQLiteUpdateSetSource,
@@ -14,6 +16,22 @@ import type { SQLInterceptor } from "./types";
 
 export type SqliteDriverMode = "async" | "sync";
 
+/**
+ * `ON CONFLICT DO UPDATE` set map using SQLite `excluded.*` so inserts are idempotent
+ * (matches IndexedDB `put` / replayed partial-sync rows already present from `initialLoad`).
+ */
+function sqliteExcludedUpsertSet<TTable extends TableWithRequiredFields>(
+	table: TTable,
+): SQLiteUpdateSetSource<TTable> {
+	const cols = getTableColumns(table);
+	const set: Record<string, SQL> = {};
+	for (const [jsName, col] of Object.entries(cols)) {
+		if (jsName === "id") continue;
+		set[jsName] = sql.raw(`excluded."${col.name}"`);
+	}
+	return set as SQLiteUpdateSetSource<TTable>;
+}
+
 export interface SqliteTableSyncBackendConfig<
 	TTable extends TableWithRequiredFields,
 > {
@@ -35,12 +53,17 @@ export interface SqliteTableSyncBackendConfig<
 export function createSqliteTableSyncBackend<
 	TTable extends TableWithRequiredFields,
 >(config: SqliteTableSyncBackendConfig<TTable>): SyncBackend<TTable> {
+	type TItem = InferSchemaOutput<SelectSchema<TTable>>;
 	const table = config.table;
 	const driverMode = config.driverMode;
 
 	let transactionQueue = Promise.resolve();
-	const queueTransaction = <T>(fn: () => Promise<T>): Promise<T> => {
-		const result = transactionQueue.then(fn, fn);
+	const queueTransaction = <T>(
+		_label: string,
+		fn: () => Promise<T>,
+	): Promise<T> => {
+		const run = (): Promise<T> => fn();
+		const result = transactionQueue.then(run, run);
 		transactionQueue = result.then(
 			() => {},
 			() => {},
@@ -183,7 +206,7 @@ export function createSqliteTableSyncBackend<
 		handleInsert: async (items) => {
 			const results: Array<InferSchemaOutput<SelectSchema<TTable>>> = [];
 
-			await queueTransaction(async () => {
+			await queueTransaction("handleInsert", async () => {
 				if (driverMode === "sync") {
 					config.drizzle.transaction((tx: typeof config.drizzle) => {
 						for (const itemToInsert of items) {
@@ -198,6 +221,10 @@ export function createSqliteTableSyncBackend<
 								.values(
 									itemToInsert as unknown as SQLiteInsertValue<typeof table>,
 								)
+								.onConflictDoUpdate({
+									target: table.id,
+									set: sqliteExcludedUpsertSet(table),
+								})
 								.returning()
 								.all() as Array<InferSchemaOutput<SelectSchema<TTable>>>;
 							if (config.debug) {
@@ -226,6 +253,10 @@ export function createSqliteTableSyncBackend<
 									.values(
 										itemToInsert as unknown as SQLiteInsertValue<typeof table>,
 									)
+									.onConflictDoUpdate({
+										target: table.id,
+										set: sqliteExcludedUpsertSet(table),
+									})
 									.returning()) as Array<
 									InferSchemaOutput<SelectSchema<TTable>>
 								>;
@@ -254,7 +285,7 @@ export function createSqliteTableSyncBackend<
 		handleUpdate: async (mutations) => {
 			const results: Array<InferSchemaOutput<SelectSchema<TTable>>> = [];
 
-			await queueTransaction(async () => {
+			await queueTransaction("handleUpdate", async () => {
 				if (driverMode === "sync") {
 					config.drizzle.transaction((tx: typeof config.drizzle) => {
 						for (const mutation of mutations) {
@@ -327,7 +358,7 @@ export function createSqliteTableSyncBackend<
 		},
 
 		handleDelete: async (mutations) => {
-			await queueTransaction(async () => {
+			await queueTransaction("handleDelete", async () => {
 				if (driverMode === "sync") {
 					config.drizzle.transaction((tx: typeof config.drizzle) => {
 						for (const mutation of mutations) {
@@ -350,6 +381,149 @@ export function createSqliteTableSyncBackend<
 					);
 				}
 
+				if (config.checkpoint) {
+					await config.checkpoint();
+				}
+			});
+		},
+		handleTruncate: async () => {
+			await queueTransaction("handleTruncate", async () => {
+				if (driverMode === "sync") {
+					config.drizzle.transaction((tx: typeof config.drizzle) => {
+						tx.delete(table).run();
+					});
+				} else {
+					await config.drizzle.transaction(
+						async (tx: typeof config.drizzle) => {
+							await tx.delete(table);
+						},
+					);
+				}
+
+				if (config.checkpoint) {
+					await config.checkpoint();
+				}
+			});
+		},
+
+		applyReceiveSyncDurableWrites: async (
+			ops: ReceiveSyncDurableOp<TItem>[],
+		) => {
+			if (ops.length === 0) return;
+
+			await queueTransaction("applyReceiveSyncDurableWrites", async () => {
+				if (driverMode === "sync") {
+					config.drizzle.transaction((tx: typeof config.drizzle) => {
+						for (const op of ops) {
+							switch (op.type) {
+								case "insert": {
+									if (config.debug) {
+										console.log(
+											`[${new Date().toISOString()}] receiveSync batch insert`,
+											op.value,
+										);
+									}
+									tx.insert(table)
+										.values(
+											op.value as unknown as SQLiteInsertValue<typeof table>,
+										)
+										.onConflictDoUpdate({
+											target: table.id,
+											set: sqliteExcludedUpsertSet(table),
+										})
+										.run();
+									break;
+								}
+								case "update": {
+									if (config.debug) {
+										console.log(
+											`[${new Date().toISOString()}] receiveSync batch update`,
+											op,
+										);
+									}
+									const updateTime = new Date();
+									tx.update(table)
+										.set({
+											...op.changes,
+											updatedAt: updateTime,
+										} as SQLiteUpdateSetSource<typeof table>)
+										// biome-ignore lint/suspicious/noExplicitAny: branded id key
+										.where(eq(table.id, op.key as any))
+										.run();
+									break;
+								}
+								case "delete":
+									tx.delete(table)
+										// biome-ignore lint/suspicious/noExplicitAny: branded id key
+										.where(eq(table.id, op.key as any))
+										.run();
+									break;
+								case "truncate":
+									tx.delete(table).run();
+									break;
+								default:
+									exhaustiveGuard(op);
+							}
+						}
+					});
+				} else {
+					await config.drizzle.transaction(
+						async (tx: typeof config.drizzle) => {
+							for (const op of ops) {
+								switch (op.type) {
+									case "insert": {
+										if (config.debug) {
+											console.log(
+												`[${new Date().toISOString()}] receiveSync batch insert`,
+												op.value,
+											);
+										}
+										await tx
+											.insert(table)
+											.values(
+												op.value as unknown as SQLiteInsertValue<typeof table>,
+											)
+											.onConflictDoUpdate({
+												target: table.id,
+												set: sqliteExcludedUpsertSet(table),
+											});
+										break;
+									}
+									case "update": {
+										if (config.debug) {
+											console.log(
+												`[${new Date().toISOString()}] receiveSync batch update`,
+												op,
+											);
+										}
+										const updateTime = new Date();
+										await tx
+											.update(table)
+											.set({
+												...op.changes,
+												updatedAt: updateTime,
+											} as SQLiteUpdateSetSource<typeof table>)
+											// biome-ignore lint/suspicious/noExplicitAny: branded id key
+											.where(eq(table.id, op.key as any));
+										break;
+									}
+									case "delete":
+										await tx
+											.delete(table)
+											// biome-ignore lint/suspicious/noExplicitAny: branded id key
+											.where(eq(table.id, op.key as any));
+										break;
+									case "truncate":
+										await tx.delete(table);
+										break;
+									default:
+										exhaustiveGuard(op);
+								}
+							}
+						},
+					);
+				}
+
 				if (config.checkpoint) {
 					await config.checkpoint();
 				}

package/src/syncableTable.ts

@@ -75,14 +75,12 @@ export const syncableTable = <
 	for (const columnName in tableColumns) {
 		const column = tableColumns[columnName];
 
-		let defaultValue: unknown | undefined;
+		// Avoid executing defaultFn at module initialization time.
+		// In Cloudflare Workers this can trigger disallowed global-scope APIs.
 		if (column.defaultFn) {
-			defaultValue = column.defaultFn();
-		} else if (column.default !== undefined) {
-			defaultValue = column.default;
+			continue;
 		}
-
-		if (defaultValue instanceof SQL) {
+		if (column.default instanceof SQL) {
 			throw new Error(
 				`Default value for column ${tableName}.${columnName} is a SQL expression, which is not supported for IndexedDB.\n\nYou can use a default value or a default function instead.`,
 			);