@firtoz/collection-sync 1.0.0

package/src/partial-sync-interest.ts

@@ -0,0 +1,200 @@
+import type { SyncMessage } from "@firtoz/db-helpers";
+import { exhaustiveGuard } from "@firtoz/maybe-error";
+import type { RangeCondition } from "./sync-protocol";
+import type { PartialSyncRowShape } from "./partial-sync-row-key";
+import { partialSyncRowKey } from "./partial-sync-row-key";
+import { matchesPredicate } from "./partial-sync-predicate-match";
+
+/** Metadata on `rangePatch` when an update crosses client interest boundaries. */
+export type PartialSyncViewTransition = "enterView" | "exitView";
+
+export type PartialSyncPatchResult<TItem extends PartialSyncRowShape> = {
+	change: SyncMessage<TItem>;
+	viewTransition?: PartialSyncViewTransition;
+};
+
+/** Tracked 1D sort interval delivered to a client (index / cursor queries). */
+export type DeliveredRange = {
+	sortColumn: string;
+	sortDirection: "asc" | "desc";
+	fromValue: unknown;
+	toValue: unknown;
+};
+
+export function compareInterestValues(left: unknown, right: unknown): number {
+	const leftValue = left instanceof Date ? left.getTime() : left;
+	const rightValue = right instanceof Date ? right.getTime() : right;
+	if (typeof leftValue === "number" && typeof rightValue === "number") {
+		return leftValue === rightValue ? 0 : leftValue < rightValue ? -1 : 1;
+	}
+	const leftString = String(leftValue);
+	const rightString = String(rightValue);
+	return leftString.localeCompare(rightString);
+}
+
+export function sortValueWithinDeliveredRange(
+	value: unknown,
+	range: DeliveredRange,
+): boolean {
+	if (value === undefined || value === null) return false;
+	const compareFrom = compareInterestValues(value, range.fromValue);
+	const compareTo = compareInterestValues(value, range.toValue);
+	if (range.sortDirection === "asc") {
+		return compareFrom >= 0 && compareTo <= 0;
+	}
+	return compareFrom <= 0 && compareTo >= 0;
+}
+
+export function rowMatchesDeliveredSortRanges<TItem>(
+	ranges: DeliveredRange[],
+	row: TItem,
+	getSortValue: (row: TItem, column: string) => unknown,
+): boolean {
+	if (ranges.length === 0) return false;
+	return ranges.some((range) => {
+		const sortValue = getSortValue(row, range.sortColumn);
+		return sortValueWithinDeliveredRange(sortValue, range);
+	});
+}
+
+export function rowMatchesPredicateGroups<TItem>(
+	predicateGroups: RangeCondition[][],
+	row: TItem,
+	getColumnValue: (row: TItem, column: string) => unknown,
+): boolean {
+	if (predicateGroups.length === 0) return false;
+	return predicateGroups.some((group) =>
+		matchesPredicate(row, group, getColumnValue),
+	);
+}
+
+export function rowMatchesClientInterest<TItem>(
+	sortRanges: DeliveredRange[],
+	predicateGroups: RangeCondition[][],
+	row: TItem,
+	getSortValue: (row: TItem, column: string) => unknown,
+	getColumnValue: (row: TItem, column: string) => unknown,
+): boolean {
+	/** Predicate viewport wins over 1D sort windows so chunk sort keys do not widen visibility. */
+	if (predicateGroups.length > 0) {
+		return rowMatchesPredicateGroups(predicateGroups, row, getColumnValue);
+	}
+	if (sortRanges.length > 0) {
+		return rowMatchesDeliveredSortRanges(sortRanges, row, getSortValue);
+	}
+	return false;
+}
+
+export type ClassifyPartialSyncRangePatchOptions = {
+	/**
+	 * When set, `delete` is only forwarded if the key was previously delivered to this client
+	 * (viewport-scoped deletes). When omitted, `delete` is always forwarded (legacy behavior).
+	 */
+	deliveredRowIds?: ReadonlySet<string> | undefined;
+};
+
+/**
+ * Maps a server-side change to a `rangePatch` payload, or `null` if this client should not
+ * receive a patch. View enter/exit keeps the real `update` on the wire so clients can cache
+ * rows and filter locally instead of fake delete/insert.
+ */
+export function classifyPartialSyncRangePatch<
+	TItem extends PartialSyncRowShape,
+>(
+	sortRanges: DeliveredRange[],
+	predicateGroups: RangeCondition[][],
+	change: SyncMessage<TItem>,
+	getSortValue: (row: TItem, column: string) => unknown,
+	getColumnValue: (row: TItem, column: string) => unknown,
+	options?: ClassifyPartialSyncRangePatchOptions,
+): PartialSyncPatchResult<TItem> | null {
+	const deliveredIds = options?.deliveredRowIds;
+	if (change.type === "delete" && deliveredIds !== undefined) {
+		return deliveredIds.has(String(partialSyncRowKey(change.key)))
+			? { change }
+			: null;
+	}
+
+	const hasInterest = sortRanges.length > 0 || predicateGroups.length > 0;
+	if (!hasInterest) return null;
+
+	if (change.type === "truncate") return { change };
+	if (change.type === "delete") return { change };
+
+	if (change.type === "insert") {
+		return rowMatchesClientInterest(
+			sortRanges,
+			predicateGroups,
+			change.value,
+			getSortValue,
+			getColumnValue,
+		)
+			? { change }
+			: null;
+	}
+
+	if (change.type === "update") {
+		const newIn = rowMatchesClientInterest(
+			sortRanges,
+			predicateGroups,
+			change.value,
+			getSortValue,
+			getColumnValue,
+		);
+		const oldIn =
+			change.previousValue !== undefined
+				? rowMatchesClientInterest(
+						sortRanges,
+						predicateGroups,
+						change.previousValue,
+						getSortValue,
+						getColumnValue,
+					)
+				: false;
+		if (newIn && oldIn) return { change };
+		if (newIn && !oldIn) return { change, viewTransition: "enterView" };
+		if (!newIn && oldIn) return { change, viewTransition: "exitView" };
+		return null;
+	}
+
+	exhaustiveGuard(change);
+}
+
+/**
+ * Filters sync messages to those relevant to a single predicate range (viewport). Used for
+ * `rangeDelta` so clients never receive changelog rows outside their requested conditions.
+ *
+ * - `insert` / `update` / `truncate`: uses {@link classifyPartialSyncRangePatch} with only this
+ *   predicate group (no sort ranges).
+ * - `delete`: passed through unchanged — callers should filter deletes in the store when the
+ *   deleted row snapshot is available (e.g. changelog payload).
+ */
+export function filterSyncMessagesForPredicateRange<
+	TItem extends PartialSyncRowShape,
+>(
+	conditions: RangeCondition[],
+	changes: SyncMessage<TItem>[],
+	getSortValue: (row: TItem, column: string) => unknown,
+	getColumnValue: (row: TItem, column: string) => unknown,
+): SyncMessage<TItem>[] {
+	const predicateGroups: RangeCondition[][] = [conditions];
+	const sortRanges: DeliveredRange[] = [];
+	const out: SyncMessage<TItem>[] = [];
+	for (const change of changes) {
+		if (change.type === "delete") {
+			out.push(change);
+			continue;
+		}
+		const patch = classifyPartialSyncRangePatch(
+			sortRanges,
+			predicateGroups,
+			change,
+			getSortValue,
+			getColumnValue,
+		);
+		if (patch !== null) {
+			out.push(patch.change);
+		}
+	}
+	return out;
+}

package/src/partial-sync-mutation-handler.ts

@@ -0,0 +1,152 @@
+import type { SyncMessage } from "@firtoz/db-helpers";
+import { exhaustiveGuard } from "@firtoz/maybe-error";
+import type { PartialSyncServerBridge } from "./partial-sync-server-bridge";
+import {
+	partialSyncRowKey,
+	type PartialSyncRowShape,
+} from "./partial-sync-row-key";
+import type {
+	MutationIntent,
+	SyncClientMessage,
+	SyncServerMessage,
+	SyncServerMessageBody,
+} from "./sync-protocol";
+import { DEFAULT_SYNC_COLLECTION_ID, toSyncMessage } from "./sync-protocol";
+
+export interface PartialSyncMutationHandlerStore<
+	TItem extends PartialSyncRowShape,
+> {
+	applySyncMessages: (messages: SyncMessage<TItem>[]) => Promise<void>;
+	getRow: (key: string | number) => Promise<TItem | undefined>;
+}
+
+export interface PartialSyncMutationHandlerOptions<
+	TItem extends PartialSyncRowShape,
+> {
+	store: PartialSyncMutationHandlerStore<TItem>;
+	partialBridge: Pick<PartialSyncServerBridge<TItem>, "pushServerChanges">;
+	sendToClient: (clientId: string, message: SyncServerMessage<TItem>) => void;
+	collectionId?: string;
+}
+
+function toMillis(value: number | Date | null | undefined): number {
+	if (typeof value === "number") return value;
+	if (value instanceof Date) return value.getTime();
+	return 0;
+}
+
+/**
+ * Partial-sync durable object mutation path: `mutateBatch` → `ack` / `reject` + interest-scoped
+ * `rangePatch` via {@link PartialSyncServerBridge.pushServerChanges}. No `serverVersion`, changelog,
+ * or `syncBatch` broadcast.
+ */
+export class PartialSyncMutationHandler<TItem extends PartialSyncRowShape> {
+	readonly #cid: string;
+
+	constructor(
+		private readonly options: PartialSyncMutationHandlerOptions<TItem>,
+	) {
+		this.#cid = options.collectionId ?? DEFAULT_SYNC_COLLECTION_ID;
+	}
+
+	get collectionId(): string {
+		return this.#cid;
+	}
+
+	#emit(clientId: string, body: SyncServerMessageBody<TItem>): void {
+		this.options.sendToClient(clientId, {
+			...body,
+			collectionId: this.#cid,
+		} as SyncServerMessage<TItem>);
+	}
+
+	async handleClientMessage(message: SyncClientMessage): Promise<void> {
+		const mid = message.collectionId ?? DEFAULT_SYNC_COLLECTION_ID;
+		if (mid !== this.#cid) return;
+		switch (message.type) {
+			case "ping":
+				this.#emit(message.clientId, {
+					type: "pong",
+					timestamp: message.timestamp,
+				});
+				return;
+			case "mutateBatch":
+				await this.#handleMutateBatch(message);
+				return;
+			case "syncHello":
+			case "queryRange":
+			case "queryByOffset":
+			case "rangeQuery":
+			case "rangeReconcile":
+				return;
+			default:
+				exhaustiveGuard(message);
+		}
+	}
+
+	async #intentToMessageLww(
+		intent: MutationIntent,
+	): Promise<SyncMessage<TItem> | null> {
+		const base = toSyncMessage(intent) as SyncMessage<TItem>;
+		if (base.type !== "update") {
+			return base;
+		}
+		const key = partialSyncRowKey(intent.key ?? base.value.id);
+		const existing = await this.options.store.getRow(key);
+		if (!existing) {
+			return base;
+		}
+		const incomingUpdatedAt = toMillis(base.value.updatedAt);
+		const existingUpdatedAt = toMillis(existing.updatedAt);
+		if (incomingUpdatedAt <= existingUpdatedAt) {
+			return {
+				type: "update",
+				value: existing,
+				previousValue: base.previousValue,
+			};
+		}
+		return base;
+	}
+
+	async #handleMutateBatch(
+		message: Extract<SyncClientMessage, { type: "mutateBatch" }>,
+	): Promise<void> {
+		const resolvedChanges: SyncMessage<TItem>[] = [];
+		const acceptedMutationIds: string[] = [];
+
+		for (const mutation of message.mutations) {
+			try {
+				const change = await this.#intentToMessageLww(mutation);
+				if (!change) {
+					continue;
+				}
+				resolvedChanges.push(change);
+				acceptedMutationIds.push(mutation.clientMutationId);
+			} catch (error) {
+				this.#emit(message.clientId, {
+					type: "reject",
+					clientId: message.clientId,
+					clientMutationId: mutation.clientMutationId,
+					reason: error instanceof Error ? error.message : String(error),
+					correctiveChanges: [],
+				});
+			}
+		}
+
+		if (resolvedChanges.length === 0) return;
+
+		await this.options.store.applySyncMessages(resolvedChanges);
+
+		this.#emit(message.clientId, {
+			type: "ack",
+			clientId: message.clientId,
+			clientMutationIds: acceptedMutationIds,
+			serverVersion: 0,
+			changes: resolvedChanges,
+		});
+
+		await this.options.partialBridge.pushServerChanges(resolvedChanges, {
+			excludeClientId: message.clientId,
+		});
+	}
+}

package/src/partial-sync-predicate-match.ts

@@ -0,0 +1,65 @@
+import { exhaustiveGuard } from "@firtoz/maybe-error";
+import type { RangeCondition } from "./sync-protocol";
+
+function compareUnknown(a: unknown, b: unknown): number {
+	const na = a instanceof Date ? a.getTime() : a;
+	const nb = b instanceof Date ? b.getTime() : b;
+	if (typeof na === "number" && typeof nb === "number") {
+		if (na === nb) return 0;
+		return na < nb ? -1 : 1;
+	}
+	return String(na).localeCompare(String(nb));
+}
+
+export function defaultPredicateColumnValue<TItem>(
+	row: TItem,
+	column: string,
+): unknown {
+	if (row !== null && typeof row === "object" && column in row) {
+		return (row as Record<string, unknown>)[column];
+	}
+	return undefined;
+}
+
+export function matchesPredicate<TItem>(
+	row: TItem,
+	conditions: RangeCondition[],
+	getColumnValue: (row: TItem, column: string) => unknown,
+): boolean {
+	for (const c of conditions) {
+		const v = getColumnValue(row, c.column);
+		switch (c.op) {
+			case "eq":
+				if (compareUnknown(v, c.value) !== 0) return false;
+				break;
+			case "neq":
+				if (compareUnknown(v, c.value) === 0) return false;
+				break;
+			case "gt":
+				if (compareUnknown(v, c.value) <= 0) return false;
+				break;
+			case "gte":
+				if (compareUnknown(v, c.value) < 0) return false;
+				break;
+			case "lt":
+				if (compareUnknown(v, c.value) >= 0) return false;
+				break;
+			case "lte":
+				if (compareUnknown(v, c.value) > 0) return false;
+				break;
+			case "between": {
+				if (c.valueTo === undefined) return false;
+				if (
+					compareUnknown(v, c.value) < 0 ||
+					compareUnknown(v, c.valueTo) > 0
+				) {
+					return false;
+				}
+				break;
+			}
+			default:
+				exhaustiveGuard(c.op);
+		}
+	}
+	return true;
+}

package/src/partial-sync-row-key.ts

@@ -0,0 +1,57 @@
+/**
+ * Row `id` values accepted by partial-sync (plain keys and ORM outputs such as drizzle-sqlite-wasm
+ * insert-schema types that are string-like but not assignable to `string | number` in TypeScript).
+ */
+export type PartialSyncRowId = string | number | { toString(): string };
+
+/**
+ * Minimal object shape keyed by a partial-sync row id. Use when only identity matters (e.g. cache
+ * keys). Prefer {@link PartialSyncRowShape} for sync / partial-sync bridges and hooks.
+ */
+export type PartialSyncRowRef = {
+	id: PartialSyncRowId;
+};
+
+/**
+ * Version watermark for sync / partial-sync (fingerprints, reconciliation). The **`updatedAt` key
+ * must exist** on the object; `null` or `undefined` mean “no ms watermark” at runtime (treated as
+ * `0` where a number is needed). Rows or ORM types **without** this property are not suitable for
+ * sync / partial-sync APIs—use {@link PartialSyncRowRef} only when you only need identity (e.g.
+ * cache keys). (`undefined` is included in the union so Drizzle `InferSelectModel` / optional
+ * columns remain assignable.)
+ */
+export type PartialSyncRowVersion = {
+	updatedAt: number | Date | null | undefined;
+};
+
+/**
+ * Row shape required across {@link PartialSyncClientBridge}, {@link SyncClientBridge}, and React
+ * partial-sync hooks: stable id plus a mandatory {@link PartialSyncRowVersion} key (see there).
+ */
+export type PartialSyncRowShape = PartialSyncRowRef & PartialSyncRowVersion;
+
+/** Max `updatedAt` as epoch ms; `null` / `undefined` → 0. */
+export function partialSyncRowVersionWatermarkMs(
+	row: PartialSyncRowVersion,
+): number {
+	const v = row.updatedAt;
+	if (v === null || v === undefined) return 0;
+	if (typeof v === "number") return v;
+	if (v instanceof Date) return v.getTime();
+	return 0;
+}
+
+/**
+ * Like {@link partialSyncRowVersionWatermarkMs} for decoded protocol payloads that are not yet
+ * narrowed to {@link PartialSyncRowVersion} (e.g. mutate-batch `value` fields). Missing
+ * `updatedAt` → 0.
+ */
+export function partialSyncRowVersionWatermarkMsUnknown(row: unknown): number {
+	if (!row || typeof row !== "object" || !("updatedAt" in row)) return 0;
+	return partialSyncRowVersionWatermarkMs(row as PartialSyncRowVersion);
+}
+
+export function partialSyncRowKey(id: PartialSyncRowId): string | number {
+	if (typeof id === "string" || typeof id === "number") return id;
+	return String(id);
+}