@firtoz/db-helpers 0.1.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/db-helpers",
-	"version": "0.1.0",
+	"version": "1.0.0",
 	"description": "TanStack DB helpers and utilities",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -48,10 +48,13 @@
 	},
 	"peerDependencies": {
 		"@standard-schema/spec": ">=1.1.0",
-		"@tanstack/db": ">=0.5.25"
+		"@tanstack/db": ">=0.5.26"
 	},
 	"devDependencies": {
 		"@standard-schema/spec": "^1.1.0",
-		"@tanstack/db": "^0.5.25"
+		"@tanstack/db": "^0.5.26"
+	},
+	"dependencies": {
+		"@firtoz/maybe-error": "^1.5.2"
 	}
 }

package/src/index.ts

@@ -1,3 +1,9 @@
+export type {
+	CollectionUtils,
+	ExternalSyncEvent,
+	ExternalSyncHandler,
+	SyncMessage,
+} from "./sync-types";
 export {
 	createMemoryCollection,
 	memoryCollectionOptions,

package/src/memoryCollection.ts

@@ -1,3 +1,5 @@
+import type { SyncMessage } from "./sync-types";
+import { exhaustiveGuard } from "@firtoz/maybe-error";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import {
 	type Collection,
@@ -16,72 +18,100 @@ type MemoryCollectionConfig<TSchema extends StandardSchemaV1> = Omit<
 	"onInsert" | "onUpdate" | "onDelete" | "sync" | "schema"
 > & {
 	schema: TSchema;
+	/** Called when a local mutation is written to the sync layer; use to broadcast to other peers. */
+	onBroadcast?: (
+		changes: SyncMessage<InferSchemaOutput<TSchema>, string | number>[],
+	) => void;
 };
 
-type MemoryUtils = {
+type MemoryUtils<
+	TItem = unknown,
+	TKey extends string | number = string | number,
+> = {
 	truncate: () => Promise<void>;
+	/**
+	 * Apply incoming sync messages without triggering onInsert/onUpdate/onDelete.
+	 * Uses the sync layer (begin/write/commit) so state updates and subscribeChanges fire,
+	 * but no rebroadcast occurs.
+	 */
+	receiveSync: (messages: SyncMessage<TItem, TKey>[]) => Promise<void>;
 };
 
 export function memoryCollectionOptions<TSchema extends StandardSchemaV1>(
 	config: MemoryCollectionConfig<TSchema>,
 ): CollectionConfig<InferSchemaOutput<TSchema>, string | number, TSchema> & {
-	utils: MemoryUtils;
+	utils: MemoryUtils<InferSchemaOutput<TSchema>, string | number>;
 	schema: TSchema;
 } {
 	type TItem = InferSchemaOutput<TSchema>;
+	type TKey = string | number;
 	let syncParams: Parameters<SyncConfig<TItem>["sync"]>[0] | null = null;
 
 	const sync: SyncConfig<TItem>["sync"] = (params) => {
 		syncParams = params;
-
 		params.markReady();
-
-		// Return cleanup function
 		return () => {};
 	};
 
-	// All mutation handlers use the same transaction sender
-	const onInsert = async (params: InsertMutationFnParams<TItem>) => {
+	const writeChanges = (writes: SyncMessage<TItem, TKey>[]) => {
 		if (!syncParams) {
 			throw new Error("Sync parameters not initialized");
 		}
 		syncParams.begin();
-		for (const mutation of params.transaction.mutations) {
-			syncParams.write({
-				type: "insert",
-				value: mutation.modified,
-			});
+		for (const msg of writes) {
+			switch (msg.type) {
+				case "insert":
+					syncParams.write({ type: "insert", value: msg.value });
+					break;
+				case "update":
+					syncParams.write({
+						type: "update",
+						value: msg.value,
+						previousValue: msg.previousValue,
+					});
+					break;
+				case "delete":
+					syncParams.write({ type: "delete", key: msg.key });
+					break;
+				case "truncate":
+					syncParams.truncate();
+					break;
+				default:
+					exhaustiveGuard(msg);
+			}
 		}
 		syncParams.commit();
 	};
 
-	const onUpdate = async (params: UpdateMutationFnParams<TItem>) => {
-		if (!syncParams) {
-			throw new Error("Sync parameters not initialized");
+	const onInsert = async (params: InsertMutationFnParams<TItem>) => {
+		const writes: SyncMessage<TItem, TKey>[] = [];
+		for (const mutation of params.transaction.mutations) {
+			writes.push({ type: "insert", value: mutation.modified });
 		}
-		syncParams.begin();
+		writeChanges(writes);
+		config.onBroadcast?.(writes);
+	};
+
+	const onUpdate = async (params: UpdateMutationFnParams<TItem>) => {
+		const writes: SyncMessage<TItem, TKey>[] = [];
 		for (const mutation of params.transaction.mutations) {
-			syncParams.write({
+			writes.push({
 				type: "update",
 				value: mutation.modified,
 				previousValue: mutation.original,
 			});
 		}
-		syncParams.commit();
+		writeChanges(writes);
+		config.onBroadcast?.(writes);
 	};
 
 	const onDelete = async (params: DeleteMutationFnParams<TItem>) => {
-		if (!syncParams) {
-			throw new Error("Sync parameters not initialized");
-		}
-		syncParams.begin();
+		const writes: SyncMessage<TItem, TKey>[] = [];
 		for (const mutation of params.transaction.mutations) {
-			syncParams.write({
-				type: "delete",
-				key: mutation.key,
-			});
+			writes.push({ type: "delete", key: mutation.key as TKey });
 		}
-		syncParams?.commit();
+		writeChanges(writes);
+		config.onBroadcast?.(writes);
 	};
 
 	const truncate = async () => {
@@ -93,6 +123,11 @@ export function memoryCollectionOptions<TSchema extends StandardSchemaV1>(
 		syncParams.commit();
 	};
 
+	const receiveSync = async (messages: SyncMessage<TItem, TKey>[]) => {
+		if (messages.length === 0) return;
+		writeChanges(messages);
+	};
+
 	return {
 		id: config.id,
 		schema: config.schema,
@@ -103,6 +138,7 @@ export function memoryCollectionOptions<TSchema extends StandardSchemaV1>(
 		onDelete,
 		utils: {
 			truncate,
+			receiveSync,
 		},
 	};
 }
@@ -110,7 +146,7 @@ export function memoryCollectionOptions<TSchema extends StandardSchemaV1>(
 export type MemoryCollection<TSchema extends StandardSchemaV1> = Collection<
 	InferSchemaOutput<TSchema>,
 	string | number,
-	MemoryUtils,
+	MemoryUtils<InferSchemaOutput<TSchema>, string | number>,
 	TSchema,
 	InferSchemaInput<TSchema>
 >;

package/src/sync-types.ts

@@ -0,0 +1,46 @@
+/**
+ * Generic collection sync types. Used by memory, IndexedDB, SQLite, and other
+ * collection backends for a unified sync protocol.
+ */
+
+/**
+ * Canonical per-mutation sync message. Use for broadcast and receive across all collection types.
+ */
+export type SyncMessage<
+	T = unknown,
+	TKey extends string | number = string | number,
+> =
+	| { type: "insert"; value: T }
+	| { type: "update"; value: T; previousValue: T }
+	| { type: "delete"; key: TKey }
+	| { type: "truncate" };
+
+/**
+ * External sync event (batched). Used internally by the sync layer.
+ */
+export type ExternalSyncEvent<T> =
+	| { type: "insert"; items: T[] }
+	| { type: "update"; items: T[] }
+	| { type: "delete"; items: T[] }
+	| { type: "truncate" };
+
+/**
+ * Handler for external sync events (internal use).
+ */
+export type ExternalSyncHandler<T> = (event: ExternalSyncEvent<T>) => void;
+
+/**
+ * Collection utils: truncate and receiveSync (canonical sync protocol).
+ */
+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>;
+	/**
+	 * Apply incoming sync messages without triggering mutation handlers.
+	 * Use the same SyncMessage[] shape for memory and backend collections.
+	 */
+	receiveSync: (messages: SyncMessage<T>[]) => Promise<void>;
+}