@firtoz/drizzle-utils 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @firtoz/drizzle-utils
 
+## 0.3.0
+
+### Minor Changes
+
+- [`46059a2`](https://github.com/firtoz/fullstack-toolkit/commit/46059a28bd0135414b9ed022ffe162a2292adae3) Thanks [@firtoz](https://github.com/firtoz)! - Add external sync support and collection truncate utilities:
+
+  - **`ExternalSyncEvent`** / **`ExternalSyncHandler`** types for receiving sync events from external sources (e.g., proxy server)
+  - **`CollectionUtils`** interface with `truncate()` method for clearing all data from a store
+  - **`handleTruncate`** added to `SyncBackend` interface
+  - **`pushExternalSync`** exposed on `SyncFunctionResult` for pushing external sync events to collections
+  - `createSyncFunction` now returns `utils` with truncate functionality
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # @firtoz/drizzle-utils
 
-Shared utilities and types for Drizzle ORM-based packages. Provides type-safe table builders with automatic timestamp tracking, branded IDs, and common migration types.
+Shared utilities and types for Drizzle ORM-based packages. Provides type-safe table builders with automatic timestamp tracking, branded IDs, common migration types, and collection sync utilities.
 
 > **⚠️ Early WIP Notice:** This package is in very early development and is **not production-ready**. It is TypeScript-only and may have breaking changes. While I (the maintainer) have limited time, I'm open to PRs for features, bug fixes, or additional support (like JS builds). Please feel free to try it out and contribute! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.
 
@@ -203,6 +203,64 @@ Comprehensive types for database migrations:
 - `ViewDefinition` - Database view definition
 - `EnumDefinition` - Enum type definition
 
+### Collection Sync Utilities
+
+Support for external sync and collection utilities:
+
+#### External Sync Events
+
+Push sync events from external sources (e.g., proxy servers) to collections:
+
+```typescript
+import type { ExternalSyncEvent, ExternalSyncHandler } from "@firtoz/drizzle-utils";
+
+// Receive sync events from a server
+const handleSync: ExternalSyncHandler<Todo> = (event) => {
+  switch (event.type) {
+    case "insert":
+      // event.items contains new items
+      break;
+    case "update":
+      // event.items contains updated items
+      break;
+    case "delete":
+      // event.items contains deleted items
+      break;
+    case "truncate":
+      // All items should be cleared
+      break;
+  }
+};
+
+// Push events to a collection's reactive store
+syncResult.pushExternalSync({ type: "insert", items: [newTodo] });
+syncResult.pushExternalSync({ type: "truncate" });
+```
+
+#### Collection Utils
+
+The `SyncFunctionResult` includes utilities for common operations:
+
+```typescript
+// Truncate (clear all data)
+await collection.utils.truncate();
+```
+
+#### SyncBackend Interface
+
+For implementing custom backends, the `SyncBackend` interface includes:
+
+```typescript
+interface SyncBackend<TTable> {
+  initialLoad: (write) => Promise<void>;
+  loadSubset: (options, write) => Promise<void>;
+  handleInsert: (mutations) => Promise<T[]>;
+  handleUpdate: (mutations) => Promise<T[]>;
+  handleDelete: (mutations) => Promise<void>;
+  handleTruncate?: () => Promise<void>; // Optional truncate support
+}
+```
+
 ## Best Practices
 
 ### 1. Use syncableTable for Data Tables

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/drizzle-utils",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Shared utilities and types for Drizzle-based packages",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -55,15 +55,15 @@
 		"access": "public"
 	},
 	"peerDependencies": {
-		"@tanstack/db": "^0.5.0",
+		"@tanstack/db": "^0.5.10",
 		"drizzle-orm": "^0.44.7",
 		"drizzle-valibot": "^0.4.2",
-		"valibot": "^1.0.0"
+		"valibot": "^1.2.0"
 	},
 	"devDependencies": {
-		"@tanstack/db": "^0.5.0",
+		"@tanstack/db": "^0.5.10",
 		"drizzle-orm": "^0.44.7",
 		"drizzle-valibot": "^0.4.2",
-		"valibot": "^1.0.0"
+		"valibot": "^1.2.0"
 	}
 }

package/src/collection-utils.ts

@@ -160,6 +160,41 @@ export interface SyncBackend<TTable extends Table> {
 			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)
+ */
+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>;
 }
 
 /**
@@ -185,6 +220,10 @@ export type SyncFunctionResult<TTable extends Table> = {
 		// 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>>>;
 };
 
 /**
@@ -194,8 +233,9 @@ export function createSyncFunction<TTable extends Table>(
 	config: BaseSyncConfig<TTable>,
 	backend: SyncBackend<TTable>,
 ): SyncFunctionResult<TTable> {
+	type ItemType = InferSchemaOutput<SelectSchema<TTable>>;
 	type CollectionType = CollectionConfig<
-		InferSchemaOutput<SelectSchema<TTable>>,
+		ItemType,
 		string,
 		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
 		any
@@ -205,11 +245,25 @@ export function createSyncFunction<TTable extends Table>(
 	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 } = 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;
@@ -315,6 +369,69 @@ 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) => {
+		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) => {
@@ -341,6 +458,7 @@ export function createSyncFunction<TTable extends Table>(
 			}
 			return deleteListener(params);
 		},
+		utils,
 	};
 }
 
@@ -478,13 +596,17 @@ export function createCollectionConfig<
 		any
 	>["onDelete"];
 	syncMode?: SyncMode;
-}): CollectionConfig<
-	InferSchemaOutput<SelectSchema<TTable>>,
-	string,
-	// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
-	any
+}): Omit<
+	CollectionConfig<
+		InferSchemaOutput<SelectSchema<TTable>>,
+		string,
+		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
+		any
+	>,
+	"utils"
 > & {
 	schema: TSchema;
+	utils: CollectionUtils<InferSchemaOutput<SelectSchema<TTable>>>;
 } {
 	return {
 		schema: config.schema,
@@ -497,12 +619,7 @@ export function createCollectionConfig<
 		onUpdate: config.onUpdate ?? config.syncResult.onUpdate,
 		onDelete: config.onDelete ?? config.syncResult.onDelete,
 		syncMode: config.syncMode,
-	} as CollectionConfig<
-		InferSchemaOutput<SelectSchema<TTable>>,
-		string,
-		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
-		any
-	> & {
-		schema: TSchema;
+		// Include utils with truncate and pushExternalSync
+		utils: config.syncResult.utils,
 	};
 }

package/src/index.ts

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