@firtoz/drizzle-sqlite-wasm 0.2.17 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @firtoz/drizzle-sqlite-wasm
 
+## 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)]:
+  - @firtoz/collection-sync@1.0.0
+  - @firtoz/db-helpers@2.1.0
+  - @firtoz/drizzle-utils@1.2.0
+
 ## 0.2.17
 
 ### Patch Changes

package/README.md

@@ -227,10 +227,8 @@ Create TanStack DB collections backed by SQLite:
 
 ```typescript
 import { createCollection } from "@tanstack/db";
-import {
-	drizzleCollectionOptions,
-	type DrizzleSqliteCollection,
-} from "@firtoz/drizzle-sqlite-wasm";
+import type { DrizzleSqliteTableCollection } from "@firtoz/drizzle-utils";
+import { drizzleCollectionOptions } from "@firtoz/drizzle-sqlite-wasm";
 import * as schema from "./schema";
 
 const collection = createCollection(
@@ -253,7 +251,7 @@ const completed = await collection.find({
   orderBy: { createdAt: "desc" },
 });
 
-type TodosCollection = DrizzleSqliteCollection<typeof schema.todoTable>;
+type TodosCollection = DrizzleSqliteTableCollection<typeof schema.todoTable>;
 
 // Subscribe to changes
 collection.subscribe((todos) => {
@@ -261,7 +259,7 @@ collection.subscribe((todos) => {
 });
 ```
 
-Use `DrizzleSqliteCollection<TTable>` when you want a reusable collection type alias that keeps inferred select/insert types from your table.
+Use `DrizzleSqliteTableCollection<TTable>` from `@firtoz/drizzle-utils` when you want a reusable collection type alias (shared with `@firtoz/drizzle-durable-sqlite`).
 
 ### Collection Options
 
@@ -295,11 +293,27 @@ Context provider for SQLite WASM:
 - `dbName: string` - Name of the SQLite database
 - `schema: TSchema` - Drizzle schema object
 - `migrations: DurableSqliteMigrationConfig` - Migration configuration
+- `workerOpenOptions?: SqliteWasmWorkerOpenOptions` - Optional `PRAGMA synchronous` / `journal_mode` on first DB open (see hook section below)
 
-#### `useDrizzleSqliteDb(worker, dbName, schema, migrations)`
+#### `useDrizzleSqliteDb(worker, dbName, schema, migrations, debug?, interceptor?, workerOpenOptions?)`
 
 Hook to create a Drizzle instance with Web Worker:
 
+Optional **`workerOpenOptions`** sets SQLite pragmas when the worker **first** opens that `dbName` (same global worker + same `dbName` ⇒ options from the first open win until the worker is reset):
+
+```typescript
+import type { SqliteWasmWorkerOpenOptions } from "@firtoz/drizzle-sqlite-wasm";
+
+const open: SqliteWasmWorkerOpenOptions = {
+  synchronous: "NORMAL", // default worker behavior if omitted: "FULL"
+  journalMode: "WAL", // default if omitted: "WAL"
+};
+
+useDrizzleSqliteDb(SqliteWorker, "my-app", schema, migrations, undefined, undefined, open);
+```
+
+`DrizzleSqliteProvider` accepts the same shape as **`workerOpenOptions`**.
+
 ```typescript
 function MyComponent() {
   const { drizzle, readyPromise } = useDrizzleSqliteDb(

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-sqlite-wasm",
-	"version": "0.2.17",
+	"version": "1.0.0",
 	"description": "Drizzle SQLite WASM bindings",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -40,7 +40,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"
@@ -69,13 +69,14 @@
 		"access": "public"
 	},
 	"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/worker-helper": "^1.5.1",
 		"@sqlite.org/sqlite-wasm": "^3.51.2-build8",
-		"@tanstack/db": "^0.5.33",
-		"drizzle-orm": "^0.45.1",
+		"@tanstack/db": "^0.6.1",
+		"drizzle-orm": "^0.45.2",
 		"drizzle-valibot": "^0.4.2",
 		"react": "^19.2.4",
 		"valibot": "^1.3.1",

package/src/collections/sqlite-collection.ts

@@ -1,6 +1,4 @@
 import type {
-	Collection,
-	InferSchemaInput,
 	InferSchemaOutput,
 	SyncMode,
 	CollectionConfig,
@@ -80,15 +78,6 @@ export type SqliteCollectionConfig<TTable extends Table> = Omit<
 	utils: CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>;
 };
 
-export type DrizzleSqliteCollection<TTable extends TableWithRequiredFields> =
-	Collection<
-		InferSchemaOutput<SelectSchema<TTable>>,
-		IdOf<TTable>,
-		CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>,
-		InsertToSelectSchema<TTable>,
-		InferSchemaInput<InsertToSelectSchema<TTable>>
-	>;
-
 export function sqliteCollectionOptions<
 	const TDrizzle extends AnyDrizzleDatabase,
 	const TTableName extends string & ValidTableNames<DrizzleSchema<TDrizzle>>,
@@ -101,6 +90,9 @@ export function sqliteCollectionOptions<
 
 	const table = config.drizzle?._.fullSchema[tableName] as TTable;
 
+	type TItem = InferSchemaOutput<SelectSchema<TTable>>;
+	const getKey = createGetKeyFunction<TTable>();
+
 	const backend = createSqliteTableSyncBackend({
 		drizzle: config.drizzle,
 		table,
@@ -116,6 +108,7 @@ export function sqliteCollectionOptions<
 		readyPromise: config.readyPromise,
 		syncMode: config.syncMode,
 		debug: config.debug,
+		getSyncPersistKey: (item: TItem) => String(getKey(item)),
 	};
 
 	const syncResult = createSyncFunction(baseSyncConfig, backend);
@@ -124,7 +117,7 @@ export function sqliteCollectionOptions<
 
 	const collectionConfig = createCollectionConfig({
 		schema,
-		getKey: createGetKeyFunction<TTable>(),
+		getKey,
 		syncResult,
 		onInsert: config.debug
 			? async (params) => {

package/src/collections/synced-sqlite-collection.ts

@@ -0,0 +1,47 @@
+import {
+	createSyncedCollection,
+	type SyncableCollectionItem,
+	type SyncClientBridge,
+	type SyncClientMessage,
+	type WithSyncOptions,
+} from "@firtoz/collection-sync";
+import type { Collection } from "@tanstack/db";
+import type { TableWithRequiredFields } from "@firtoz/drizzle-utils";
+import type { InferSelectModel } from "drizzle-orm";
+import type {
+	AnyDrizzleDatabase,
+	DrizzleSchema,
+	DrizzleSqliteCollectionConfig,
+	ValidTableNames,
+} from "./sqlite-collection";
+import { sqliteCollectionOptions } from "./sqlite-collection";
+
+/**
+ * Like {@link createSyncedCollection} from `@firtoz/collection-sync`, but row type uses Drizzle’s
+ * {@link InferSelectModel} so branded columns (e.g. ids) match `$inferSelect`, not Valibot schema output.
+ */
+export function createSyncedSqliteCollection<
+	const TDrizzle extends AnyDrizzleDatabase,
+	const TTableName extends string & ValidTableNames<DrizzleSchema<TDrizzle>>,
+	TTable extends DrizzleSchema<TDrizzle>[TTableName] & TableWithRequiredFields,
+>(
+	config: DrizzleSqliteCollectionConfig<TDrizzle, TTableName>,
+	syncOptions?: WithSyncOptions,
+): {
+	collection: Collection<InferSelectModel<TTable>>;
+	bridge: SyncClientBridge<InferSelectModel<TTable> & SyncableCollectionItem>;
+	setTransportSend: (send: (msg: SyncClientMessage) => void) => void;
+} {
+	type TRow = InferSelectModel<TTable>;
+	type TBridgeItem = TRow & SyncableCollectionItem;
+	const options = sqliteCollectionOptions(config);
+	const { collection, bridge, setTransportSend } = createSyncedCollection(
+		options,
+		syncOptions,
+	);
+	return {
+		collection: collection as unknown as Collection<TRow>,
+		bridge: bridge as unknown as SyncClientBridge<TBridgeItem>,
+		setTransportSend,
+	};
+}

package/src/hooks/useDrizzleSqliteDb.ts

@@ -13,6 +13,7 @@ import {
 	isSqliteWorkerInitialized,
 } from "../worker/global-manager";
 import type { SQLInterceptor } from "../collections/sqlite-collection";
+import type { SqliteWasmWorkerOpenOptions } from "../worker/sqlite-open-options";
 
 export const useDrizzleSqliteDb = <TSchema extends Record<string, unknown>>(
 	WorkerConstructor: new () => Worker,
@@ -22,6 +23,11 @@ export const useDrizzleSqliteDb = <TSchema extends Record<string, unknown>>(
 	debug?: boolean,
 	/** Optional interceptor to log ALL SQL queries (including direct Drizzle queries) */
 	interceptor?: SQLInterceptor,
+	/**
+	 * Pragmas applied when the worker first opens this `dbName` in the session.
+	 * Ignored if that database was already started (same global worker + dbName).
+	 */
+	workerOpenOptions?: SqliteWasmWorkerOpenOptions,
 ) => {
 	const resolveRef = useRef<null | (() => void)>(null);
 	const rejectRef = useRef<null | ((error: unknown) => void)>(null);
@@ -63,7 +69,7 @@ export const useDrizzleSqliteDb = <TSchema extends Record<string, unknown>>(
 				"../worker/global-manager"
 			);
 			const manager = getSqliteWorkerManager();
-			const instance = await manager.getDbInstance(dbName);
+			const instance = await manager.getDbInstance(dbName, workerOpenOptions);
 
 			if (mounted) {
 				sqliteClientRef.current = instance;
@@ -76,7 +82,7 @@ export const useDrizzleSqliteDb = <TSchema extends Record<string, unknown>>(
 		return () => {
 			mounted = false;
 		};
-	}, [dbName, WorkerConstructor]);
+	}, [dbName, WorkerConstructor, workerOpenOptions]);
 
 	// Store interceptor in a ref to avoid recreating drizzle on interceptor changes
 	const interceptorRef = useRef(interceptor);

package/src/index.ts

@@ -1,11 +1,11 @@
 export { drizzleSqliteWasm } from "./drizzle/direct";
 export {
 	sqliteCollectionOptions as drizzleCollectionOptions,
-	type DrizzleSqliteCollection,
 	type SqliteCollectionConfig,
 	type SQLOperation,
 	type SQLInterceptor,
 } from "./collections/sqlite-collection";
+export { createSyncedSqliteCollection } from "./collections/synced-sqlite-collection";
 export { syncableTable } from "@firtoz/drizzle-utils";
 export { makeId } from "@firtoz/drizzle-utils";
 export type {
@@ -34,5 +34,15 @@ export {
 } from "./worker/global-manager";
 export { SqliteWorkerManager, DbInstance } from "./worker/manager";
 export type { ISqliteWorkerClient } from "./worker/manager";
+export type {
+	SqliteWasmJournalMode,
+	SqliteWasmSynchronousMode,
+	SqliteWasmWorkerOpenOptions,
+} from "./worker/sqlite-open-options";
+export {
+	SqliteWasmJournalModeSchema,
+	SqliteWasmSynchronousModeSchema,
+	SqliteWasmWorkerOpenOptionsSchema,
+} from "./worker/sqlite-open-options";
 export { customSqliteMigrate } from "./migration/migrator";
 export type { DurableSqliteMigrationConfig } from "./migration/migrator";

package/src/worker/manager.ts

@@ -1,5 +1,6 @@
 import { exhaustiveGuard } from "@firtoz/maybe-error";
 import { WorkerClient } from "@firtoz/worker-helper/WorkerClient";
+import type { SqliteWasmWorkerOpenOptions } from "./sqlite-open-options";
 import {
 	type SqliteWorkerClientMessage,
 	type SqliteWorkerServerMessage,
@@ -257,7 +258,10 @@ export class SqliteWorkerManager extends WorkerClient<
 	/**
 	 * Get or create a database instance
 	 */
-	public async getDbInstance(dbName: string): Promise<DbInstance> {
+	public async getDbInstance(
+		dbName: string,
+		openOptions?: SqliteWasmWorkerOpenOptions,
+	): Promise<DbInstance> {
 		// Check if instance already exists
 		let instance = this.dbInstances.get(dbName);
 		if (instance) {
@@ -283,6 +287,7 @@ export class SqliteWorkerManager extends WorkerClient<
 			type: SqliteWorkerClientMessageType.Start,
 			requestId: startRequestId,
 			dbName: dbName,
+			...(openOptions !== undefined ? { openOptions } : {}),
 		});
 
 		return instance;

package/src/worker/schema.ts

@@ -1,4 +1,5 @@
 import z from "zod";
+import { SqliteWasmWorkerOpenOptionsSchema } from "./sqlite-open-options";
 
 export const RemoteCallbackIdSchema = z.string().brand("remote-callback-id");
 export type RemoteCallbackId = z.infer<typeof RemoteCallbackIdSchema>;
@@ -55,6 +56,8 @@ export const SqliteWorkerClientMessageSchema = z.discriminatedUnion("type", [
 		type: z.literal(SqliteWorkerClientMessageType.Start),
 		requestId: StartRequestIdSchema,
 		dbName: z.string(),
+		/** Applied on first open of this `dbName` in the worker process. */
+		openOptions: SqliteWasmWorkerOpenOptionsSchema.optional(),
 	}),
 	RemoteCallbackRequestSchema,
 	CheckpointRequestSchema,

package/src/worker/sqlite-open-options.ts

@@ -0,0 +1,41 @@
+import z from "zod";
+
+/**
+ * SQLite `PRAGMA synchronous` levels (see SQLite docs). Default worker behavior
+ * remains `FULL` for maximum durability with OPFS; `NORMAL` is often much faster
+ * for interactive UIs at the cost of a narrower crash window.
+ */
+export const SqliteWasmSynchronousModeSchema = z.enum([
+	"OFF",
+	"NORMAL",
+	"FULL",
+	"EXTRA",
+]);
+export type SqliteWasmSynchronousMode = z.infer<
+	typeof SqliteWasmSynchronousModeSchema
+>;
+
+/**
+ * SQLite `PRAGMA journal_mode` values the worker will pass through as
+ * `PRAGMA journal_mode=<value>;` (uppercase).
+ */
+export const SqliteWasmJournalModeSchema = z.enum([
+	"WAL",
+	"DELETE",
+	"TRUNCATE",
+	"MEMORY",
+	"OFF",
+]);
+export type SqliteWasmJournalMode = z.infer<typeof SqliteWasmJournalModeSchema>;
+
+/** Options applied once when the worker opens a database file (OPFS or transient). */
+export const SqliteWasmWorkerOpenOptionsSchema = z
+	.object({
+		synchronous: SqliteWasmSynchronousModeSchema.optional(),
+		journalMode: SqliteWasmJournalModeSchema.optional(),
+	})
+	.strict();
+
+export type SqliteWasmWorkerOpenOptions = z.infer<
+	typeof SqliteWasmWorkerOpenOptionsSchema
+>;

package/src/worker/sqlite.worker.ts

@@ -12,6 +12,7 @@ import {
 } from "./schema";
 import { handleRemoteCallback } from "../drizzle/handle-callback";
 import { exhaustiveGuard } from "@firtoz/maybe-error";
+import type { SqliteWasmWorkerOpenOptions } from "./sqlite-open-options";
 import type { Sqlite3Static, Database } from "../types";
 
 // Declare self as DedicatedWorkerGlobalScope for TypeScript
@@ -133,10 +134,31 @@ class SqliteWorkerHelper extends WorkerHelper<
 		}
 	}
 
+	private applyOpenPragmas(
+		db: Database,
+		openOptions?: SqliteWasmWorkerOpenOptions,
+	) {
+		const journalMode = openOptions?.journalMode ?? "WAL";
+		const synchronous = openOptions?.synchronous ?? "FULL";
+		try {
+			db.exec(`PRAGMA journal_mode=${journalMode};`);
+			db.exec(`PRAGMA synchronous=${synchronous};`);
+			this.log(
+				"PRAGMA journal_mode=",
+				journalMode,
+				"synchronous=",
+				synchronous,
+			);
+		} catch (e) {
+			this.error("Error applying open pragmas:", e);
+		}
+	}
+
 	private async startDatabase(
 		sqlite3: Sqlite3Static,
 		dbName: string,
 		requestId: StartRequestId,
+		openOptions?: SqliteWasmWorkerOpenOptions,
 	) {
 		const dbId = DbIdSchema.parse(crypto.randomUUID());
 
@@ -146,24 +168,14 @@ class SqliteWorkerHelper extends WorkerHelper<
 		if ("opfs" in sqlite3) {
 			db = new sqlite3.oo1.OpfsDb(dbFileName);
 			this.log("OPFS database created:", db.filename);
-
-			// Configure database for reliable persistence
-			try {
-				// Ensure WAL mode is enabled
-				db.exec("PRAGMA journal_mode=WAL;");
-				// Use FULL synchronous mode to ensure data is written to persistent storage
-				// before transactions are considered complete
-				db.exec("PRAGMA synchronous=FULL;");
-				this.log("Database configured with WAL mode and FULL synchronous");
-			} catch (e) {
-				this.error("Error configuring database:", e);
-			}
+			this.applyOpenPragmas(db, openOptions);
 		} else {
 			db = new sqlite3.oo1.DB(dbFileName, "c");
 			this.log(
 				"OPFS is not available, created transient database",
 				db.filename,
 			);
+			this.applyOpenPragmas(db, openOptions);
 		}
 
 		// Store database with initialized flag
@@ -183,7 +195,12 @@ class SqliteWorkerHelper extends WorkerHelper<
 			case SqliteWorkerClientMessageType.Start:
 				{
 					const sqlite3 = await this.initPromise;
-					await this.startDatabase(sqlite3, data.dbName, data.requestId);
+					await this.startDatabase(
+						sqlite3,
+						data.dbName,
+						data.requestId,
+						data.openOptions,
+					);
 				}
 				break;
 			case SqliteWorkerClientMessageType.RemoteCallbackRequest: