@firtoz/db-helpers 1.0.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/db-helpers",
-	"version": "1.0.0",
+	"version": "2.0.0",
 	"description": "TanStack DB helpers and utilities",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -19,6 +19,7 @@
 	],
 	"scripts": {
 		"typecheck": "tsc --noEmit -p ./tsconfig.json",
+		"test": "bun test",
 		"lint": "biome check --write src",
 		"lint:ci": "biome ci src",
 		"format": "biome format src --write"
@@ -48,11 +49,13 @@
 	},
 	"peerDependencies": {
 		"@standard-schema/spec": ">=1.1.0",
-		"@tanstack/db": ">=0.5.26"
+		"@tanstack/db": ">=0.5.33"
 	},
 	"devDependencies": {
 		"@standard-schema/spec": "^1.1.0",
-		"@tanstack/db": "^0.5.26"
+		"@tanstack/db": "^0.5.33",
+		"bun-types": "^1.3.10",
+		"zod": "^4.3.6"
 	},
 	"dependencies": {
 		"@firtoz/maybe-error": "^1.5.2"

package/src/generic-sync.ts

@@ -0,0 +1,357 @@
+import type { CollectionUtils, SyncMessage } from "./sync-types";
+import { exhaustiveGuard } from "@firtoz/maybe-error";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type {
+	CollectionConfig,
+	InferSchemaOutput,
+	SyncConfig,
+	SyncConfigRes,
+	SyncMode,
+	LoadSubsetOptions,
+} from "@tanstack/db";
+import { DeduplicatedLoadSubset } from "@tanstack/db";
+
+// 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;
+
+/**
+ * Base configuration for sync lifecycle management (generic, no Drizzle dependency).
+ */
+export interface GenericBaseSyncConfig {
+	readyPromise: Promise<void>;
+	syncMode?: SyncMode;
+	debug?: boolean;
+}
+
+/**
+ * Backend-specific implementations required for sync (generic, no Drizzle dependency).
+ */
+export interface GenericSyncBackend<TItem extends object> {
+	initialLoad: () => Promise<Array<TItem>>;
+	loadSubset: (options: LoadSubsetOptions) => Promise<Array<TItem>>;
+	handleInsert: (items: Array<TItem>) => Promise<Array<TItem>>;
+	handleUpdate: (
+		mutations: Array<{
+			key: string;
+			changes: Partial<TItem>;
+			original: TItem;
+		}>,
+	) => Promise<Array<TItem>>;
+	handleDelete: (
+		mutations: Array<{
+			key: string;
+			modified: TItem;
+			original: TItem;
+		}>,
+	) => Promise<void>;
+	handleTruncate?: () => Promise<void>;
+}
+
+/**
+ * Return type for createGenericSyncFunction.
+ */
+export type GenericSyncFunctionResult<TItem extends object> = {
+	sync: SyncConfig<TItem, string>["sync"];
+	onInsert: CollectionConfig<
+		TItem,
+		string,
+		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
+		any
+	>["onInsert"];
+	onUpdate: CollectionConfig<
+		TItem,
+		string,
+		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
+		any
+	>["onUpdate"];
+	onDelete: CollectionConfig<
+		TItem,
+		string,
+		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
+		any
+	>["onDelete"];
+	utils: CollectionUtils<TItem>;
+};
+
+/**
+ * Creates the sync function with common lifecycle management.
+ * Generic version -- no Drizzle dependency.
+ */
+export function createGenericSyncFunction<TItem extends object>(
+	config: GenericBaseSyncConfig,
+	backend: GenericSyncBackend<TItem>,
+): GenericSyncFunctionResult<TItem> {
+	type CollectionType = CollectionConfig<
+		TItem,
+		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"];
+
+	let syncBegin: (() => void) | null = null;
+	let syncWrite:
+		| ((op: { type: "insert" | "update" | "delete"; value: TItem }) => void)
+		| null = null;
+	let syncCommit: (() => void) | null = null;
+	let syncTruncate: (() => void) | null = null;
+
+	const syncFn: SyncConfig<TItem, string>["sync"] = (params) => {
+		const { begin, write, commit, markReady, truncate } = params;
+
+		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();
+		};
+
+		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;
+	};
+
+	const receiveSync = async (messages: SyncMessage<TItem>[]) => {
+		if (messages.length === 0) return;
+		if (!syncBegin || !syncWrite || !syncCommit || !syncTruncate) {
+			if (config.debug) {
+				console.warn(
+					"[receiveSync] Sync functions not initialized yet - messages will be dropped",
+					messages.length,
+				);
+			}
+			return;
+		}
+		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 TItem,
+					});
+					break;
+				case "truncate":
+					syncTruncate();
+					break;
+				default:
+					exhaustiveGuard(msg);
+			}
+		}
+		syncCommit();
+	};
+
+	const utils: CollectionUtils<TItem> = {
+		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",
+				);
+			}
+			await backend.handleTruncate();
+			syncBegin();
+			syncTruncate();
+			syncCommit();
+		},
+		receiveSync,
+	};
+
+	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,
+	};
+}
+
+/**
+ * Generic collection config factory.
+ * Combines schema, sync, and event handlers into a collection config.
+ * No Drizzle dependency -- uses StandardSchemaV1 directly.
+ */
+export function createGenericCollectionConfig<
+	TItem extends object,
+	TSchema extends StandardSchemaV1,
+>(config: {
+	schema: TSchema;
+	getKey: (item: TItem) => string;
+	syncResult: GenericSyncFunctionResult<TItem>;
+	onInsert?: CollectionConfig<
+		TItem,
+		string,
+		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
+		any
+	>["onInsert"];
+	onUpdate?: CollectionConfig<
+		TItem,
+		string,
+		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
+		any
+	>["onUpdate"];
+	onDelete?: CollectionConfig<
+		TItem,
+		string,
+		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
+		any
+	>["onDelete"];
+	syncMode?: SyncMode;
+}): Omit<
+	CollectionConfig<
+		TItem,
+		string,
+		// biome-ignore lint/suspicious/noExplicitAny: Schema type parameter needs to be flexible
+		any
+	>,
+	"utils"
+> & {
+	schema: TSchema;
+	utils: CollectionUtils<InferSchemaOutput<TSchema>>;
+} {
+	return {
+		schema: config.schema,
+		getKey: config.getKey,
+		sync: {
+			sync: config.syncResult.sync,
+		},
+		onInsert: config.onInsert ?? config.syncResult.onInsert,
+		onUpdate: config.onUpdate ?? config.syncResult.onUpdate,
+		onDelete: config.onDelete ?? config.syncResult.onDelete,
+		syncMode: config.syncMode,
+		utils: config.syncResult.utils as CollectionUtils<
+			InferSchemaOutput<TSchema>
+		>,
+	};
+}

package/src/index.ts

@@ -9,3 +9,14 @@ export {
 	memoryCollectionOptions,
 	type MemoryCollection,
 } from "./memoryCollection";
+
+export { evaluateExpression, getExpressionValue } from "./ir-evaluator";
+
+export {
+	USE_DEDUPE,
+	createGenericSyncFunction,
+	createGenericCollectionConfig,
+	type GenericBaseSyncConfig,
+	type GenericSyncBackend,
+	type GenericSyncFunctionResult,
+} from "./generic-sync";

package/src/ir-evaluator.ts

@@ -0,0 +1,136 @@
+import type { IR } from "@tanstack/db";
+
+/**
+ * Evaluates a TanStack DB IR expression against a plain object item.
+ * @internal Exported for testing and reuse by collection backends
+ */
+export function evaluateExpression(
+	expression: IR.BasicExpression,
+	item: Record<string, unknown>,
+): boolean {
+	switch (expression.type) {
+		case "ref": {
+			const propRef = expression;
+			const columnName = propRef.path[propRef.path.length - 1];
+			return item[columnName as string] !== undefined;
+		}
+		case "val": {
+			const value = expression;
+			return !!value.value;
+		}
+		case "func": {
+			const func = expression;
+
+			switch (func.name) {
+				case "eq": {
+					const left = getExpressionValue(func.args[0], item);
+					const right = getExpressionValue(func.args[1], item);
+					return left === right;
+				}
+				case "ne": {
+					const left = getExpressionValue(func.args[0], item);
+					const right = getExpressionValue(func.args[1], item);
+					return left !== right;
+				}
+				case "gt": {
+					const left = getExpressionValue(func.args[0], item);
+					const right = getExpressionValue(func.args[1], item);
+					return left > right;
+				}
+				case "gte": {
+					const left = getExpressionValue(func.args[0], item);
+					const right = getExpressionValue(func.args[1], item);
+					return left >= right;
+				}
+				case "lt": {
+					const left = getExpressionValue(func.args[0], item);
+					const right = getExpressionValue(func.args[1], item);
+					return left < right;
+				}
+				case "lte": {
+					const left = getExpressionValue(func.args[0], item);
+					const right = getExpressionValue(func.args[1], item);
+					return left <= right;
+				}
+				case "and": {
+					return func.args.every((arg) => evaluateExpression(arg, item));
+				}
+				case "or": {
+					return func.args.some((arg) => evaluateExpression(arg, item));
+				}
+				case "not": {
+					return !evaluateExpression(func.args[0], item);
+				}
+				case "isNull": {
+					const value = getExpressionValue(func.args[0], item);
+					return value === null || value === undefined;
+				}
+				case "isNotNull": {
+					const value = getExpressionValue(func.args[0], item);
+					return value !== null && value !== undefined;
+				}
+				case "like": {
+					const left = String(getExpressionValue(func.args[0], item));
+					const right = String(getExpressionValue(func.args[1], item));
+					const pattern = right.replace(/%/g, ".*").replace(/_/g, ".");
+					return new RegExp(`^${pattern}$`).test(left);
+				}
+				case "ilike": {
+					const left = String(getExpressionValue(func.args[0], item));
+					const right = String(getExpressionValue(func.args[1], item));
+					const pattern = right.replace(/%/g, ".*").replace(/_/g, ".");
+					return new RegExp(`^${pattern}$`, "i").test(left);
+				}
+				case "in": {
+					const left = getExpressionValue(func.args[0], item);
+					const right = getExpressionValue(func.args[1], item);
+					return Array.isArray(right) && right.includes(left);
+				}
+				case "isUndefined": {
+					const value = getExpressionValue(func.args[0], item);
+					return value === null || value === undefined;
+				}
+				default:
+					throw new Error(`Unsupported function: ${func.name}`);
+			}
+		}
+		default: {
+			const _ex: never = expression;
+			void _ex;
+			throw new Error(
+				`Unsupported expression type: ${(expression as { type: string }).type}`,
+			);
+		}
+	}
+}
+
+/**
+ * Gets the value from an IR expression by resolving refs and vals.
+ * @internal Exported for testing and reuse by collection backends
+ */
+export function getExpressionValue(
+	expression: IR.BasicExpression,
+	item: Record<string, unknown>,
+	// biome-ignore lint/suspicious/noExplicitAny: We need any here for dynamic values
+): any {
+	switch (expression.type) {
+		case "ref": {
+			const propRef = expression;
+			const columnName = propRef.path[propRef.path.length - 1];
+			return item[columnName as string];
+		}
+		case "val": {
+			const value = expression;
+			return value.value;
+		}
+		case "func":
+			throw new Error("Cannot get value from func expression");
+		default: {
+			const _ex: never = expression;
+			void _ex;
+			throw new Error(
+				`Cannot get value from expression type: ${(expression as { type: string }).type}`,
+			);
+		}
+	}
+}