@firtoz/collection-sync 5.0.0 → 6.0.0

package/dist/sync-protocol.d.ts

@@ -0,0 +1,378 @@
+import { SyncMessage } from '@firtoz/db-helpers';
+import { z } from 'zod';
+
+/** Default {@link SyncClientMessage} / {@link SyncServerMessage} `collectionId` when omitted on the wire. */
+declare const DEFAULT_SYNC_COLLECTION_ID: "default";
+declare const mutationIntentSchema: z.ZodObject<{
+    clientMutationId: z.ZodString;
+    type: z.ZodEnum<{
+        insert: "insert";
+        update: "update";
+        delete: "delete";
+        truncate: "truncate";
+    }>;
+    value: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    previousValue: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    key: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$strip>;
+type MutationIntent = z.infer<typeof mutationIntentSchema>;
+type SyncSortDirection = "asc" | "desc";
+type SyncRangeSort = {
+    column: string;
+    direction: SyncSortDirection;
+};
+/** Fixed operator set for predicate-based range queries (e.g. spatial filters). */
+type RangeConditionOp = "gt" | "gte" | "lt" | "lte" | "eq" | "neq" | "between";
+type RangeCondition = {
+    column: string;
+    op: RangeConditionOp;
+    value: unknown;
+    /** Required when `op` is `"between"`. */
+    valueTo?: unknown;
+};
+type IndexRangeCursor = {
+    kind: "index";
+    mode: "cursor";
+    sort: SyncRangeSort;
+    limit: number;
+    afterCursor: unknown | null;
+};
+type IndexRangeOffset = {
+    kind: "index";
+    mode: "offset";
+    sort: SyncRangeSort;
+    limit: number;
+    offset: number;
+};
+type PredicateRange = {
+    kind: "predicate";
+    conditions: RangeCondition[];
+    sort?: SyncRangeSort;
+    limit?: number;
+};
+type SyncRange = IndexRangeCursor | IndexRangeOffset | PredicateRange;
+/** Client watermark for reconciliation (max row version in range + count). */
+type RangeFingerprint = {
+    version: number;
+    count: number;
+};
+declare const syncRangeSchema: z.ZodType<SyncRange>;
+declare function createClientMessageSchema(): z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"mutateBatch">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    mutations: z.ZodArray<z.ZodObject<{
+        clientMutationId: z.ZodString;
+        type: z.ZodEnum<{
+            insert: "insert";
+            update: "update";
+            delete: "delete";
+            truncate: "truncate";
+        }>;
+        value: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        previousValue: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        key: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"syncHello">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    lastAckedServerVersion: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"queryRange">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    requestId: z.ZodString;
+    sort: z.ZodObject<{
+        column: z.ZodString;
+        direction: z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>;
+    }, z.core.$strip>;
+    limit: z.ZodNumber;
+    afterCursor: z.ZodNullable<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"queryByOffset">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    requestId: z.ZodString;
+    sort: z.ZodObject<{
+        column: z.ZodString;
+        direction: z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>;
+    }, z.core.$strip>;
+    limit: z.ZodNumber;
+    offset: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"rangeQuery">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    requestId: z.ZodString;
+    range: z.ZodType<SyncRange, unknown, z.core.$ZodTypeInternals<SyncRange, unknown>>;
+    fingerprint: z.ZodOptional<z.ZodObject<{
+        version: z.ZodNumber;
+        count: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"rangeReconcile">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    requestId: z.ZodString;
+    range: z.ZodType<SyncRange, unknown, z.core.$ZodTypeInternals<SyncRange, unknown>>;
+    manifest: z.ZodArray<z.ZodObject<{
+        id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        version: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "type">;
+type SyncClientMessage = z.infer<ReturnType<typeof createClientMessageSchema>>;
+declare const clientMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"mutateBatch">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    mutations: z.ZodArray<z.ZodObject<{
+        clientMutationId: z.ZodString;
+        type: z.ZodEnum<{
+            insert: "insert";
+            update: "update";
+            delete: "delete";
+            truncate: "truncate";
+        }>;
+        value: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        previousValue: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        key: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"syncHello">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    lastAckedServerVersion: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"queryRange">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    requestId: z.ZodString;
+    sort: z.ZodObject<{
+        column: z.ZodString;
+        direction: z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>;
+    }, z.core.$strip>;
+    limit: z.ZodNumber;
+    afterCursor: z.ZodNullable<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"queryByOffset">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    requestId: z.ZodString;
+    sort: z.ZodObject<{
+        column: z.ZodString;
+        direction: z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>;
+    }, z.core.$strip>;
+    limit: z.ZodNumber;
+    offset: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"rangeQuery">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    requestId: z.ZodString;
+    range: z.ZodType<SyncRange, unknown, z.core.$ZodTypeInternals<SyncRange, unknown>>;
+    fingerprint: z.ZodOptional<z.ZodObject<{
+        version: z.ZodNumber;
+        count: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"rangeReconcile">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    requestId: z.ZodString;
+    range: z.ZodType<SyncRange, unknown, z.core.$ZodTypeInternals<SyncRange, unknown>>;
+    manifest: z.ZodArray<z.ZodObject<{
+        id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        version: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "type">;
+/** How to apply {@link SyncServerMessage} `syncBackfill` changes on the client. */
+type SyncBackfillMode = "snapshot" | "delta";
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** Client payload before `collectionId` is attached (bridge outbox helpers). */
+type SyncClientMessageBody = DistributiveOmit<SyncClientMessage, "collectionId">;
+declare function createServerMessageSchema<TItem = unknown, TKey extends string | number = string | number>(): z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"ack">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    clientMutationIds: z.ZodArray<z.ZodString>;
+    serverVersion: z.ZodNumber;
+    changes: z.ZodArray<z.ZodCustom<SyncMessage<TItem, TKey>, SyncMessage<TItem, TKey>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"syncBatch">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    serverVersion: z.ZodNumber;
+    changes: z.ZodArray<z.ZodCustom<SyncMessage<TItem, TKey>, SyncMessage<TItem, TKey>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"syncBackfill">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    mode: z.ZodEnum<{
+        snapshot: "snapshot";
+        delta: "delta";
+    }>;
+    serverVersion: z.ZodNumber;
+    changes: z.ZodArray<z.ZodCustom<SyncMessage<TItem, TKey>, SyncMessage<TItem, TKey>>>;
+    chunkIndex: z.ZodOptional<z.ZodNumber>;
+    totalChunks: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"reject">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    clientMutationId: z.ZodString;
+    reason: z.ZodString;
+    correctiveChanges: z.ZodDefault<z.ZodArray<z.ZodCustom<SyncMessage<TItem, TKey>, SyncMessage<TItem, TKey>>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"pong">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"queryRangeChunk">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    requestId: z.ZodString;
+    rows: z.ZodArray<z.ZodCustom<TItem, TItem>>;
+    totalCount: z.ZodNumber;
+    lastCursor: z.ZodNullable<z.ZodUnknown>;
+    hasMore: z.ZodBoolean;
+    chunkIndex: z.ZodNumber;
+    done: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"rangePatch">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    change: z.ZodCustom<SyncMessage<TItem, TKey>, SyncMessage<TItem, TKey>>;
+    viewTransition: z.ZodOptional<z.ZodEnum<{
+        enterView: "enterView";
+        exitView: "exitView";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"rangeUpToDate">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    requestId: z.ZodString;
+    totalCount: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"rangeDelta">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    requestId: z.ZodString;
+    totalCount: z.ZodNumber;
+    changes: z.ZodArray<z.ZodCustom<SyncMessage<TItem, TKey>, SyncMessage<TItem, TKey>>>;
+    lastCursor: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"rangeReconcileResult">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    requestId: z.ZodString;
+    added: z.ZodArray<z.ZodCustom<SyncMessage<TItem, TKey>, SyncMessage<TItem, TKey>>>;
+    updated: z.ZodArray<z.ZodCustom<SyncMessage<TItem, TKey>, SyncMessage<TItem, TKey>>>;
+    stale: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    movedHints: z.ZodArray<z.ZodObject<{
+        id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        hint: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+    totalCount: z.ZodNumber;
+}, z.core.$strip>], "type">;
+type SyncServerMessage<TItem = unknown, TKey extends string | number = string | number> = z.infer<ReturnType<typeof createServerMessageSchema<TItem, TKey>>>;
+/** Server payload before `collectionId` is attached (bridge outbox helpers). */
+type SyncServerMessageBody<TItem = unknown, TKey extends string | number = string | number> = DistributiveOmit<SyncServerMessage<TItem, TKey>, "collectionId">;
+/** Attach `collectionId` to an outbound server message (single-collection servers). */
+declare function withServerCollectionId<TItem, TKey extends string | number>(collectionId: string, message: SyncServerMessage<TItem, TKey>): SyncServerMessage<TItem, TKey>;
+declare const serverMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"ack">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    clientMutationIds: z.ZodArray<z.ZodString>;
+    serverVersion: z.ZodNumber;
+    changes: z.ZodArray<z.ZodCustom<SyncMessage<unknown, string | number>, SyncMessage<unknown, string | number>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"syncBatch">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    serverVersion: z.ZodNumber;
+    changes: z.ZodArray<z.ZodCustom<SyncMessage<unknown, string | number>, SyncMessage<unknown, string | number>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"syncBackfill">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    mode: z.ZodEnum<{
+        snapshot: "snapshot";
+        delta: "delta";
+    }>;
+    serverVersion: z.ZodNumber;
+    changes: z.ZodArray<z.ZodCustom<SyncMessage<unknown, string | number>, SyncMessage<unknown, string | number>>>;
+    chunkIndex: z.ZodOptional<z.ZodNumber>;
+    totalChunks: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"reject">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    clientId: z.ZodString;
+    clientMutationId: z.ZodString;
+    reason: z.ZodString;
+    correctiveChanges: z.ZodDefault<z.ZodArray<z.ZodCustom<SyncMessage<unknown, string | number>, SyncMessage<unknown, string | number>>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"pong">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"queryRangeChunk">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    requestId: z.ZodString;
+    rows: z.ZodArray<z.ZodCustom<unknown, unknown>>;
+    totalCount: z.ZodNumber;
+    lastCursor: z.ZodNullable<z.ZodUnknown>;
+    hasMore: z.ZodBoolean;
+    chunkIndex: z.ZodNumber;
+    done: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"rangePatch">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    change: z.ZodCustom<SyncMessage<unknown, string | number>, SyncMessage<unknown, string | number>>;
+    viewTransition: z.ZodOptional<z.ZodEnum<{
+        enterView: "enterView";
+        exitView: "exitView";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"rangeUpToDate">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    requestId: z.ZodString;
+    totalCount: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"rangeDelta">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    requestId: z.ZodString;
+    totalCount: z.ZodNumber;
+    changes: z.ZodArray<z.ZodCustom<SyncMessage<unknown, string | number>, SyncMessage<unknown, string | number>>>;
+    lastCursor: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"rangeReconcileResult">;
+    collectionId: z.ZodDefault<z.ZodString>;
+    requestId: z.ZodString;
+    added: z.ZodArray<z.ZodCustom<SyncMessage<unknown, string | number>, SyncMessage<unknown, string | number>>>;
+    updated: z.ZodArray<z.ZodCustom<SyncMessage<unknown, string | number>, SyncMessage<unknown, string | number>>>;
+    stale: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    movedHints: z.ZodArray<z.ZodObject<{
+        id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        hint: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+    totalCount: z.ZodNumber;
+}, z.core.$strip>], "type">;
+declare function toSyncMessage(intent: MutationIntent): SyncMessage;
+declare function createClientMutationId(prefix?: string): string;
+
+export { DEFAULT_SYNC_COLLECTION_ID, type IndexRangeCursor, type IndexRangeOffset, type MutationIntent, type PredicateRange, type RangeCondition, type RangeConditionOp, type RangeFingerprint, type SyncBackfillMode, type SyncClientMessage, type SyncClientMessageBody, type SyncRange, type SyncRangeSort, type SyncServerMessage, type SyncServerMessageBody, type SyncSortDirection, clientMessageSchema, createClientMessageSchema, createClientMutationId, createServerMessageSchema, mutationIntentSchema, serverMessageSchema, syncRangeSchema, toSyncMessage, withServerCollectionId };

package/dist/sync-protocol.js

@@ -0,0 +1,4 @@
+export { DEFAULT_SYNC_COLLECTION_ID, clientMessageSchema, createClientMessageSchema, createClientMutationId, createServerMessageSchema, mutationIntentSchema, serverMessageSchema, syncRangeSchema, toSyncMessage, withServerCollectionId } from './chunk-BJJEAKXL.js';
+import './chunk-HMLY7DHA.js';
+//# sourceMappingURL=sync-protocol.js.map
+//# sourceMappingURL=sync-protocol.js.map

package/dist/sync-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"sync-protocol.js"}

package/dist/sync-server-bridge.d.ts

@@ -0,0 +1,35 @@
+import { SyncMessage } from '@firtoz/db-helpers';
+import { SyncServerMessage, SyncClientMessage } from './sync-protocol.js';
+import { PartialSyncRowShape } from './partial-sync-row-key.js';
+import 'zod';
+
+interface SyncServerBridgeStore<TItem> {
+    applySyncMessages: (messages: SyncMessage<TItem>[]) => Promise<void>;
+    getSnapshotMessages: () => Promise<SyncMessage<TItem>[]>;
+    getRow: (key: string | number) => Promise<TItem | undefined>;
+}
+interface SyncServerBridgeOptions<TItem> {
+    store: SyncServerBridgeStore<TItem>;
+    sendToClient: (clientId: string, message: SyncServerMessage<TItem>) => void;
+    broadcastExcept: (excludeClientId: string, message: SyncServerMessage<TItem>) => void | Promise<void>;
+    /** Deliver a server message to every connected client (e.g. {@link SyncServerBridge.pushServerChanges}). */
+    broadcastAll?: (message: SyncServerMessage<TItem>) => void;
+    /** Maximum number of changes per `syncBackfill` frame. Defaults to 500. */
+    backfillChunkSize?: number;
+    /** Multiplex key for sync messages. Default {@link DEFAULT_SYNC_COLLECTION_ID}. */
+    collectionId?: string;
+}
+declare class SyncServerBridge<TItem extends PartialSyncRowShape> {
+    #private;
+    private readonly options;
+    constructor(options: SyncServerBridgeOptions<TItem>);
+    get collectionId(): string;
+    get serverVersion(): number;
+    handleClientMessage(message: SyncClientMessage): Promise<void>;
+    /**
+     * Apply mutations that originated on the server (cron, admin API, etc.) and fan out to all clients.
+     */
+    pushServerChanges(changes: SyncMessage<TItem>[]): Promise<void>;
+}
+
+export { SyncServerBridge, type SyncServerBridgeOptions, type SyncServerBridgeStore };

package/dist/sync-server-bridge.js

@@ -0,0 +1,6 @@
+export { SyncServerBridge } from './chunk-TEH7V76G.js';
+import './chunk-BJJEAKXL.js';
+import './chunk-UJ24XW52.js';
+import './chunk-HMLY7DHA.js';
+//# sourceMappingURL=sync-server-bridge.js.map
+//# sourceMappingURL=sync-server-bridge.js.map

package/dist/sync-server-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"sync-server-bridge.js"}

package/dist/with-sync.d.ts

@@ -0,0 +1,107 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { UtilsRecord, CollectionConfig, NonSingleResult } from '@tanstack/db';
+import { SyncClientBridge } from './sync-client-bridge.js';
+import { PartialSyncRowShape } from './partial-sync-row-key.js';
+import { SyncClientMessage } from './sync-protocol.js';
+import '@firtoz/db-helpers';
+import 'zod';
+
+/**
+ * Sync cursor persistence (see {@link WithSyncOptions}):
+ *
+ * - **Ephemeral collections** (in-memory only, no durable row storage): omit `syncStateKey`.
+ *   Each load gets a new `clientId` and `lastAckedServerVersion: 0`, so the server answers with a
+ *   **full snapshot** backfill — correct because local rows do not survive refresh.
+ *
+ * - **Durable collections** (IndexedDB, sqlite-wasm, etc.): set `syncStateKey` (and default storage).
+ *   `persistLastAckedServerVersion` defaults to **true**, so reconnect sends the last acked server
+ *   version and the server can return **delta** backfill when the changelog allows.
+ *
+ * - To keep a stable `clientId` in storage but **always** request a full snapshot (rare), set
+ *   `syncStateKey` and `persistLastAckedServerVersion: false`.
+ */
+/** Row shape required for sync (matches {@link SyncClientBridge}). */
+type SyncableCollectionItem = PartialSyncRowShape;
+/**
+ * Key/value persistence for sync metadata (`clientId`, `lastAckedServerVersion`).
+ * Same shape as `Storage`; use `localStorage`, `sessionStorage`, a `Map` adapter, etc.
+ */
+type SyncStateStorage = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+};
+type WithSyncOptions = {
+    /**
+     * If set, sync metadata (`clientId`, optionally `lastAckedServerVersion`) is read/written via
+     * {@link syncStateStorage} or `localStorage`. Omit for ephemeral collections (e.g. memory) so
+     * every load handshakes as a fresh client with a full snapshot — see module note above.
+     */
+    syncStateKey?: string;
+    /**
+     * Where to read/write {@link syncStateKey}. Defaults to `globalThis.localStorage` when `syncStateKey` is set and this is omitted.
+     * Pass `null` to skip persistence even when `syncStateKey` is set (e.g. tests).
+     */
+    syncStateStorage?: SyncStateStorage | null;
+    /**
+     * Persist and reuse lastAcked server version across page reloads (enables delta backfill on reconnect).
+     * Defaults to `true` when {@link syncStateKey} is set and a storage backend is resolved; set `false` to always handshake with `lastAckedServerVersion: 0` (full snapshot). When `false`, existing stored `lastAckedServerVersion` is preserved in storage so it is not wiped on load.
+     */
+    persistLastAckedServerVersion?: boolean;
+    onRejectedMutation?: (reason: string, mutationId: string) => void;
+    /**
+     * When `false`, the bridge does not send `syncHello` on connect (use with partial sync + `mutateBatch`).
+     * Default `true`.
+     */
+    sendSyncHelloOnConnect?: boolean;
+    /**
+     * When `false`, local {@link CollectionConfig.utils.truncate} clears storage only — it does **not**
+     * enqueue a `truncate` for the next `mutateBatch`. Partial sync calls truncate on window reset; forwarding
+     * it would batch with unrelated user edits and make the server apply `truncate` + `update`, wiping data.
+     * Default `true` (full sync). {@link createPartialSyncedCollection} sets this to `false`.
+     */
+    forwardTruncateToMutations?: boolean;
+    /**
+     * Must match the server's {@link SyncServerBridgeOptions.collectionId} on the same WebSocket.
+     */
+    collectionId?: string;
+    /**
+     * When set to a positive number (milliseconds), local mutation batches are debounced: each
+     * burst merges into one `onLocalMutation` call after this many milliseconds of quiet time.
+     * `truncate` messages flush any pending batch immediately and are not delayed.
+     */
+    localMutationThrottleMs?: number;
+};
+/** Returns `globalThis.localStorage` when it looks usable; otherwise `null`. */
+declare function getBrowserLocalStorageSyncStateStorage(): SyncStateStorage | null;
+/**
+ * Infer the collection row type from options passed to {@link withSync} / {@link createSyncedCollection}.
+ * Prefer `CollectionConfig`'s first type parameter (the select row). That matches Drizzle SQLite configs
+ * where `schema` is an insert schema whose {@link InferSchemaOutput} can differ from the row type.
+ */
+type InferItemFromCollectionOptions<T> = T extends Omit<CollectionConfig<infer TItem, infer _K, infer _S, infer _U>, "utils"> & {
+    utils: UtilsRecord;
+} ? TItem : T extends WithSyncableCollectionConfig<infer TItem, infer _K, infer _S, infer _U> ? TItem : T extends CollectionConfig<infer TItem, infer _TKey, infer _TSchema, infer _TUtils> ? TItem : T extends {
+    getKey: (item: infer I) => unknown;
+} ? I : never;
+/**
+ * Any TanStack {@link CollectionConfig} (from memory / IndexedDB / SQLite helpers, etc.)
+ * that is not a single-row collection. Requires `utils` (sync backends always provide it).
+ */
+type WithSyncableCollectionConfig<TItem extends SyncableCollectionItem = SyncableCollectionItem, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = UtilsRecord> = Omit<CollectionConfig<TItem, TKey, TSchema, TUtils>, "utils"> & NonSingleResult & {
+    utils: TUtils;
+};
+/**
+ * Wraps TanStack DB collection options so local mutations are forwarded to {@link SyncClientBridge}.
+ * Pair with {@link connectSync} or {@link createSyncedCollection} to attach a WebSocket transport.
+ *
+ * Row type is inferred from your collection config via {@link InferItemFromCollectionOptions}.
+ */
+/** Widened config union from memory / Drizzle / IndexedDB helpers. */
+type AnyWithSyncableCollectionConfig = WithSyncableCollectionConfig<any, any, any, any>;
+declare function withSync<TConfig extends AnyWithSyncableCollectionConfig>(baseOptions: TConfig, syncOptions?: WithSyncOptions): {
+    options: TConfig;
+    bridge: SyncClientBridge<InferItemFromCollectionOptions<TConfig>>;
+    setTransportSend: (send: (msg: SyncClientMessage) => void) => void;
+};
+
+export { type AnyWithSyncableCollectionConfig, type InferItemFromCollectionOptions, type SyncStateStorage, type SyncableCollectionItem, type WithSyncOptions, type WithSyncableCollectionConfig, getBrowserLocalStorageSyncStateStorage, withSync };

package/dist/with-sync.js

@@ -0,0 +1,7 @@
+export { getBrowserLocalStorageSyncStateStorage, withSync } from './chunk-YYGPIHHJ.js';
+import './chunk-QJP4GSJH.js';
+import './chunk-BJJEAKXL.js';
+import './chunk-UJ24XW52.js';
+import './chunk-HMLY7DHA.js';
+//# sourceMappingURL=with-sync.js.map
+//# sourceMappingURL=with-sync.js.map

package/dist/with-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"with-sync.js"}

package/package.json

@@ -1,34 +1,40 @@
 {
 	"name": "@firtoz/collection-sync",
-	"version": "5.0.0",
+	"version": "6.0.0",
 	"description": "WebSocket sync protocol and bridges for TanStack DB collections",
-	"main": "./src/index.ts",
-	"module": "./src/index.ts",
-	"types": "./src/index.ts",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"type": "module",
 	"exports": {
 		".": {
-			"types": "./src/index.ts",
-			"import": "./src/index.ts",
-			"require": "./src/index.ts"
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
 		},
 		"./react": {
-			"types": "./src/react/index.ts",
-			"import": "./src/react/index.ts",
-			"require": "./src/react/index.ts"
+			"types": "./dist/react/index.d.ts",
+			"import": "./dist/react/index.js"
+		},
+		"./react/*": {
+			"types": "./dist/react/*.d.ts",
+			"import": "./dist/react/*.js"
 		},
 		"./*": {
-			"types": "./src/*.ts",
-			"import": "./src/*.ts",
-			"require": "./src/*.ts"
+			"types": "./dist/*.d.ts",
+			"import": "./dist/*.js"
 		}
 	},
 	"files": [
+		"dist/**/*.js",
+		"dist/**/*.js.map",
+		"dist/**/*.d.ts",
 		"src/**/*.ts",
 		"!src/**/*.test.ts",
 		"README.md"
 	],
 	"scripts": {
+		"build": "tsup",
+		"prepack": "bun run build",
 		"typecheck": "tsgo --noEmit -p ./tsconfig.json",
 		"lint": "biome check --write src",
 		"lint:ci": "biome ci src",
@@ -59,19 +65,19 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@firtoz/db-helpers": "^2.1.1",
-		"@firtoz/maybe-error": "^1.5.2",
+		"@firtoz/db-helpers": "^2.2.0",
+		"@firtoz/maybe-error": "^1.6.0",
 		"zod": "^4.3.6"
 	},
 	"peerDependencies": {
-		"@firtoz/websocket-do": "^12.0.0",
+		"@firtoz/websocket-do": "^13.0.0",
 		"@standard-schema/spec": ">=1.1.0",
 		"@tanstack/db": ">=0.6.3",
 		"@tanstack/react-db": ">=0.1.82",
 		"react": ">=19.2.4"
 	},
 	"devDependencies": {
-		"@firtoz/websocket-do": "^12.0.0",
+		"@firtoz/websocket-do": "^13.0.0",
 		"@standard-schema/spec": "^1.1.0",
 		"@tanstack/db": "^0.6.4",
 		"@tanstack/react-db": "0.1.82",