@firtoz/drizzle-utils 0.3.3 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @firtoz/drizzle-utils
 
+## 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.0",
 	"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.26",
 		"drizzle-orm": ">=0.45.1",
 		"drizzle-valibot": ">=0.4.0",
 		"valibot": ">=1.0.0"
 	},
 	"devDependencies": {
-		"@tanstack/db": "^0.5.25",
+		"@tanstack/db": "^0.5.26",
 		"drizzle-orm": "^0.45.1",
 		"drizzle-valibot": "^0.4.2",
 		"valibot": "^1.2.0"
+	},
+	"dependencies": {
+		"@firtoz/db-helpers": "^1.0.0",
+		"@firtoz/maybe-error": "^1.5.2"
 	}
 }

package/src/collection-utils.ts

@@ -1,3 +1,5 @@
+import type { CollectionUtils, SyncMessage } from "@firtoz/db-helpers";
+import { exhaustiveGuard } from "@firtoz/maybe-error";
 import { type Table, SQL, getTableColumns } from "drizzle-orm";
 import type { BuildSchema } from "drizzle-valibot";
 import { createInsertSchema } from "drizzle-valibot";
@@ -162,36 +164,6 @@ export interface SyncBackend<TTable extends Table> {
 	handleTruncate?: () => Promise<void>;
 }
 
-/**
- * External sync event for pushing changes from outside (e.g., from a proxy server)
- */
-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;
-
-/**
- * Collection utils that include truncate and external sync functionality
- */
-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>;
-}
-
 /**
  * Return type for createSyncFunction that includes both sync config and listeners
  */
@@ -364,49 +336,44 @@ export function createSyncFunction<TTable extends Table>(
 		} satisfies SyncConfigRes;
 	};
 
-	// External sync handler - allows pushing sync events from outside (e.g., proxy server)
-	const pushExternalSync: ExternalSyncHandler<ItemType> = (event) => {
+	// Apply SyncMessage[] to the sync layer (canonical receive API)
+	const receiveSync = async (messages: SyncMessage<ItemType>[]) => {
+		if (messages.length === 0) return;
 		if (!syncBegin || !syncWrite || !syncCommit || !syncTruncate) {
 			if (config.debug) {
 				console.warn(
-					"[pushExternalSync] Sync functions not initialized yet - event will be dropped",
-					event,
+					"[receiveSync] Sync functions not initialized yet - messages will be dropped",
+					messages.length,
 				);
 			}
 			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;
+		syncBegin();
+		for (const msg of messages) {
+			switch (msg.type) {
+				case "insert":
+					syncWrite({ type: "insert", value: msg.value });
+					break;
+				case "update":
+					syncWrite({ type: "update", value: msg.value });
+					break;
+				case "delete":
+					syncWrite({
+						type: "delete",
+						value: { id: msg.key } as ItemType,
+					});
+					break;
+				case "truncate":
+					syncTruncate();
+					break;
+				default:
+					exhaustiveGuard(msg);
+			}
 		}
+		syncCommit();
 	};
 
-	// Create utils with truncate and external sync
+	// Create utils with truncate and receiveSync
 	const utils: CollectionUtils<ItemType> = {
 		truncate: async () => {
 			if (!backend.handleTruncate) {
@@ -424,7 +391,7 @@ export function createSyncFunction<TTable extends Table>(
 			syncTruncate();
 			syncCommit();
 		},
-		pushExternalSync,
+		receiveSync,
 	};
 
 	return {
@@ -614,7 +581,7 @@ export function createCollectionConfig<
 		onUpdate: config.onUpdate ?? config.syncResult.onUpdate,
 		onDelete: config.onDelete ?? config.syncResult.onDelete,
 		syncMode: config.syncMode,
-		// Include utils with truncate and pushExternalSync
+		// Include utils with truncate and receiveSync
 		utils: config.syncResult.utils,
 	};
 }

package/src/index.ts

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