@firtoz/collection-sync 4.0.0 → 6.0.0

package/dist/chunk-6EHROJFY.js

@@ -0,0 +1,111 @@
+import { matchesPredicate } from './chunk-3EHHMLSV.js';
+import { partialSyncRowKey } from './chunk-UJ24XW52.js';
+import { exhaustiveGuard } from '@firtoz/maybe-error';
+
+function compareInterestValues(left, right) {
+  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);
+}
+function sortValueWithinDeliveredRange(value, range) {
+  if (value === void 0 || 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;
+}
+function rowMatchesDeliveredSortRanges(ranges, row, getSortValue) {
+  if (ranges.length === 0) return false;
+  return ranges.some((range) => {
+    const sortValue = getSortValue(row, range.sortColumn);
+    return sortValueWithinDeliveredRange(sortValue, range);
+  });
+}
+function rowMatchesPredicateGroups(predicateGroups, row, getColumnValue) {
+  if (predicateGroups.length === 0) return false;
+  return predicateGroups.some(
+    (group) => matchesPredicate(row, group, getColumnValue)
+  );
+}
+function rowMatchesClientInterest(sortRanges, predicateGroups, row, getSortValue, getColumnValue) {
+  if (predicateGroups.length > 0) {
+    return rowMatchesPredicateGroups(predicateGroups, row, getColumnValue);
+  }
+  if (sortRanges.length > 0) {
+    return rowMatchesDeliveredSortRanges(sortRanges, row, getSortValue);
+  }
+  return false;
+}
+function classifyPartialSyncRangePatch(sortRanges, predicateGroups, change, getSortValue, getColumnValue, options) {
+  const deliveredIds = options?.deliveredRowIds;
+  if (change.type === "delete" && deliveredIds !== void 0) {
+    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 !== void 0 ? 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);
+}
+function filterSyncMessagesForPredicateRange(conditions, changes, getSortValue, getColumnValue) {
+  const predicateGroups = [conditions];
+  const sortRanges = [];
+  const out = [];
+  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;
+}
+
+export { classifyPartialSyncRangePatch, compareInterestValues, filterSyncMessagesForPredicateRange, rowMatchesClientInterest, rowMatchesDeliveredSortRanges, rowMatchesPredicateGroups, sortValueWithinDeliveredRange };
+//# sourceMappingURL=chunk-6EHROJFY.js.map
+//# sourceMappingURL=chunk-6EHROJFY.js.map

package/dist/chunk-6EHROJFY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/partial-sync-interest.ts"],"names":[],"mappings":";;;;AAuBO,SAAS,qBAAA,CAAsB,MAAe,KAAA,EAAwB;AAC5E,EAAA,MAAM,SAAA,GAAY,IAAA,YAAgB,IAAA,GAAO,IAAA,CAAK,SAAQ,GAAI,IAAA;AAC1D,EAAA,MAAM,UAAA,GAAa,KAAA,YAAiB,IAAA,GAAO,KAAA,CAAM,SAAQ,GAAI,KAAA;AAC7D,EAAA,IAAI,OAAO,SAAA,KAAc,QAAA,IAAY,OAAO,eAAe,QAAA,EAAU;AACpE,IAAA,OAAO,SAAA,KAAc,UAAA,GAAa,CAAA,GAAI,SAAA,GAAY,aAAa,EAAA,GAAK,CAAA;AAAA,EACrE;AACA,EAAA,MAAM,UAAA,GAAa,OAAO,SAAS,CAAA;AACnC,EAAA,MAAM,WAAA,GAAc,OAAO,UAAU,CAAA;AACrC,EAAA,OAAO,UAAA,CAAW,cAAc,WAAW,CAAA;AAC5C;AAEO,SAAS,6BAAA,CACf,OACA,KAAA,EACU;AACV,EAAA,IAAI,KAAA,KAAU,MAAA,IAAa,KAAA,KAAU,IAAA,EAAM,OAAO,KAAA;AAClD,EAAA,MAAM,WAAA,GAAc,qBAAA,CAAsB,KAAA,EAAO,KAAA,CAAM,SAAS,CAAA;AAChE,EAAA,MAAM,SAAA,GAAY,qBAAA,CAAsB,KAAA,EAAO,KAAA,CAAM,OAAO,CAAA;AAC5D,EAAA,IAAI,KAAA,CAAM,kBAAkB,KAAA,EAAO;AAClC,IAAA,OAAO,WAAA,IAAe,KAAK,SAAA,IAAa,CAAA;AAAA,EACzC;AACA,EAAA,OAAO,WAAA,IAAe,KAAK,SAAA,IAAa,CAAA;AACzC;AAEO,SAAS,6BAAA,CACf,MAAA,EACA,GAAA,EACA,YAAA,EACU;AACV,EAAA,IAAI,MAAA,CAAO,MAAA,KAAW,CAAA,EAAG,OAAO,KAAA;AAChC,EAAA,OAAO,MAAA,CAAO,IAAA,CAAK,CAAC,KAAA,KAAU;AAC7B,IAAA,MAAM,SAAA,GAAY,YAAA,CAAa,GAAA,EAAK,KAAA,CAAM,UAAU,CAAA;AACpD,IAAA,OAAO,6BAAA,CAA8B,WAAW,KAAK,CAAA;AAAA,EACtD,CAAC,CAAA;AACF;AAEO,SAAS,yBAAA,CACf,eAAA,EACA,GAAA,EACA,cAAA,EACU;AACV,EAAA,IAAI,eAAA,CAAgB,MAAA,KAAW,CAAA,EAAG,OAAO,KAAA;AACzC,EAAA,OAAO,eAAA,CAAgB,IAAA;AAAA,IAAK,CAAC,KAAA,KAC5B,gBAAA,CAAiB,GAAA,EAAK,OAAO,cAAc;AAAA,GAC5C;AACD;AAEO,SAAS,wBAAA,CACf,UAAA,EACA,eAAA,EACA,GAAA,EACA,cACA,cAAA,EACU;AAEV,EAAA,IAAI,eAAA,CAAgB,SAAS,CAAA,EAAG;AAC/B,IAAA,OAAO,yBAAA,CAA0B,eAAA,EAAiB,GAAA,EAAK,cAAc,CAAA;AAAA,EACtE;AACA,EAAA,IAAI,UAAA,CAAW,SAAS,CAAA,EAAG;AAC1B,IAAA,OAAO,6BAAA,CAA8B,UAAA,EAAY,GAAA,EAAK,YAAY,CAAA;AAAA,EACnE;AACA,EAAA,OAAO,KAAA;AACR;AAeO,SAAS,8BAGf,UAAA,EACA,eAAA,EACA,MAAA,EACA,YAAA,EACA,gBACA,OAAA,EACuC;AACvC,EAAA,MAAM,eAAe,OAAA,EAAS,eAAA;AAC9B,EAAA,IAAI,MAAA,CAAO,IAAA,KAAS,QAAA,IAAY,YAAA,KAAiB,MAAA,EAAW;AAC3D,IAAA,OAAO,YAAA,CAAa,GAAA,CAAI,MAAA,CAAO,iBAAA,CAAkB,MAAA,CAAO,GAAG,CAAC,CAAC,CAAA,GAC1D,EAAE,MAAA,EAAO,GACT,IAAA;AAAA,EACJ;AAEA,EAAA,MAAM,WAAA,GAAc,UAAA,CAAW,MAAA,GAAS,CAAA,IAAK,gBAAgB,MAAA,GAAS,CAAA;AACtE,EAAA,IAAI,CAAC,aAAa,OAAO,IAAA;AAEzB,EAAA,IAAI,MAAA,CAAO,IAAA,KAAS,UAAA,EAAY,OAAO,EAAE,MAAA,EAAO;AAChD,EAAA,IAAI,MAAA,CAAO,IAAA,KAAS,QAAA,EAAU,OAAO,EAAE,MAAA,EAAO;AAE9C,EAAA,IAAI,MAAA,CAAO,SAAS,QAAA,EAAU;AAC7B,IAAA,OAAO,wBAAA;AAAA,MACN,UAAA;AAAA,MACA,eAAA;AAAA,MACA,MAAA,CAAO,KAAA;AAAA,MACP,YAAA;AAAA,MACA;AAAA,KACD,GACG,EAAE,MAAA,EAAO,GACT,IAAA;AAAA,EACJ;AAEA,EAAA,IAAI,MAAA,CAAO,SAAS,QAAA,EAAU;AAC7B,IAAA,MAAM,KAAA,GAAQ,wBAAA;AAAA,MACb,UAAA;AAAA,MACA,eAAA;AAAA,MACA,MAAA,CAAO,KAAA;AAAA,MACP,YAAA;AAAA,MACA;AAAA,KACD;AACA,IAAA,MAAM,KAAA,GACL,MAAA,CAAO,aAAA,KAAkB,MAAA,GACtB,wBAAA;AAAA,MACA,UAAA;AAAA,MACA,eAAA;AAAA,MACA,MAAA,CAAO,aAAA;AAAA,MACP,YAAA;AAAA,MACA;AAAA,KACD,GACC,KAAA;AACJ,IAAA,IAAI,KAAA,IAAS,KAAA,EAAO,OAAO,EAAE,MAAA,EAAO;AACpC,IAAA,IAAI,SAAS,CAAC,KAAA,SAAc,EAAE,MAAA,EAAQ,gBAAgB,WAAA,EAAY;AAClE,IAAA,IAAI,CAAC,KAAA,IAAS,KAAA,SAAc,EAAE,MAAA,EAAQ,gBAAgB,UAAA,EAAW;AACjE,IAAA,OAAO,IAAA;AAAA,EACR;AAEA,EAAA,eAAA,CAAgB,MAAM,CAAA;AACvB;AAWO,SAAS,mCAAA,CAGf,UAAA,EACA,OAAA,EACA,YAAA,EACA,cAAA,EACuB;AACvB,EAAA,MAAM,eAAA,GAAsC,CAAC,UAAU,CAAA;AACvD,EAAA,MAAM,aAA+B,EAAC;AACtC,EAAA,MAAM,MAA4B,EAAC;AACnC,EAAA,KAAA,MAAW,UAAU,OAAA,EAAS;AAC7B,IAAA,IAAI,MAAA,CAAO,SAAS,QAAA,EAAU;AAC7B,MAAA,GAAA,CAAI,KAAK,MAAM,CAAA;AACf,MAAA;AAAA,IACD;AACA,IAAA,MAAM,KAAA,GAAQ,6BAAA;AAAA,MACb,UAAA;AAAA,MACA,eAAA;AAAA,MACA,MAAA;AAAA,MACA,YAAA;AAAA,MACA;AAAA,KACD;AACA,IAAA,IAAI,UAAU,IAAA,EAAM;AACnB,MAAA,GAAA,CAAI,IAAA,CAAK,MAAM,MAAM,CAAA;AAAA,IACtB;AAAA,EACD;AACA,EAAA,OAAO,GAAA;AACR","file":"chunk-6EHROJFY.js","sourcesContent":["import type { SyncMessage } from \"@firtoz/db-helpers\";\nimport { exhaustiveGuard } from \"@firtoz/maybe-error\";\nimport type { RangeCondition } from \"./sync-protocol\";\nimport type { PartialSyncRowShape } from \"./partial-sync-row-key\";\nimport { partialSyncRowKey } from \"./partial-sync-row-key\";\nimport { matchesPredicate } from \"./partial-sync-predicate-match\";\n\n/** Metadata on `rangePatch` when an update crosses client interest boundaries. */\nexport type PartialSyncViewTransition = \"enterView\" | \"exitView\";\n\nexport type PartialSyncPatchResult<TItem extends PartialSyncRowShape> = {\n\tchange: SyncMessage<TItem>;\n\tviewTransition?: PartialSyncViewTransition;\n};\n\n/** Tracked 1D sort interval delivered to a client (index / cursor queries). */\nexport type DeliveredRange = {\n\tsortColumn: string;\n\tsortDirection: \"asc\" | \"desc\";\n\tfromValue: unknown;\n\ttoValue: unknown;\n};\n\nexport function compareInterestValues(left: unknown, right: unknown): number {\n\tconst leftValue = left instanceof Date ? left.getTime() : left;\n\tconst rightValue = right instanceof Date ? right.getTime() : right;\n\tif (typeof leftValue === \"number\" && typeof rightValue === \"number\") {\n\t\treturn leftValue === rightValue ? 0 : leftValue < rightValue ? -1 : 1;\n\t}\n\tconst leftString = String(leftValue);\n\tconst rightString = String(rightValue);\n\treturn leftString.localeCompare(rightString);\n}\n\nexport function sortValueWithinDeliveredRange(\n\tvalue: unknown,\n\trange: DeliveredRange,\n): boolean {\n\tif (value === undefined || value === null) return false;\n\tconst compareFrom = compareInterestValues(value, range.fromValue);\n\tconst compareTo = compareInterestValues(value, range.toValue);\n\tif (range.sortDirection === \"asc\") {\n\t\treturn compareFrom >= 0 && compareTo <= 0;\n\t}\n\treturn compareFrom <= 0 && compareTo >= 0;\n}\n\nexport function rowMatchesDeliveredSortRanges<TItem>(\n\tranges: DeliveredRange[],\n\trow: TItem,\n\tgetSortValue: (row: TItem, column: string) => unknown,\n): boolean {\n\tif (ranges.length === 0) return false;\n\treturn ranges.some((range) => {\n\t\tconst sortValue = getSortValue(row, range.sortColumn);\n\t\treturn sortValueWithinDeliveredRange(sortValue, range);\n\t});\n}\n\nexport function rowMatchesPredicateGroups<TItem>(\n\tpredicateGroups: RangeCondition[][],\n\trow: TItem,\n\tgetColumnValue: (row: TItem, column: string) => unknown,\n): boolean {\n\tif (predicateGroups.length === 0) return false;\n\treturn predicateGroups.some((group) =>\n\t\tmatchesPredicate(row, group, getColumnValue),\n\t);\n}\n\nexport function rowMatchesClientInterest<TItem>(\n\tsortRanges: DeliveredRange[],\n\tpredicateGroups: RangeCondition[][],\n\trow: TItem,\n\tgetSortValue: (row: TItem, column: string) => unknown,\n\tgetColumnValue: (row: TItem, column: string) => unknown,\n): boolean {\n\t/** Predicate viewport wins over 1D sort windows so chunk sort keys do not widen visibility. */\n\tif (predicateGroups.length > 0) {\n\t\treturn rowMatchesPredicateGroups(predicateGroups, row, getColumnValue);\n\t}\n\tif (sortRanges.length > 0) {\n\t\treturn rowMatchesDeliveredSortRanges(sortRanges, row, getSortValue);\n\t}\n\treturn false;\n}\n\nexport type ClassifyPartialSyncRangePatchOptions = {\n\t/**\n\t * When set, `delete` is only forwarded if the key was previously delivered to this client\n\t * (viewport-scoped deletes). When omitted, `delete` is always forwarded (legacy behavior).\n\t */\n\tdeliveredRowIds?: ReadonlySet<string> | undefined;\n};\n\n/**\n * Maps a server-side change to a `rangePatch` payload, or `null` if this client should not\n * receive a patch. View enter/exit keeps the real `update` on the wire so clients can cache\n * rows and filter locally instead of fake delete/insert.\n */\nexport function classifyPartialSyncRangePatch<\n\tTItem extends PartialSyncRowShape,\n>(\n\tsortRanges: DeliveredRange[],\n\tpredicateGroups: RangeCondition[][],\n\tchange: SyncMessage<TItem>,\n\tgetSortValue: (row: TItem, column: string) => unknown,\n\tgetColumnValue: (row: TItem, column: string) => unknown,\n\toptions?: ClassifyPartialSyncRangePatchOptions,\n): PartialSyncPatchResult<TItem> | null {\n\tconst deliveredIds = options?.deliveredRowIds;\n\tif (change.type === \"delete\" && deliveredIds !== undefined) {\n\t\treturn deliveredIds.has(String(partialSyncRowKey(change.key)))\n\t\t\t? { change }\n\t\t\t: null;\n\t}\n\n\tconst hasInterest = sortRanges.length > 0 || predicateGroups.length > 0;\n\tif (!hasInterest) return null;\n\n\tif (change.type === \"truncate\") return { change };\n\tif (change.type === \"delete\") return { change };\n\n\tif (change.type === \"insert\") {\n\t\treturn rowMatchesClientInterest(\n\t\t\tsortRanges,\n\t\t\tpredicateGroups,\n\t\t\tchange.value,\n\t\t\tgetSortValue,\n\t\t\tgetColumnValue,\n\t\t)\n\t\t\t? { change }\n\t\t\t: null;\n\t}\n\n\tif (change.type === \"update\") {\n\t\tconst newIn = rowMatchesClientInterest(\n\t\t\tsortRanges,\n\t\t\tpredicateGroups,\n\t\t\tchange.value,\n\t\t\tgetSortValue,\n\t\t\tgetColumnValue,\n\t\t);\n\t\tconst oldIn =\n\t\t\tchange.previousValue !== undefined\n\t\t\t\t? rowMatchesClientInterest(\n\t\t\t\t\t\tsortRanges,\n\t\t\t\t\t\tpredicateGroups,\n\t\t\t\t\t\tchange.previousValue,\n\t\t\t\t\t\tgetSortValue,\n\t\t\t\t\t\tgetColumnValue,\n\t\t\t\t\t)\n\t\t\t\t: false;\n\t\tif (newIn && oldIn) return { change };\n\t\tif (newIn && !oldIn) return { change, viewTransition: \"enterView\" };\n\t\tif (!newIn && oldIn) return { change, viewTransition: \"exitView\" };\n\t\treturn null;\n\t}\n\n\texhaustiveGuard(change);\n}\n\n/**\n * Filters sync messages to those relevant to a single predicate range (viewport). Used for\n * `rangeDelta` so clients never receive changelog rows outside their requested conditions.\n *\n * - `insert` / `update` / `truncate`: uses {@link classifyPartialSyncRangePatch} with only this\n *   predicate group (no sort ranges).\n * - `delete`: passed through unchanged — callers should filter deletes in the store when the\n *   deleted row snapshot is available (e.g. changelog payload).\n */\nexport function filterSyncMessagesForPredicateRange<\n\tTItem extends PartialSyncRowShape,\n>(\n\tconditions: RangeCondition[],\n\tchanges: SyncMessage<TItem>[],\n\tgetSortValue: (row: TItem, column: string) => unknown,\n\tgetColumnValue: (row: TItem, column: string) => unknown,\n): SyncMessage<TItem>[] {\n\tconst predicateGroups: RangeCondition[][] = [conditions];\n\tconst sortRanges: DeliveredRange[] = [];\n\tconst out: SyncMessage<TItem>[] = [];\n\tfor (const change of changes) {\n\t\tif (change.type === \"delete\") {\n\t\t\tout.push(change);\n\t\t\tcontinue;\n\t\t}\n\t\tconst patch = classifyPartialSyncRangePatch(\n\t\t\tsortRanges,\n\t\t\tpredicateGroups,\n\t\t\tchange,\n\t\t\tgetSortValue,\n\t\t\tgetColumnValue,\n\t\t);\n\t\tif (patch !== null) {\n\t\t\tout.push(patch.change);\n\t\t}\n\t}\n\treturn out;\n}\n"]}

package/dist/chunk-6X3434GJ.js

@@ -0,0 +1,21 @@
+// src/react/partial-sync-adapter.ts
+function createPartialSyncAdapter(config) {
+  return {
+    toConditions: config.toConditions,
+    expandViewport: config.expandViewport ?? ((v) => v),
+    sort: config.sort,
+    getSortValue: config.getSortValue
+  };
+}
+function betweenConditionsForNumericAxes(viewport, axes) {
+  return axes.map((axis) => ({
+    column: axis.column,
+    op: "between",
+    value: axis.min(viewport),
+    valueTo: axis.max(viewport)
+  }));
+}
+
+export { betweenConditionsForNumericAxes, createPartialSyncAdapter };
+//# sourceMappingURL=chunk-6X3434GJ.js.map
+//# sourceMappingURL=chunk-6X3434GJ.js.map

package/dist/chunk-6X3434GJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react/partial-sync-adapter.ts"],"names":[],"mappings":";AAsCO,SAAS,yBAKf,MAAA,EAC4D;AAC5D,EAAA,OAAO;AAAA,IACN,cAAc,MAAA,CAAO,YAAA;AAAA,IACrB,cAAA,EAAgB,MAAA,CAAO,cAAA,KAAmB,CAAC,CAAA,KAAM,CAAA,CAAA;AAAA,IACjD,MAAM,MAAA,CAAO,IAAA;AAAA,IACb,cAAc,MAAA,CAAO;AAAA,GACtB;AACD;AAWO,SAAS,+BAAA,CACf,UACA,IAAA,EACmB;AACnB,EAAA,OAAO,IAAA,CAAK,GAAA,CAAI,CAAC,IAAA,MAAU;AAAA,IAC1B,QAAQ,IAAA,CAAK,MAAA;AAAA,IACb,EAAA,EAAI,SAAA;AAAA,IACJ,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,QAAQ,CAAA;AAAA,IACxB,OAAA,EAAS,IAAA,CAAK,GAAA,CAAI,QAAQ;AAAA,GAC3B,CAAE,CAAA;AACH","file":"chunk-6X3434GJ.js","sourcesContent":["import type { PartialSyncRowShape } from \"../partial-sync-row-key\";\nimport type { RangeCondition, SyncRangeSort } from \"../sync-protocol\";\n\n/** Row shape compatible with partial-sync viewport hooks (matches {@link PartialSyncItem}). */\nexport type PartialSyncViewportItem = PartialSyncRowShape;\n\nexport type PredicateSortSpec<TSortColumn extends string> = {\n\tcolumn: TSortColumn;\n\tdirection: SyncRangeSort[\"direction\"];\n};\n\n/**\n * Bundles predicate ↔ viewport mapping, optional prefetch expansion, and sort accessors for\n * {@link usePartialSyncViewport} + {@link usePredicateFilteredRows}.\n */\nexport type PartialSyncViewportAdapter<\n\tTItem extends PartialSyncViewportItem,\n\tTViewport,\n\tTSortColumn extends keyof TItem & string,\n> = {\n\ttoConditions: (viewport: TViewport) => RangeCondition[];\n\texpandViewport: (viewport: TViewport, pad: number) => TViewport;\n\tsort: PredicateSortSpec<TSortColumn>;\n\tgetSortValue: (row: TItem, column: TSortColumn) => unknown;\n};\n\nexport type CreatePartialSyncAdapterConfig<\n\tTItem extends PartialSyncViewportItem,\n\tTViewport,\n\tTSortColumn extends keyof TItem & string,\n> = {\n\ttoConditions: (viewport: TViewport) => RangeCondition[];\n\t/** Widen viewport before server `rangeQuery`. Default: identity (no prefetch). */\n\texpandViewport?: (viewport: TViewport, pad: number) => TViewport;\n\tsort: PredicateSortSpec<TSortColumn>;\n\tgetSortValue: (row: TItem, column: TSortColumn) => unknown;\n};\n\nexport function createPartialSyncAdapter<\n\tTItem extends PartialSyncViewportItem,\n\tTViewport,\n\tTSortColumn extends keyof TItem & string,\n>(\n\tconfig: CreatePartialSyncAdapterConfig<TItem, TViewport, TSortColumn>,\n): PartialSyncViewportAdapter<TItem, TViewport, TSortColumn> {\n\treturn {\n\t\ttoConditions: config.toConditions,\n\t\texpandViewport: config.expandViewport ?? ((v) => v),\n\t\tsort: config.sort,\n\t\tgetSortValue: config.getSortValue,\n\t};\n}\n\nexport type NumericAxisSpec<TViewport> = {\n\treadonly column: string;\n\treadonly min: (viewport: TViewport) => number;\n\treadonly max: (viewport: TViewport) => number;\n};\n\n/**\n * Builds `between` {@link RangeCondition}s from numeric axis accessors (N-D box / interval per column).\n */\nexport function betweenConditionsForNumericAxes<TViewport>(\n\tviewport: TViewport,\n\taxes: readonly NumericAxisSpec<TViewport>[],\n): RangeCondition[] {\n\treturn axes.map((axis) => ({\n\t\tcolumn: axis.column,\n\t\top: \"between\" as const,\n\t\tvalue: axis.min(viewport),\n\t\tvalueTo: axis.max(viewport),\n\t}));\n}\n"]}

package/dist/chunk-BGJH6PH2.js

@@ -0,0 +1,175 @@
+import { usePredicateFilteredRows } from './chunk-YD5LVGWX.js';
+import { DEFAULT_VIEWPORT_RANGE_MAX_WAIT_MS, DEFAULT_VIEWPORT_RANGE_QUIET_MS } from './chunk-M5MJHS6A.js';
+import { useMemo, useSyncExternalStore, useRef, useEffectEvent, useLayoutEffect } from 'react';
+
+function usePartialSyncViewport({
+  bridge,
+  bridgeState,
+  collection,
+  adapter,
+  viewport,
+  predicateLimit,
+  prefetchPad = 0,
+  quietMs = DEFAULT_VIEWPORT_RANGE_QUIET_MS,
+  maxWaitMs = DEFAULT_VIEWPORT_RANGE_MAX_WAIT_MS,
+  totalCountFallback = 0,
+  getColumnValue,
+  cacheDisplayMode = "immediate",
+  alwaysIncludeRowIds,
+  onRangeReconcile
+}) {
+  const conditions = useMemo(
+    () => adapter.toConditions(viewport),
+    [adapter, viewport]
+  );
+  const confirmedKeysRevision = useSyncExternalStore(
+    (onStoreChange) => bridge.subscribeConfirmedKeysRevision(onStoreChange),
+    () => bridge.serverConfirmedKeysRevision,
+    () => 0
+  );
+  const viewportRows = usePredicateFilteredRows({
+    collection,
+    conditions,
+    sort: adapter.sort,
+    getSortValue: adapter.getSortValue,
+    ...getColumnValue !== void 0 ? { getColumnValue } : {},
+    limit: predicateLimit,
+    cacheDisplayMode,
+    ...alwaysIncludeRowIds !== void 0 && alwaysIncludeRowIds.length > 0 ? { alwaysIncludeRowIds } : {},
+    ...cacheDisplayMode === "confirmed" ? {
+      confirmedRowKeys: bridge.serverConfirmedKeys,
+      confirmedKeysRevision
+    } : {}
+  });
+  const fetchViewport = useMemo(
+    () => adapter.expandViewport(viewport, prefetchPad),
+    [adapter, prefetchPad, viewport]
+  );
+  const bridgeRef = useRef(bridge);
+  bridgeRef.current = bridge;
+  const adapterRef = useRef(adapter);
+  adapterRef.current = adapter;
+  const fetchViewportRef = useRef(fetchViewport);
+  fetchViewportRef.current = fetchViewport;
+  const predicateLimitRef = useRef(predicateLimit);
+  predicateLimitRef.current = predicateLimit;
+  const quietTimerRef = useRef(null);
+  const maxWaitTimerRef = useRef(null);
+  const lastRangeFetchAtRef = useRef(0);
+  const onRangeReconcileEvent = useEffectEvent(
+    (rec) => {
+      onRangeReconcile?.(rec);
+    }
+  );
+  const canReconcileWithManifest = useEffectEvent(() => {
+    const col = collection;
+    if (typeof col.get !== "function") return false;
+    const keys = bridge.serverConfirmedKeys;
+    if (keys.size === 0) return false;
+    for (const k of keys) {
+      let row = col.get(k);
+      if (row === void 0 && typeof k === "number") {
+        row = col.get(String(k));
+      } else if (row === void 0 && typeof k === "string") {
+        const n = Number(k);
+        if (!Number.isNaN(n)) row = col.get(n);
+      }
+      if (row !== void 0) return true;
+    }
+    return false;
+  });
+  useLayoutEffect(() => {
+    const clearQuietTimer = () => {
+      if (quietTimerRef.current !== null) {
+        clearTimeout(quietTimerRef.current);
+        quietTimerRef.current = null;
+      }
+    };
+    const clearMaxWaitTimer = () => {
+      if (maxWaitTimerRef.current !== null) {
+        clearTimeout(maxWaitTimerRef.current);
+        maxWaitTimerRef.current = null;
+      }
+    };
+    const runRangeQuery = () => {
+      clearQuietTimer();
+      clearMaxWaitTimer();
+      lastRangeFetchAtRef.current = performance.now();
+      const v = fetchViewportRef.current;
+      const ad = adapterRef.current;
+      const range = {
+        kind: "predicate",
+        conditions: ad.toConditions(v),
+        sort: ad.sort,
+        limit: predicateLimitRef.current
+      };
+      if (canReconcileWithManifest()) {
+        void bridgeRef.current.requestRangeReconcile(range).then((rec) => {
+          onRangeReconcileEvent(rec);
+        }).catch((err) => {
+          console.error("partial sync viewport rangeReconcile failed", err);
+        });
+        return;
+      }
+      void bridgeRef.current.requestRangeQuery(range).catch((err) => {
+        console.error("partial sync viewport rangeQuery failed", err);
+      });
+    };
+    clearQuietTimer();
+    clearMaxWaitTimer();
+    const now = performance.now();
+    const sinceLastFetch = now - lastRangeFetchAtRef.current;
+    const fetchImmediately = lastRangeFetchAtRef.current === 0 || sinceLastFetch >= maxWaitMs;
+    if (fetchImmediately) {
+      runRangeQuery();
+      return () => {
+        clearQuietTimer();
+        clearMaxWaitTimer();
+      };
+    }
+    quietTimerRef.current = setTimeout(runRangeQuery, quietMs);
+    maxWaitTimerRef.current = setTimeout(
+      runRangeQuery,
+      Math.max(0, maxWaitMs - sinceLastFetch)
+    );
+    return () => {
+      clearQuietTimer();
+      clearMaxWaitTimer();
+    };
+  }, [conditions, prefetchPad, maxWaitMs, quietMs]);
+  useLayoutEffect(() => {
+    if (typeof document === "undefined") return;
+    const onVisibleRefresh = () => {
+      if (document.visibilityState !== "visible") return;
+      const v = fetchViewportRef.current;
+      const ad = adapterRef.current;
+      const range = {
+        kind: "predicate",
+        conditions: ad.toConditions(v),
+        sort: ad.sort,
+        limit: predicateLimitRef.current
+      };
+      if (canReconcileWithManifest()) {
+        void bridgeRef.current.requestRangeReconcile(range).then((rec) => {
+          onRangeReconcileEvent(rec);
+        }).catch((err) => {
+          console.error("partial sync viewport rangeReconcile failed", err);
+        });
+        return;
+      }
+      void bridgeRef.current.requestRangeQuery(range).catch((err) => {
+        console.error("partial sync viewport rangeQuery failed", err);
+      });
+    };
+    document.addEventListener("visibilitychange", onVisibleRefresh);
+    return () => {
+      document.removeEventListener("visibilitychange", onVisibleRefresh);
+    };
+  }, []);
+  const totalCount = bridgeState.status === "partial" || bridgeState.status === "realtime" ? bridgeState.totalCount : totalCountFallback;
+  return { viewportRows, totalCount };
+}
+
+export { usePartialSyncViewport };
+//# sourceMappingURL=chunk-BGJH6PH2.js.map
+//# sourceMappingURL=chunk-BGJH6PH2.js.map

package/dist/chunk-BGJH6PH2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react/usePartialSyncViewport.ts"],"names":[],"mappings":"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","file":"chunk-BGJH6PH2.js","sourcesContent":["import {\n\tuseEffectEvent,\n\tuseLayoutEffect,\n\tuseMemo,\n\tuseRef,\n\tuseSyncExternalStore,\n} from \"react\";\nimport type { PartialSyncReconcileResult } from \"../partial-sync-client-bridge\";\nimport type { SyncRange } from \"../sync-protocol\";\nimport {\n\tDEFAULT_VIEWPORT_RANGE_MAX_WAIT_MS,\n\tDEFAULT_VIEWPORT_RANGE_QUIET_MS,\n} from \"./constants\";\nimport { usePredicateFilteredRows } from \"./usePredicateFilteredRows\";\nimport type {\n\tPartialSyncItem,\n\tUsePartialSyncViewportOptions,\n\tUsePartialSyncViewportResult,\n} from \"./types\";\n\n/**\n * Predicate viewport sync: debounced server `rangeQuery` for a moving logical viewport plus\n * {@link usePredicateFilteredRows} for the visible rows already in the local collection.\n */\nexport function usePartialSyncViewport<\n\tTItem extends PartialSyncItem,\n\tTViewport,\n\tTSortColumn extends keyof TItem & string,\n>({\n\tbridge,\n\tbridgeState,\n\tcollection,\n\tadapter,\n\tviewport,\n\tpredicateLimit,\n\tprefetchPad = 0,\n\tquietMs = DEFAULT_VIEWPORT_RANGE_QUIET_MS,\n\tmaxWaitMs = DEFAULT_VIEWPORT_RANGE_MAX_WAIT_MS,\n\ttotalCountFallback = 0,\n\tgetColumnValue,\n\tcacheDisplayMode = \"immediate\",\n\talwaysIncludeRowIds,\n\tonRangeReconcile,\n}: UsePartialSyncViewportOptions<\n\tTItem,\n\tTViewport,\n\tTSortColumn\n>): UsePartialSyncViewportResult<TItem> {\n\tconst conditions = useMemo(\n\t\t() => adapter.toConditions(viewport),\n\t\t[adapter, viewport],\n\t);\n\n\tconst confirmedKeysRevision = useSyncExternalStore(\n\t\t(onStoreChange) => bridge.subscribeConfirmedKeysRevision(onStoreChange),\n\t\t() => bridge.serverConfirmedKeysRevision,\n\t\t() => 0,\n\t);\n\n\tconst viewportRows = usePredicateFilteredRows({\n\t\tcollection,\n\t\tconditions,\n\t\tsort: adapter.sort,\n\t\tgetSortValue: adapter.getSortValue,\n\t\t...(getColumnValue !== undefined ? { getColumnValue } : {}),\n\t\tlimit: predicateLimit,\n\t\tcacheDisplayMode,\n\t\t...(alwaysIncludeRowIds !== undefined && alwaysIncludeRowIds.length > 0\n\t\t\t? { alwaysIncludeRowIds }\n\t\t\t: {}),\n\t\t...(cacheDisplayMode === \"confirmed\"\n\t\t\t? {\n\t\t\t\t\tconfirmedRowKeys: bridge.serverConfirmedKeys,\n\t\t\t\t\tconfirmedKeysRevision,\n\t\t\t\t}\n\t\t\t: {}),\n\t});\n\n\tconst fetchViewport = useMemo(\n\t\t() => adapter.expandViewport(viewport, prefetchPad),\n\t\t[adapter, prefetchPad, viewport],\n\t);\n\n\tconst bridgeRef = useRef(bridge);\n\tbridgeRef.current = bridge;\n\tconst adapterRef = useRef(adapter);\n\tadapterRef.current = adapter;\n\tconst fetchViewportRef = useRef(fetchViewport);\n\tfetchViewportRef.current = fetchViewport;\n\tconst predicateLimitRef = useRef(predicateLimit);\n\tpredicateLimitRef.current = predicateLimit;\n\n\tconst quietTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\tconst maxWaitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\tconst lastRangeFetchAtRef = useRef(0);\n\n\tconst onRangeReconcileEvent = useEffectEvent(\n\t\t(rec: PartialSyncReconcileResult<TItem>) => {\n\t\t\tonRangeReconcile?.(rec);\n\t\t},\n\t);\n\n\tconst canReconcileWithManifest = useEffectEvent((): boolean => {\n\t\tconst col = collection;\n\t\tif (typeof col.get !== \"function\") return false;\n\t\tconst keys = bridge.serverConfirmedKeys;\n\t\tif (keys.size === 0) return false;\n\t\tfor (const k of keys) {\n\t\t\tlet row = col.get(k);\n\t\t\tif (row === undefined && typeof k === \"number\") {\n\t\t\t\trow = col.get(String(k));\n\t\t\t} else if (row === undefined && typeof k === \"string\") {\n\t\t\t\tconst n = Number(k);\n\t\t\t\tif (!Number.isNaN(n)) row = col.get(n);\n\t\t\t}\n\t\t\tif (row !== undefined) return true;\n\t\t}\n\t\treturn false;\n\t});\n\n\tuseLayoutEffect(() => {\n\t\tconst clearQuietTimer = () => {\n\t\t\tif (quietTimerRef.current !== null) {\n\t\t\t\tclearTimeout(quietTimerRef.current);\n\t\t\t\tquietTimerRef.current = null;\n\t\t\t}\n\t\t};\n\t\tconst clearMaxWaitTimer = () => {\n\t\t\tif (maxWaitTimerRef.current !== null) {\n\t\t\t\tclearTimeout(maxWaitTimerRef.current);\n\t\t\t\tmaxWaitTimerRef.current = null;\n\t\t\t}\n\t\t};\n\n\t\tconst runRangeQuery = () => {\n\t\t\tclearQuietTimer();\n\t\t\tclearMaxWaitTimer();\n\t\t\tlastRangeFetchAtRef.current = performance.now();\n\t\t\tconst v = fetchViewportRef.current;\n\t\t\tconst ad = adapterRef.current;\n\t\t\tconst range: SyncRange = {\n\t\t\t\tkind: \"predicate\",\n\t\t\t\tconditions: ad.toConditions(v),\n\t\t\t\tsort: ad.sort,\n\t\t\t\tlimit: predicateLimitRef.current,\n\t\t\t};\n\t\t\tif (canReconcileWithManifest()) {\n\t\t\t\tvoid bridgeRef.current\n\t\t\t\t\t.requestRangeReconcile(range)\n\t\t\t\t\t.then((rec) => {\n\t\t\t\t\t\tonRangeReconcileEvent(rec);\n\t\t\t\t\t})\n\t\t\t\t\t.catch((err: unknown) => {\n\t\t\t\t\t\tconsole.error(\"partial sync viewport rangeReconcile failed\", err);\n\t\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tvoid bridgeRef.current.requestRangeQuery(range).catch((err: unknown) => {\n\t\t\t\tconsole.error(\"partial sync viewport rangeQuery failed\", err);\n\t\t\t});\n\t\t};\n\n\t\tclearQuietTimer();\n\t\tclearMaxWaitTimer();\n\n\t\tconst now = performance.now();\n\t\tconst sinceLastFetch = now - lastRangeFetchAtRef.current;\n\t\tconst fetchImmediately =\n\t\t\tlastRangeFetchAtRef.current === 0 || sinceLastFetch >= maxWaitMs;\n\n\t\tif (fetchImmediately) {\n\t\t\trunRangeQuery();\n\t\t\treturn () => {\n\t\t\t\tclearQuietTimer();\n\t\t\t\tclearMaxWaitTimer();\n\t\t\t};\n\t\t}\n\n\t\tquietTimerRef.current = setTimeout(runRangeQuery, quietMs);\n\t\tmaxWaitTimerRef.current = setTimeout(\n\t\t\trunRangeQuery,\n\t\t\tMath.max(0, maxWaitMs - sinceLastFetch),\n\t\t);\n\n\t\treturn () => {\n\t\t\tclearQuietTimer();\n\t\t\tclearMaxWaitTimer();\n\t\t};\n\t}, [conditions, prefetchPad, maxWaitMs, quietMs]);\n\n\tuseLayoutEffect(() => {\n\t\tif (typeof document === \"undefined\") return;\n\t\tconst onVisibleRefresh = (): void => {\n\t\t\tif (document.visibilityState !== \"visible\") return;\n\t\t\tconst v = fetchViewportRef.current;\n\t\t\tconst ad = adapterRef.current;\n\t\t\tconst range: SyncRange = {\n\t\t\t\tkind: \"predicate\",\n\t\t\t\tconditions: ad.toConditions(v),\n\t\t\t\tsort: ad.sort,\n\t\t\t\tlimit: predicateLimitRef.current,\n\t\t\t};\n\t\t\tif (canReconcileWithManifest()) {\n\t\t\t\tvoid bridgeRef.current\n\t\t\t\t\t.requestRangeReconcile(range)\n\t\t\t\t\t.then((rec) => {\n\t\t\t\t\t\tonRangeReconcileEvent(rec);\n\t\t\t\t\t})\n\t\t\t\t\t.catch((err: unknown) => {\n\t\t\t\t\t\tconsole.error(\"partial sync viewport rangeReconcile failed\", err);\n\t\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tvoid bridgeRef.current.requestRangeQuery(range).catch((err: unknown) => {\n\t\t\t\tconsole.error(\"partial sync viewport rangeQuery failed\", err);\n\t\t\t});\n\t\t};\n\t\tdocument.addEventListener(\"visibilitychange\", onVisibleRefresh);\n\t\treturn () => {\n\t\t\tdocument.removeEventListener(\"visibilitychange\", onVisibleRefresh);\n\t\t};\n\t}, []);\n\n\tconst totalCount =\n\t\tbridgeState.status === \"partial\" || bridgeState.status === \"realtime\"\n\t\t\t? bridgeState.totalCount\n\t\t\t: totalCountFallback;\n\n\treturn { viewportRows, totalCount };\n}\n"]}

package/dist/chunk-BJJEAKXL.js

@@ -0,0 +1,252 @@
+import { exhaustiveGuard } from '@firtoz/maybe-error';
+import { z } from 'zod';
+
+// src/sync-protocol.ts
+var DEFAULT_SYNC_COLLECTION_ID = "default";
+var collectionIdSchema = z.string().min(1).default(DEFAULT_SYNC_COLLECTION_ID);
+var mutationTypeSchema = z.enum(["insert", "update", "delete", "truncate"]);
+var mutationIntentSchema = z.object({
+  clientMutationId: z.string().min(1),
+  type: mutationTypeSchema,
+  value: z.record(z.string(), z.unknown()).optional(),
+  previousValue: z.record(z.string(), z.unknown()).optional(),
+  key: z.union([z.string(), z.number()]).optional()
+});
+var syncRangeSortSchema = z.object({
+  column: z.string().min(1),
+  direction: z.enum(["asc", "desc"])
+});
+var rangeConditionOpSchema = z.enum([
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "eq",
+  "neq",
+  "between"
+]);
+var rangeConditionSchema = z.object({
+  column: z.string().min(1),
+  op: rangeConditionOpSchema,
+  value: z.unknown(),
+  valueTo: z.unknown().optional()
+});
+var indexRangeCursorSchema = z.object({
+  kind: z.literal("index"),
+  mode: z.literal("cursor"),
+  sort: syncRangeSortSchema,
+  limit: z.number().int().positive(),
+  afterCursor: z.unknown().nullable()
+});
+var indexRangeOffsetSchema = z.object({
+  kind: z.literal("index"),
+  mode: z.literal("offset"),
+  sort: syncRangeSortSchema,
+  limit: z.number().int().positive(),
+  offset: z.number().int().nonnegative()
+});
+var predicateRangeSchema = z.object({
+  kind: z.literal("predicate"),
+  conditions: z.array(rangeConditionSchema).min(1),
+  sort: syncRangeSortSchema.optional(),
+  limit: z.number().int().positive().optional()
+});
+var syncRangeSchema = z.union([
+  indexRangeCursorSchema,
+  indexRangeOffsetSchema,
+  predicateRangeSchema
+]);
+var rangeFingerprintSchema = z.object({
+  version: z.number().int().nonnegative(),
+  count: z.number().int().nonnegative()
+});
+function createClientMessageSchema() {
+  return z.discriminatedUnion("type", [
+    z.object({
+      type: z.literal("mutateBatch"),
+      collectionId: collectionIdSchema,
+      clientId: z.string().min(1),
+      mutations: z.array(mutationIntentSchema).min(1)
+    }),
+    z.object({
+      type: z.literal("syncHello"),
+      collectionId: collectionIdSchema,
+      clientId: z.string().min(1),
+      lastAckedServerVersion: z.number().int().nonnegative()
+    }),
+    z.object({
+      type: z.literal("ping"),
+      collectionId: collectionIdSchema,
+      clientId: z.string().min(1),
+      timestamp: z.number()
+    }),
+    z.object({
+      type: z.literal("queryRange"),
+      collectionId: collectionIdSchema,
+      clientId: z.string().min(1),
+      requestId: z.string().min(1),
+      sort: z.object({
+        column: z.string().min(1),
+        direction: z.enum(["asc", "desc"])
+      }),
+      limit: z.number().int().positive(),
+      afterCursor: z.unknown().nullable()
+    }),
+    z.object({
+      type: z.literal("queryByOffset"),
+      collectionId: collectionIdSchema,
+      clientId: z.string().min(1),
+      requestId: z.string().min(1),
+      sort: z.object({
+        column: z.string().min(1),
+        direction: z.enum(["asc", "desc"])
+      }),
+      limit: z.number().int().positive(),
+      offset: z.number().int().nonnegative()
+    }),
+    z.object({
+      type: z.literal("rangeQuery"),
+      collectionId: collectionIdSchema,
+      clientId: z.string().min(1),
+      requestId: z.string().min(1),
+      range: syncRangeSchema,
+      fingerprint: rangeFingerprintSchema.optional()
+    }),
+    z.object({
+      type: z.literal("rangeReconcile"),
+      collectionId: collectionIdSchema,
+      clientId: z.string().min(1),
+      requestId: z.string().min(1),
+      range: syncRangeSchema,
+      manifest: z.array(
+        z.object({
+          id: z.union([z.string(), z.number()]),
+          version: z.number().int().nonnegative()
+        })
+      )
+    })
+  ]);
+}
+var clientMessageSchema = createClientMessageSchema();
+function createServerMessageSchema() {
+  const syncMessageSchema = z.custom();
+  return z.discriminatedUnion("type", [
+    z.object({
+      type: z.literal("ack"),
+      collectionId: collectionIdSchema,
+      clientId: z.string().min(1),
+      clientMutationIds: z.array(z.string().min(1)),
+      serverVersion: z.number().int().nonnegative(),
+      changes: z.array(syncMessageSchema)
+    }),
+    z.object({
+      type: z.literal("syncBatch"),
+      collectionId: collectionIdSchema,
+      serverVersion: z.number().int().nonnegative(),
+      changes: z.array(syncMessageSchema)
+    }),
+    z.object({
+      type: z.literal("syncBackfill"),
+      collectionId: collectionIdSchema,
+      mode: z.enum(["snapshot", "delta"]),
+      serverVersion: z.number().int().nonnegative(),
+      changes: z.array(syncMessageSchema),
+      chunkIndex: z.number().int().nonnegative().optional(),
+      totalChunks: z.number().int().positive().optional()
+    }),
+    z.object({
+      type: z.literal("reject"),
+      collectionId: collectionIdSchema,
+      clientId: z.string().min(1),
+      clientMutationId: z.string().min(1),
+      reason: z.string().min(1),
+      correctiveChanges: z.array(syncMessageSchema).default([])
+    }),
+    z.object({
+      type: z.literal("pong"),
+      collectionId: collectionIdSchema,
+      timestamp: z.number()
+    }),
+    z.object({
+      type: z.literal("queryRangeChunk"),
+      collectionId: collectionIdSchema,
+      requestId: z.string().min(1),
+      rows: z.array(z.custom()),
+      totalCount: z.number().int().nonnegative(),
+      lastCursor: z.unknown().nullable(),
+      hasMore: z.boolean(),
+      chunkIndex: z.number().int().nonnegative(),
+      done: z.boolean()
+    }),
+    z.object({
+      type: z.literal("rangePatch"),
+      collectionId: collectionIdSchema,
+      change: syncMessageSchema,
+      viewTransition: z.enum(["enterView", "exitView"]).optional()
+    }),
+    z.object({
+      type: z.literal("rangeUpToDate"),
+      collectionId: collectionIdSchema,
+      requestId: z.string().min(1),
+      totalCount: z.number().int().nonnegative()
+    }),
+    z.object({
+      type: z.literal("rangeDelta"),
+      collectionId: collectionIdSchema,
+      requestId: z.string().min(1),
+      totalCount: z.number().int().nonnegative(),
+      changes: z.array(syncMessageSchema),
+      lastCursor: z.unknown().optional()
+    }),
+    z.object({
+      type: z.literal("rangeReconcileResult"),
+      collectionId: collectionIdSchema,
+      requestId: z.string().min(1),
+      added: z.array(syncMessageSchema),
+      updated: z.array(syncMessageSchema),
+      stale: z.array(z.union([z.string(), z.number()])),
+      movedHints: z.array(
+        z.object({
+          id: z.union([z.string(), z.number()]),
+          hint: z.record(z.string(), z.unknown())
+        })
+      ),
+      totalCount: z.number().int().nonnegative()
+    })
+  ]);
+}
+function withServerCollectionId(collectionId, message) {
+  return { ...message, collectionId };
+}
+var serverMessageSchema = createServerMessageSchema();
+function toSyncMessage(intent) {
+  switch (intent.type) {
+    case "insert":
+      if (!intent.value) throw new Error("Insert intent requires value");
+      return { type: "insert", value: intent.value };
+    case "update":
+      if (!intent.value || !intent.previousValue) {
+        throw new Error("Update intent requires value and previousValue");
+      }
+      return {
+        type: "update",
+        value: intent.value,
+        previousValue: intent.previousValue
+      };
+    case "delete":
+      if (intent.key === void 0)
+        throw new Error("Delete intent requires key");
+      return { type: "delete", key: intent.key };
+    case "truncate":
+      return { type: "truncate" };
+    default:
+      exhaustiveGuard(intent.type);
+  }
+}
+function createClientMutationId(prefix = "m") {
+  return `${prefix}_${crypto.randomUUID()}`;
+}
+
+export { DEFAULT_SYNC_COLLECTION_ID, clientMessageSchema, createClientMessageSchema, createClientMutationId, createServerMessageSchema, mutationIntentSchema, serverMessageSchema, syncRangeSchema, toSyncMessage, withServerCollectionId };
+//# sourceMappingURL=chunk-BJJEAKXL.js.map
+//# sourceMappingURL=chunk-BJJEAKXL.js.map