@firtoz/collection-sync 1.0.0

package/src/connect-sync.ts

@@ -0,0 +1,82 @@
+import { ZodWebSocketClient } from "@firtoz/websocket-do/zod-client";
+import type { SyncClientBridge } from "./sync-client-bridge";
+import type { PartialSyncRowShape } from "./partial-sync-row-key";
+import {
+	createClientMessageSchema,
+	createServerMessageSchema,
+	type SyncClientMessage,
+	type SyncServerMessage,
+} from "./sync-protocol";
+
+export type ConnectSyncTransport = "json" | "msgpack";
+
+export type ConnectSyncOptions<TItem = unknown> = {
+	/** WebSocket URL (e.g. `wss://host/room/x/websocket`). */
+	url: string;
+	transport?: ConnectSyncTransport;
+	/** Prefer a module-level function or `useCallback`; a new inline function each render can churn effects. */
+	serializeJson?: (value: unknown) => string;
+	/** Prefer a module-level function or `useCallback`; a new inline function each render can churn effects. */
+	deserializeJson?: (raw: string) => unknown;
+	/** Wire transport after {@link SyncClientBridge} is created (from {@link withSync}). */
+	setTransportSend: (send: (msg: SyncClientMessage) => void) => void;
+	/** Optional tap before messages reach the bridge (e.g. debug / inspector). */
+	onServerMessage?: (msg: SyncServerMessage<TItem>) => void;
+};
+
+/**
+ * Connects a {@link SyncClientBridge} to a WebSocket using the same codec as {@link ZodSession} on the server.
+ */
+export function connectSync<TItem extends PartialSyncRowShape>(
+	bridge: SyncClientBridge<TItem>,
+	options: ConnectSyncOptions<TItem>,
+): () => void {
+	const clientSchema = createClientMessageSchema();
+	const serverSchema = createServerMessageSchema<TItem>();
+	const useMsgpack = options.transport === "msgpack";
+
+	const zodClient = new ZodWebSocketClient({
+		url: options.url,
+		clientSchema,
+		serverSchema,
+		enableBufferMessages: useMsgpack,
+		...(useMsgpack
+			? {}
+			: {
+					serializeJson: options.serializeJson ?? JSON.stringify,
+					deserializeJson: options.deserializeJson ?? JSON.parse,
+				}),
+		onMessage: (msg) => {
+			options.onServerMessage?.(msg);
+			void bridge.handleServerMessage(msg);
+		},
+	});
+
+	options.setTransportSend((message) => {
+		zodClient.send(message);
+	});
+
+	bridge.setConnected(false);
+
+	const onOpen = () => {
+		bridge.setConnected(true);
+	};
+	const onClose = () => {
+		bridge.setConnected(false);
+	};
+
+	zodClient.socket.addEventListener("open", onOpen);
+	zodClient.socket.addEventListener("close", onClose);
+
+	if (zodClient.socket.readyState === WebSocket.OPEN) {
+		onOpen();
+	}
+
+	return () => {
+		zodClient.socket.removeEventListener("open", onOpen);
+		zodClient.socket.removeEventListener("close", onClose);
+		bridge.setConnected(false);
+		options.setTransportSend(() => {});
+		zodClient.close();
+	};
+}

package/src/create-partial-synced-collection.ts

@@ -0,0 +1,32 @@
+import type { Collection } from "@tanstack/db";
+import { createCollection } from "@tanstack/db";
+import {
+	withSync,
+	type AnyWithSyncableCollectionConfig,
+	type InferItemFromCollectionOptions,
+	type WithSyncOptions,
+} from "./with-sync";
+
+/**
+ * Like {@link createSyncedCollection}, but defaults `sendSyncHelloOnConnect` to `false` and
+ * `forwardTruncateToMutations` to `false` for use with {@link connectPartialSync} +
+ * {@link usePartialSyncWindow} (`mutateBatch` without `syncHello`). Local window resets call
+ * `truncate()` on the collection; those must not be sent to the server or they can batch with user
+ * edits and wipe authoritative data.
+ */
+export function createPartialSyncedCollection<
+	TConfig extends AnyWithSyncableCollectionConfig,
+>(baseOptions: TConfig, syncOptions?: WithSyncOptions) {
+	type TItem = InferItemFromCollectionOptions<TConfig>;
+	const { options, bridge, setTransportSend } = withSync(baseOptions, {
+		...syncOptions,
+		sendSyncHelloOnConnect: syncOptions?.sendSyncHelloOnConnect ?? false,
+		forwardTruncateToMutations:
+			syncOptions?.forwardTruncateToMutations ?? false,
+	});
+	const collection = createCollection(
+		options as never,
+	) as unknown as Collection<TItem>;
+	bridge.setRowGet((key) => collection.get(key));
+	return { collection, bridge, setTransportSend };
+}

package/src/create-synced-collection.ts

@@ -0,0 +1,32 @@
+import type { Collection } from "@tanstack/db";
+import { createCollection } from "@tanstack/db";
+import {
+	withSync,
+	type AnyWithSyncableCollectionConfig,
+	type InferItemFromCollectionOptions,
+	type WithSyncOptions,
+} from "./with-sync";
+
+/**
+ * Builds a {@link withSync} wrapper and a TanStack {@link createCollection} in one step.
+ * Row type is inferred from the collection config (see {@link InferItemFromCollectionOptions}).
+ * (The internal `as unknown as Collection<TItem>` bridges `createCollection`'s overloads to the inferred row type.)
+ *
+ * Pass `syncOptions` for durable backends (IndexedDB, sqlite-wasm): use `syncStateKey` so incremental
+ * reconnect works. Omit `syncOptions` (or omit `syncStateKey`) for in-memory collections that need a
+ * full snapshot every load — see the module doc on {@link withSync} / `with-sync.ts`.
+ */
+export function createSyncedCollection<
+	TConfig extends AnyWithSyncableCollectionConfig,
+>(baseOptions: TConfig, syncOptions?: WithSyncOptions) {
+	type TItem = InferItemFromCollectionOptions<TConfig>;
+	const { options, bridge, setTransportSend } = withSync(
+		baseOptions,
+		syncOptions,
+	);
+	const collection = createCollection(
+		options as never,
+	) as unknown as Collection<TItem>;
+	bridge.setRowGet((key) => collection.get(key));
+	return { collection, bridge, setTransportSend };
+}

package/src/index.ts

@@ -0,0 +1,119 @@
+export {
+	DEFAULT_SYNC_COLLECTION_ID,
+	createClientMessageSchema,
+	createServerMessageSchema,
+	clientMessageSchema,
+	serverMessageSchema,
+	mutationIntentSchema,
+	syncRangeSchema,
+	toSyncMessage,
+	createClientMutationId,
+	type MutationIntent,
+	type IndexRangeCursor,
+	type IndexRangeOffset,
+	type PredicateRange,
+	type RangeCondition,
+	type RangeConditionOp,
+	type RangeFingerprint,
+	type SyncBackfillMode,
+	type SyncClientMessage,
+	type SyncClientMessageBody,
+	type SyncRange,
+	type SyncRangeSort,
+	type SyncServerMessage,
+	type SyncServerMessageBody,
+	type SyncSortDirection,
+} from "./sync-protocol";
+
+export {
+	SyncClientBridge,
+	type SyncClientBridgeOptions,
+} from "./sync-client-bridge";
+
+export {
+	PartialSyncClientBridge,
+	type PartialSyncClientBridgeOptions,
+	type PartialSyncRangePatchAppliedEvent,
+	type PartialSyncRangeResult,
+	type PartialSyncReconcileResult,
+	type PartialSyncState,
+	type PartialSyncViewTransitionEvent,
+} from "./partial-sync-client-bridge";
+
+export {
+	CacheManager,
+	type CacheEntry,
+	type CacheManagerOptions,
+	type CacheStorageEstimate,
+	type CacheViewport,
+} from "./cache-manager";
+
+export {
+	SyncServerBridge,
+	type SyncServerBridgeStore,
+	type SyncServerBridgeOptions,
+} from "./sync-server-bridge";
+
+export {
+	PartialSyncServerBridge,
+	type ClientQueryState,
+	type DeliveredRange,
+	type PartialSyncPushServerChangesOptions,
+	type PartialSyncServerBridgeOptions,
+	type PartialSyncServerBridgeStore,
+} from "./partial-sync-server-bridge";
+
+export {
+	PartialSyncMutationHandler,
+	type PartialSyncMutationHandlerOptions,
+	type PartialSyncMutationHandlerStore,
+} from "./partial-sync-mutation-handler";
+
+export {
+	withSync,
+	getBrowserLocalStorageSyncStateStorage,
+	type AnyWithSyncableCollectionConfig,
+	type InferItemFromCollectionOptions,
+	type SyncStateStorage,
+	type SyncableCollectionItem,
+	type WithSyncOptions,
+	type WithSyncableCollectionConfig,
+} from "./with-sync";
+
+export { createSyncedCollection } from "./create-synced-collection";
+
+export { createPartialSyncedCollection } from "./create-partial-synced-collection";
+
+export {
+	connectSync,
+	type ConnectSyncOptions,
+	type ConnectSyncTransport,
+} from "./connect-sync";
+
+export {
+	connectPartialSync,
+	type ConnectPartialSyncOptions,
+	type ConnectPartialSyncTransport,
+} from "./connect-partial-sync";
+
+export {
+	partialSyncRowKey,
+	partialSyncRowVersionWatermarkMs,
+	partialSyncRowVersionWatermarkMsUnknown,
+	type PartialSyncRowId,
+	type PartialSyncRowRef,
+	type PartialSyncRowShape,
+	type PartialSyncRowVersion,
+} from "./partial-sync-row-key";
+
+export type {
+	PartialSyncPatchResult,
+	PartialSyncViewTransition,
+} from "./partial-sync-interest";
+
+export {
+	compareInterestValues,
+	filterSyncMessagesForPredicateRange,
+	rowMatchesClientInterest,
+	type ClassifyPartialSyncRangePatchOptions,
+} from "./partial-sync-interest";