@firtoz/drizzle-utils 0.3.3 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @firtoz/drizzle-utils
 
+## 1.0.1
+
+### Patch Changes
+
+- [`5c667ec`](https://github.com/firtoz/fullstack-toolkit/commit/5c667ecfce1ed4f22ccf9686ad37f00e7a4ecee3) Thanks [@firtoz](https://github.com/firtoz)! - Refactor `SyncBackend`, `createSyncFunction`, and `createCollectionConfig` to delegate to generic (Drizzle-free) implementations from `@firtoz/db-helpers`. No public API changes.
+
+- Updated dependencies [[`5c667ec`](https://github.com/firtoz/fullstack-toolkit/commit/5c667ecfce1ed4f22ccf9686ad37f00e7a4ecee3), [`5c667ec`](https://github.com/firtoz/fullstack-toolkit/commit/5c667ecfce1ed4f22ccf9686ad37f00e7a4ecee3)]:
+  - @firtoz/db-helpers@2.0.0
+
+## 1.0.0
+
+### Major Changes
+
+- [`3c7ce1d`](https://github.com/firtoz/fullstack-toolkit/commit/3c7ce1dbca5c5396386db9927ae7f5e19a562cf6) Thanks [@firtoz](https://github.com/firtoz)! - **Unified collection sync**
+
+  `CollectionUtils` now exposes `receiveSync(messages: SyncMessage<T>[])` instead of `pushExternalSync`. Canonical sync message type is `SyncMessage<T, TKey>` (`insert` | `update` | `delete` | `truncate`). `ExternalSyncEvent` / `ExternalSyncHandler` are internal only.
+
+  **Upgrade:** Replace `utils.pushExternalSync(events)` with `utils.receiveSync(messages)`. Import `SyncMessage` from `@firtoz/drizzle-utils` (or from `@firtoz/db-helpers`) and send per-mutation messages: `{ type: "insert", value }`, `{ type: "update", value, previousValue }`, `{ type: "delete", key }`, or `{ type: "truncate" }`. Stop using `ExternalSyncEvent` / `ExternalSyncHandler` in your code; they are no longer part of the public API. Generic sync types (`SyncMessage`, `CollectionUtils`) are now defined in `@firtoz/db-helpers` and re-exported here for backward compatibility.
+
+### Patch Changes
+
+- Updated dependencies [[`3c7ce1d`](https://github.com/firtoz/fullstack-toolkit/commit/3c7ce1dbca5c5396386db9927ae7f5e19a562cf6)]:
+  - @firtoz/db-helpers@1.0.0
+
 ## 0.3.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-utils",
-	"version": "0.3.3",
+	"version": "1.0.1",
 	"description": "Shared utilities and types for Drizzle-based packages",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -53,15 +53,19 @@
 		"access": "public"
 	},
 	"peerDependencies": {
-		"@tanstack/db": ">=0.5.25",
+		"@tanstack/db": ">=0.5.33",
 		"drizzle-orm": ">=0.45.1",
 		"drizzle-valibot": ">=0.4.0",
 		"valibot": ">=1.0.0"
 	},
 	"devDependencies": {
-		"@tanstack/db": "^0.5.25",
+		"@tanstack/db": "^0.5.33",
 		"drizzle-orm": "^0.45.1",
 		"drizzle-valibot": "^0.4.2",
 		"valibot": "^1.2.0"
+	},
+	"dependencies": {
+		"@firtoz/db-helpers": "^2.0.0",
+		"@firtoz/maybe-error": "^1.5.2"
 	}
 }

package/src/collection-utils.ts

@@ -1,3 +1,12 @@
+import type { CollectionUtils } from "@firtoz/db-helpers";
+import {
+	type GenericBaseSyncConfig,
+	type GenericSyncBackend,
+	type GenericSyncFunctionResult,
+	createGenericSyncFunction,
+	createGenericCollectionConfig,
+	USE_DEDUPE as _USE_DEDUPE,
+} from "@firtoz/db-helpers";
 import { type Table, SQL, getTableColumns } from "drizzle-orm";
 import type { BuildSchema } from "drizzle-valibot";
 import { createInsertSchema } from "drizzle-valibot";
@@ -7,12 +16,8 @@ import type {
 	UtilsRecord,
 	CollectionConfig,
 	InferSchemaOutput,
-	SyncConfig,
-	SyncConfigRes,
 	SyncMode,
-	LoadSubsetOptions,
 } from "@tanstack/db";
-import { DeduplicatedLoadSubset } from "@tanstack/db";
 
 /**
  * Utility type for branded IDs
@@ -87,374 +92,41 @@ export type InferCollectionFromTable<TTable extends Table> = Collection<
 	}
 >;
 
-// WORKAROUND: DeduplicatedLoadSubset has a bug where toggling queries (e.g., isNull/isNotNull)
-// creates invalid expressions like not(or(isNull(...), not(isNull(...))))
-// See: https://github.com/TanStack/db/issues/828
-// TODO: Re-enable once the bug is fixed
-export const USE_DEDUPE = false as boolean;
+export const USE_DEDUPE = _USE_DEDUPE;
 
 /**
- * Base configuration for sync lifecycle management
+ * Base configuration for sync lifecycle management.
+ * Extends the generic (Drizzle-free) config with a Drizzle table reference.
  */
-export interface BaseSyncConfig<TTable extends Table> {
-	/**
-	 * The Drizzle table definition
-	 */
+export interface BaseSyncConfig<TTable extends Table>
+	extends GenericBaseSyncConfig {
 	table: TTable;
-	/**
-	 * Promise that resolves when the database is ready
-	 */
-	readyPromise: Promise<void>;
-	/**
-	 * Sync mode: 'eager' (immediate) or 'lazy' (on-demand)
-	 */
-	syncMode?: SyncMode;
-	/**
-	 * Enable debug logging
-	 */
-	debug?: boolean;
-}
-
-/**
- * Backend-specific implementations required for sync
- */
-export interface SyncBackend<TTable extends Table> {
-	/**
-	 * Initial data load - should call write() for each item
-	 */
-	initialLoad: () => Promise<Array<InferSchemaOutput<SelectSchema<TTable>>>>;
-	/**
-	 * Load a subset of data based on query options
-	 */
-	loadSubset: (
-		options: LoadSubsetOptions,
-	) => Promise<Array<InferSchemaOutput<SelectSchema<TTable>>>>;
-	/**
-	 * Handle insert mutations
-	 */
-	handleInsert: (
-		items: Array<InferSchemaOutput<SelectSchema<TTable>>>,
-	) => Promise<Array<InferSchemaOutput<SelectSchema<TTable>>>>;
-	/**
-	 * Handle update mutations
-	 */
-	handleUpdate: (
-		mutations: Array<{
-			key: string;
-			changes: Partial<InferSchemaOutput<SelectSchema<TTable>>>;
-			original: InferSchemaOutput<SelectSchema<TTable>>;
-		}>,
-	) => Promise<Array<InferSchemaOutput<SelectSchema<TTable>>>>;
-	/**
-	 * Handle delete mutations
-	 */
-	handleDelete: (
-		mutations: Array<{
-			key: string;
-			modified: InferSchemaOutput<SelectSchema<TTable>>;
-			original: InferSchemaOutput<SelectSchema<TTable>>;
-		}>,
-	) => Promise<void>;
-	/**
-	 * Handle truncate (clear all data from store)
-	 * Optional - if not provided, truncate util won't be available
-	 */
-	handleTruncate?: () => Promise<void>;
 }
 
 /**
- * External sync event for pushing changes from outside (e.g., from a proxy server)
+ * Backend-specific implementations required for sync.
+ * Drizzle-typed alias for GenericSyncBackend.
  */
-export type ExternalSyncEvent<T> =
-	| { type: "insert"; items: T[] }
-	| { type: "update"; items: T[] }
-	| { type: "delete"; items: T[] }
-	| { type: "truncate" };
-
-/**
- * Handler for external sync events
- */
-export type ExternalSyncHandler<T> = (event: ExternalSyncEvent<T>) => void;
+export type SyncBackend<TTable extends Table> = GenericSyncBackend<
+	InferSchemaOutput<SelectSchema<TTable>>
+>;
 
 /**
- * Collection utils that include truncate and external sync functionality
+ * Return type for createSyncFunction.
+ * Drizzle-typed alias for GenericSyncFunctionResult.
  */
-export interface CollectionUtils<T = unknown> {
-	/**
-	 * Clear all data from the store (truncate).
-	 * This clears the backend store and updates the local reactive store.
-	 */
-	truncate: () => Promise<void>;
-	/**
-	 * Push external sync events to the collection.
-	 * Use this when receiving sync messages from a proxy server or other external source.
-	 */
-	pushExternalSync: ExternalSyncHandler<T>;
-}
+export type SyncFunctionResult<TTable extends Table> =
+	GenericSyncFunctionResult<InferSchemaOutput<SelectSchema<TTable>>>;
 
 /**
- * Return type for createSyncFunction that includes both sync config and listeners
- */
-export type SyncFunctionResult<TTable extends Table> = {
-	sync: SyncConfig<InferSchemaOutput<SelectSchema<TTable>>, string>["sync"];
-	onInsert: CollectionConfig<
-		InferSchemaOutput<SelectSchema<TTable>>,
-		string,
-		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
-		any
-	>["onInsert"];
-	onUpdate: CollectionConfig<
-		InferSchemaOutput<SelectSchema<TTable>>,
-		string,
-		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
-		any
-	>["onUpdate"];
-	onDelete: CollectionConfig<
-		InferSchemaOutput<SelectSchema<TTable>>,
-		string,
-		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
-		any
-	>["onDelete"];
-	/**
-	 * Collection utilities including truncate and external sync
-	 */
-	utils: CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>;
-};
-
-/**
- * Creates the sync function with common lifecycle management
+ * Creates the sync function with common lifecycle management.
+ * Delegates to the generic (Drizzle-free) implementation in @firtoz/db-helpers.
  */
 export function createSyncFunction<TTable extends Table>(
 	config: BaseSyncConfig<TTable>,
 	backend: SyncBackend<TTable>,
 ): SyncFunctionResult<TTable> {
-	type ItemType = InferSchemaOutput<SelectSchema<TTable>>;
-	type CollectionType = CollectionConfig<
-		ItemType,
-		string,
-		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
-		any
-	>;
-
-	let insertListener: CollectionType["onInsert"];
-	let updateListener: CollectionType["onUpdate"];
-	let deleteListener: CollectionType["onDelete"];
-
-	// Captured sync functions for external sync
-	let syncBegin: (() => void) | null = null;
-	let syncWrite:
-		| ((op: { type: "insert" | "update" | "delete"; value: ItemType }) => void)
-		| null = null;
-	let syncCommit: (() => void) | null = null;
-	let syncTruncate: (() => void) | null = null;
-
-	const syncFn: SyncConfig<
-		InferSchemaOutput<SelectSchema<TTable>>,
-		string
-	>["sync"] = (params) => {
-		const { begin, write, commit, markReady, truncate } = params;
-
-		// Capture sync functions for external use
-		syncBegin = begin;
-		syncWrite = write;
-		syncCommit = commit;
-		syncTruncate = truncate;
-
-		const initialSync = async () => {
-			await config.readyPromise;
-
-			try {
-				const items = await backend.initialLoad();
-
-				begin();
-
-				for (const item of items) {
-					write({
-						type: "insert",
-						value: item,
-					});
-				}
-
-				commit();
-			} finally {
-				markReady();
-			}
-		};
-
-		if (config.syncMode === "eager" || !config.syncMode) {
-			initialSync();
-		} else {
-			markReady();
-		}
-
-		insertListener = async (params) => {
-			const results = await backend.handleInsert(
-				params.transaction.mutations.map((m) => m.modified),
-			);
-
-			begin();
-			for (const result of results) {
-				write({
-					type: "insert",
-					value: result,
-				});
-			}
-			commit();
-		};
-
-		updateListener = async (params) => {
-			const results = await backend.handleUpdate(params.transaction.mutations);
-
-			begin();
-			for (const result of results) {
-				write({
-					type: "update",
-					value: result,
-				});
-			}
-			commit();
-		};
-
-		deleteListener = async (params) => {
-			await backend.handleDelete(params.transaction.mutations);
-
-			begin();
-			for (const item of params.transaction.mutations) {
-				write({
-					type: "delete",
-					value: item.modified,
-				});
-			}
-			commit();
-		};
-
-		const loadSubset = async (options: LoadSubsetOptions) => {
-			await config.readyPromise;
-
-			const items = await backend.loadSubset(options);
-
-			begin();
-
-			for (const item of items) {
-				write({
-					type: "insert",
-					value: item,
-				});
-			}
-
-			commit();
-		};
-
-		// Create deduplicated loadSubset wrapper to avoid redundant queries
-		let loadSubsetDedupe: DeduplicatedLoadSubset | null = null;
-		if (USE_DEDUPE) {
-			loadSubsetDedupe = new DeduplicatedLoadSubset({
-				loadSubset,
-			});
-		}
-
-		return {
-			cleanup: () => {
-				insertListener = undefined;
-				updateListener = undefined;
-				deleteListener = undefined;
-				loadSubsetDedupe?.reset();
-			},
-			loadSubset: loadSubsetDedupe?.loadSubset ?? loadSubset,
-		} satisfies SyncConfigRes;
-	};
-
-	// External sync handler - allows pushing sync events from outside (e.g., proxy server)
-	const pushExternalSync: ExternalSyncHandler<ItemType> = (event) => {
-		if (!syncBegin || !syncWrite || !syncCommit || !syncTruncate) {
-			if (config.debug) {
-				console.warn(
-					"[pushExternalSync] Sync functions not initialized yet - event will be dropped",
-					event,
-				);
-			}
-			return;
-		}
-
-		switch (event.type) {
-			case "insert":
-				syncBegin();
-				for (const item of event.items) {
-					syncWrite({ type: "insert", value: item });
-				}
-				syncCommit();
-				break;
-			case "update":
-				syncBegin();
-				for (const item of event.items) {
-					syncWrite({ type: "update", value: item });
-				}
-				syncCommit();
-				break;
-			case "delete":
-				syncBegin();
-				for (const item of event.items) {
-					syncWrite({ type: "delete", value: item });
-				}
-				syncCommit();
-				break;
-			case "truncate":
-				syncBegin();
-				syncTruncate();
-				syncCommit();
-				break;
-		}
-	};
-
-	// Create utils with truncate and external sync
-	const utils: CollectionUtils<ItemType> = {
-		truncate: async () => {
-			if (!backend.handleTruncate) {
-				throw new Error("Truncate not supported by this backend");
-			}
-			if (!syncBegin || !syncTruncate || !syncCommit) {
-				throw new Error(
-					"Sync functions not initialized - sync function may not have been called yet",
-				);
-			}
-			// Clear the backend store
-			await backend.handleTruncate();
-			// Update local reactive store (same pattern as insert/update/delete listeners)
-			syncBegin();
-			syncTruncate();
-			syncCommit();
-		},
-		pushExternalSync,
-	};
-
-	return {
-		sync: syncFn,
-		onInsert: async (params) => {
-			if (!insertListener) {
-				throw new Error(
-					"insertListener not initialized - sync function may not have been called yet",
-				);
-			}
-			return insertListener(params);
-		},
-		onUpdate: async (params) => {
-			if (!updateListener) {
-				throw new Error(
-					"updateListener not initialized - sync function may not have been called yet",
-				);
-			}
-			return updateListener(params);
-		},
-		onDelete: async (params) => {
-			if (!deleteListener) {
-				throw new Error(
-					"deleteListener not initialized - sync function may not have been called yet",
-				);
-			}
-			return deleteListener(params);
-		},
-		utils,
-	};
+	return createGenericSyncFunction(config, backend);
 }
 
 /**
@@ -562,8 +234,8 @@ export function createGetKeyFunction<TTable extends Table>() {
 }
 
 /**
- * Base collection config factory
- * Combines schema, sync, and event handlers into a collection config
+ * Base collection config factory.
+ * Delegates to the generic (Drizzle-free) implementation in @firtoz/db-helpers.
  */
 export function createCollectionConfig<
 	TTable extends Table,
@@ -603,18 +275,19 @@ export function createCollectionConfig<
 	schema: TSchema;
 	utils: CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>;
 } {
-	return {
-		schema: config.schema,
-		getKey: config.getKey,
-		sync: {
-			sync: config.syncResult.sync,
-		},
-		// Merge provided handlers with sync result handlers (provided handlers take precedence)
-		onInsert: config.onInsert ?? config.syncResult.onInsert,
-		onUpdate: config.onUpdate ?? config.syncResult.onUpdate,
-		onDelete: config.onDelete ?? config.syncResult.onDelete,
-		syncMode: config.syncMode,
-		// Include utils with truncate and pushExternalSync
-		utils: config.syncResult.utils,
+	type TItem = InferSchemaOutput<SelectSchema<TTable>>;
+	type ReturnType = Omit<
+		CollectionConfig<
+			TItem,
+			string,
+			// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
+			any
+		>,
+		"utils"
+	> & {
+		schema: TSchema;
+		utils: CollectionUtils<TItem>;
 	};
+
+	return createGenericCollectionConfig<TItem, TSchema>(config) as ReturnType;
 }

package/src/index.ts

@@ -27,9 +27,6 @@ export type {
 	BaseSyncConfig,
 	SyncBackend,
 	SyncFunctionResult,
-	ExternalSyncEvent,
-	ExternalSyncHandler,
-	CollectionUtils,
 } from "./collection-utils";
 
 export {