@terreno/syncdb 57.4.0 → 57.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +3 -3
  2. package/dist/auth/betterAuthAdapter.js +1 -1
  3. package/dist/auth/betterAuthAdapter.js.map +1 -1
  4. package/dist/client.d.ts.map +1 -1
  5. package/dist/client.js +43 -8
  6. package/dist/client.js.map +1 -1
  7. package/dist/client.test.js +77 -11
  8. package/dist/client.test.js.map +1 -1
  9. package/dist/crypto/keyProviders.js +1 -1
  10. package/dist/crypto/keyProviders.js.map +1 -1
  11. package/dist/debug/devtools.d.ts +6 -0
  12. package/dist/debug/devtools.d.ts.map +1 -0
  13. package/dist/debug/devtools.js +111 -0
  14. package/dist/debug/devtools.js.map +1 -0
  15. package/dist/debug/devtools.test.d.ts +2 -0
  16. package/dist/debug/devtools.test.d.ts.map +1 -0
  17. package/dist/debug/devtools.test.js +168 -0
  18. package/dist/debug/devtools.test.js.map +1 -0
  19. package/dist/react/collectionHooks.js +2 -2
  20. package/dist/react/collectionHooks.js.map +1 -1
  21. package/dist/storage/store.test.js +6 -6
  22. package/dist/storage/store.test.js.map +1 -1
  23. package/dist/sync/replayCoordinator.d.ts.map +1 -1
  24. package/dist/sync/replayCoordinator.js +36 -15
  25. package/dist/sync/replayCoordinator.js.map +1 -1
  26. package/dist/sync/replayCoordinator.test.js +29 -10
  27. package/dist/sync/replayCoordinator.test.js.map +1 -1
  28. package/dist/sync/socketTransport.d.ts.map +1 -1
  29. package/dist/sync/socketTransport.js +44 -2
  30. package/dist/sync/socketTransport.js.map +1 -1
  31. package/dist/sync/socketTransport.test.js +34 -1
  32. package/dist/sync/socketTransport.test.js.map +1 -1
  33. package/dist/sync/transport.d.ts +6 -0
  34. package/dist/sync/transport.d.ts.map +1 -1
  35. package/dist/sync/transport.js +1 -1
  36. package/dist/sync/transport.js.map +1 -1
  37. package/package.json +9 -4
  38. package/src/client.test.ts +74 -2
  39. package/src/client.ts +40 -5
  40. package/src/debug/devtools.test.ts +234 -0
  41. package/src/debug/devtools.ts +196 -0
  42. package/src/react/collectionHooks.ts +2 -2
  43. package/src/sync/replayCoordinator.test.ts +28 -0
  44. package/src/sync/replayCoordinator.ts +43 -11
  45. package/src/sync/socketTransport.test.ts +35 -0
  46. package/src/sync/socketTransport.ts +44 -0
  47. package/src/sync/transport.ts +6 -0
@@ -0,0 +1,196 @@
1
+ import {DateTime} from "luxon";
2
+ import type {MergeableContent} from "tinybase";
3
+
4
+ import type {SyncDb} from "../client";
5
+ import {listConflicts} from "../mutations/conflicts";
6
+ import {CURSORS_TABLE, KNOWN_STREAMS_TABLE, OUTBOX_TABLE} from "../storage/types";
7
+ import type {ConflictResolutionStrategy, SyncMutationOperation} from "../types";
8
+
9
+ const DEFAULT_ENTITY_LIMIT = 500;
10
+ const MAX_ENTITY_LIMIT = 2_000;
11
+
12
+ interface SyncDbDevtoolsInspectOptions {
13
+ collection?: string;
14
+ entityId?: string;
15
+ includeDebugEvents?: boolean;
16
+ limit?: number;
17
+ }
18
+
19
+ interface SyncDbDevtoolsMutation {
20
+ collection: string;
21
+ operation: SyncMutationOperation;
22
+ id?: string;
23
+ data?: Record<string, unknown>;
24
+ maxAttempts?: number;
25
+ }
26
+
27
+ interface SyncDbDevtoolsState {
28
+ capturedAt: string;
29
+ name: string;
30
+ status: ReturnType<SyncDb["getSyncStatus"]>;
31
+ collections: Record<
32
+ string,
33
+ {
34
+ entities: ReturnType<SyncDb["store"]["listEntities"]>;
35
+ total: number;
36
+ truncated: boolean;
37
+ }
38
+ >;
39
+ outbox: Record<string, unknown>;
40
+ conflicts: ReturnType<typeof listConflicts>;
41
+ cursors: Record<string, unknown>;
42
+ knownStreams: Record<string, unknown>;
43
+ needsRepair: ReturnType<SyncDb["store"]["listNeedsRepair"]>;
44
+ values: Record<string, unknown>;
45
+ debug?: ReturnType<NonNullable<SyncDb["debug"]>["snapshot"]>;
46
+ }
47
+
48
+ interface SyncDbDevtoolsSnapshot extends SyncDbDevtoolsState {
49
+ mergeableContent: unknown;
50
+ }
51
+
52
+ interface SyncDbDevtoolsClient {
53
+ inspect: (options?: SyncDbDevtoolsInspectOptions) => SyncDbDevtoolsState;
54
+ snapshot: (options?: SyncDbDevtoolsInspectOptions) => SyncDbDevtoolsSnapshot;
55
+ mutate: (args: SyncDbDevtoolsMutation) => ReturnType<SyncDb["mutate"]>;
56
+ setLocalEntity: (args: {
57
+ collection: string;
58
+ id: string;
59
+ data: unknown;
60
+ deleted?: boolean;
61
+ seq?: number;
62
+ stream?: string;
63
+ }) => void;
64
+ deleteLocalEntity: (args: {collection: string; id: string}) => void;
65
+ merge: (content: unknown) => void;
66
+ flush: () => Promise<void>;
67
+ reconcile: () => Promise<void>;
68
+ forceResync: () => ReturnType<SyncDb["forceResync"]>;
69
+ resolveConflict: (args: {mutationId: string; strategy: ConflictResolutionStrategy}) => void;
70
+ retryFailed: (args: {entityId: string}) => void;
71
+ goOffline: () => void;
72
+ goOnline: () => Promise<void>;
73
+ clearDebug: () => void;
74
+ }
75
+
76
+ interface SyncDbDevtoolsRegistry {
77
+ clients: Record<string, SyncDbDevtoolsClient>;
78
+ list: () => string[];
79
+ }
80
+
81
+ const getRegistry = (): SyncDbDevtoolsRegistry => {
82
+ const globalWithRegistry = globalThis as typeof globalThis & {
83
+ __TERRENO_SYNCDB__?: SyncDbDevtoolsRegistry;
84
+ };
85
+ if (!globalWithRegistry.__TERRENO_SYNCDB__) {
86
+ const clients: Record<string, SyncDbDevtoolsClient> = {};
87
+ globalWithRegistry.__TERRENO_SYNCDB__ = {
88
+ clients,
89
+ list: (): string[] => Object.keys(clients).sort(),
90
+ };
91
+ }
92
+ return globalWithRegistry.__TERRENO_SYNCDB__;
93
+ };
94
+
95
+ const decodeOutbox = (rows: Record<string, unknown>): Record<string, unknown> => {
96
+ return Object.fromEntries(
97
+ Object.entries(rows).map(([mutationId, value]) => {
98
+ const row =
99
+ typeof value === "object" && value !== null ? (value as Record<string, unknown>) : {value};
100
+ let args: unknown = row.args;
101
+ if (typeof row.args === "string") {
102
+ try {
103
+ args = JSON.parse(row.args);
104
+ } catch {
105
+ args = row.args;
106
+ }
107
+ }
108
+ return [mutationId, {...row, args}];
109
+ })
110
+ );
111
+ };
112
+
113
+ export const registerSyncDbDevtools = ({client, name}: {client: SyncDb; name: string}): void => {
114
+ const inspect = (options: SyncDbDevtoolsInspectOptions = {}): SyncDbDevtoolsState => {
115
+ const limit = Math.min(Math.max(options.limit ?? DEFAULT_ENTITY_LIMIT, 1), MAX_ENTITY_LIMIT);
116
+ const selectedCollections = options.collection
117
+ ? [options.collection]
118
+ : [...client.store.collections];
119
+ const collections: SyncDbDevtoolsState["collections"] = {};
120
+
121
+ for (const collection of selectedCollections) {
122
+ const allEntities = options.entityId
123
+ ? [
124
+ client.store.getEntity({
125
+ collection,
126
+ id: options.entityId,
127
+ }),
128
+ ].filter((entity) => entity !== undefined)
129
+ : client.store.listEntities({collection, includeDeleted: true});
130
+ collections[collection] = {
131
+ entities: allEntities.slice(0, limit),
132
+ total: allEntities.length,
133
+ truncated: allEntities.length > limit,
134
+ };
135
+ }
136
+
137
+ return {
138
+ capturedAt: DateTime.utc().toISO(),
139
+ collections,
140
+ conflicts: listConflicts({store: client.store}),
141
+ cursors: client.store.raw.getTable(CURSORS_TABLE),
142
+ ...(client.debug
143
+ ? {
144
+ debug:
145
+ options.includeDebugEvents === false
146
+ ? {
147
+ ...client.debug.snapshot(),
148
+ events: [],
149
+ }
150
+ : client.debug.snapshot(),
151
+ }
152
+ : {}),
153
+ knownStreams: client.store.raw.getTable(KNOWN_STREAMS_TABLE),
154
+ name,
155
+ needsRepair: client.store.listNeedsRepair(),
156
+ outbox: decodeOutbox(client.store.raw.getTable(OUTBOX_TABLE)),
157
+ status: client.getSyncStatus(),
158
+ values: client.store.raw.getValues(),
159
+ };
160
+ };
161
+
162
+ const devtoolsClient: SyncDbDevtoolsClient = {
163
+ clearDebug: (): void => {
164
+ client.debug?.clear();
165
+ },
166
+ deleteLocalEntity: ({collection, id}): void => {
167
+ if (!client.store.collections.includes(collection)) {
168
+ throw new Error(`Unknown collection "${collection}".`);
169
+ }
170
+ client.store.raw.delRow(collection, id);
171
+ },
172
+ flush: async (): Promise<void> => {
173
+ await client.replayOutbox();
174
+ },
175
+ forceResync: client.forceResync,
176
+ goOffline: client.goOffline,
177
+ goOnline: client.goOnline,
178
+ inspect,
179
+ merge: (content): void => {
180
+ client.store.raw.applyMergeableChanges(content as MergeableContent);
181
+ },
182
+ mutate: client.mutate,
183
+ reconcile: client.reconcile,
184
+ resolveConflict: client.resolveConflict,
185
+ retryFailed: client.retryFailed,
186
+ setLocalEntity: ({collection, id, data, deleted, seq, stream}): void => {
187
+ client.store.upsertEntity({collection, data, deleted, id, seq, stream});
188
+ },
189
+ snapshot: (options = {}): SyncDbDevtoolsSnapshot => ({
190
+ ...inspect(options),
191
+ mergeableContent: client.store.raw.getMergeableContent(),
192
+ }),
193
+ };
194
+
195
+ getRegistry().clients[name] = devtoolsClient;
196
+ };
@@ -75,7 +75,7 @@ export const createCollectionHooks = <
75
75
  id: args.id,
76
76
  ...(maxAttempts !== undefined ? {maxAttempts} : {}),
77
77
  }),
78
- [maxAttempts, update]
78
+ [update]
79
79
  );
80
80
  return useMemo(() => [trigger], [trigger]);
81
81
  };
@@ -88,7 +88,7 @@ export const createCollectionHooks = <
88
88
  id: args.id,
89
89
  ...(maxAttempts !== undefined ? {maxAttempts} : {}),
90
90
  }),
91
- [maxAttempts, remove]
91
+ [remove]
92
92
  );
93
93
  return useMemo(() => [trigger], [trigger]);
94
94
  };
@@ -167,6 +167,34 @@ describe("createReplayCoordinator", () => {
167
167
  expect(entity?.data).toEqual({title: "t1"});
168
168
  });
169
169
 
170
+ it("ignores an ack that resolves after its replay lifecycle is reset", async () => {
171
+ const harness = makeHarness();
172
+ enqueue(harness, {entityId: "t1", mutationId: "m1"});
173
+ let resolveResponse:
174
+ | ((result: {ack: {id: string; mutationId: string; seq: number}; type: "ack"}) => void)
175
+ | undefined;
176
+ harness.transport.respondWith(
177
+ (request) =>
178
+ new Promise((resolve) => {
179
+ resolveResponse = resolve;
180
+ expect(request.mutationId).toBe("m1");
181
+ })
182
+ );
183
+
184
+ const replay = harness.coordinator.replay({userId: USER});
185
+ await Promise.resolve();
186
+ expect(resolveResponse).toBeDefined();
187
+
188
+ // A lifecycle boundary can reset replay state while an HTTP request is still
189
+ // pending; the mutation can subsequently be restored to queued for a retry.
190
+ harness.coordinator.reset();
191
+ harness.outbox.markQueued({mutationId: "m1"});
192
+ resolveResponse?.({ack: {id: "t1", mutationId: "m1", seq: 42}, type: "ack"});
193
+
194
+ await replay;
195
+ expect(harness.outbox.getMutation({mutationId: "m1"})?.status).toBe("queued");
196
+ });
197
+
170
198
  it("does not clear a pendingMutationId owned by a newer mutation", async () => {
171
199
  const harness = makeHarness();
172
200
  enqueue(harness, {entityId: "t1", mutationId: "m1"});
@@ -256,6 +256,10 @@ export const createReplayCoordinator = ({
256
256
  shouldDrain = () => true,
257
257
  }: CreateReplayCoordinatorArgs): ReplayCoordinator => {
258
258
  const inFlightReplays = new Map<string, Promise<ReplayResult>>();
259
+ // Every reset is a lifecycle boundary (stop, sign-out, or user switch). A
260
+ // send that settles after one must never apply its old outcome to the
261
+ // current store/outbox, even if its mutation row was restored to queued.
262
+ let lifecycleEpoch = 0;
259
263
  /**
260
264
  * Set when a `replay()` call coalesces into an already-running drain whose
261
265
  * final pass may have already observed the queue as empty (a narrow race:
@@ -853,7 +857,11 @@ export const createReplayCoordinator = ({
853
857
  * batching is marked unsupported for this connection, or a chunk's only
854
858
  * eligible mutation count is 1).
855
859
  */
856
- const sendSingle = async (userId: string, mutation: OutboxMutation): Promise<OutcomeDecision> => {
860
+ const sendSingle = async (
861
+ userId: string,
862
+ mutation: OutboxMutation,
863
+ replayEpoch: number
864
+ ): Promise<OutcomeDecision> => {
857
865
  outbox.markInFlight({mutationId: mutation.mutationId});
858
866
  debug?.record({
859
867
  collection: mutation.collection,
@@ -869,10 +877,16 @@ export const createReplayCoordinator = ({
869
877
  try {
870
878
  result = await sendMutation(buildRequest(mutation));
871
879
  } catch (error) {
880
+ if (replayEpoch !== lifecycleEpoch) {
881
+ return {authPaused: false, haltDrain: true, progressed: false};
882
+ }
872
883
  const decision = applyTransportError(mutation, error);
873
884
  reportProgress(userId, 1);
874
885
  return decision;
875
886
  }
887
+ if (replayEpoch !== lifecycleEpoch) {
888
+ return {authPaused: false, haltDrain: true, progressed: false};
889
+ }
876
890
  const decision = applyResult(mutation, result);
877
891
  reportProgress(userId, 1);
878
892
  return decision;
@@ -952,13 +966,16 @@ export const createReplayCoordinator = ({
952
966
  /** Send one chunk as a batch; returns the per-mutation outcome decisions and any halt reached. */
953
967
  const sendChunk = async (
954
968
  userId: string,
955
- chunk: OutboxMutation[]
969
+ chunk: OutboxMutation[],
970
+ replayEpoch: number
956
971
  ): Promise<{
957
972
  decisions: Map<string, OutcomeDecision>;
958
973
  unsupported: boolean;
959
974
  haltedAt?: number;
960
975
  /** True when the server returned fewer results than mutations sent. */
961
976
  shortResponse: boolean;
977
+ /** True when a reset invalidated this request while it was awaiting a response. */
978
+ superseded: boolean;
962
979
  }> => {
963
980
  const decisions = new Map<string, OutcomeDecision>();
964
981
  for (const mutation of chunk) {
@@ -980,6 +997,9 @@ export const createReplayCoordinator = ({
980
997
  // biome-ignore lint/style/noNonNullAssertion: caller only invokes sendChunk when sendMutationBatch is defined and batching is not marked unsupported.
981
998
  response = await sendMutationBatch!(request);
982
999
  } catch (error) {
1000
+ if (replayEpoch !== lifecycleEpoch) {
1001
+ return {decisions, shortResponse: false, superseded: true, unsupported: false};
1002
+ }
983
1003
  // Transport failure for the WHOLE chunk: every mutation in it goes back
984
1004
  // to queued via the same transport-error handling as a single send, and
985
1005
  // the drain halts (INV-3 — resending the whole chunk is safe).
@@ -993,7 +1013,10 @@ export const createReplayCoordinator = ({
993
1013
  }
994
1014
  }
995
1015
  reportProgress(userId, chunk.length);
996
- return {decisions, haltedAt, shortResponse: false, unsupported: false};
1016
+ return {decisions, haltedAt, shortResponse: false, superseded: false, unsupported: false};
1017
+ }
1018
+ if (replayEpoch !== lifecycleEpoch) {
1019
+ return {decisions, shortResponse: false, superseded: true, unsupported: false};
997
1020
  }
998
1021
  if (response.type === "unsupported") {
999
1022
  // The chunk was marked inFlight before sending (for diagnostics/debug
@@ -1003,7 +1026,7 @@ export const createReplayCoordinator = ({
1003
1026
  for (const mutation of chunk) {
1004
1027
  outbox.markQueued({mutationId: mutation.mutationId});
1005
1028
  }
1006
- return {decisions, shortResponse: false, unsupported: true};
1029
+ return {decisions, shortResponse: false, superseded: false, unsupported: true};
1007
1030
  }
1008
1031
  // Walk results in order (INV-1), applying the same per-outcome handlers as
1009
1032
  // the single-send path, then the B4 stop-the-line policy. Per B2, the
@@ -1046,10 +1069,10 @@ export const createReplayCoordinator = ({
1046
1069
  }
1047
1070
  }
1048
1071
  reportProgress(userId, processed);
1049
- return {decisions, haltedAt, shortResponse, unsupported: false};
1072
+ return {decisions, haltedAt, shortResponse, superseded: false, unsupported: false};
1050
1073
  };
1051
1074
 
1052
- const drainOnce = async (userId: string): Promise<DrainPassResult> => {
1075
+ const drainOnce = async (userId: string, replayEpoch: number): Promise<DrainPassResult> => {
1053
1076
  let progressed = false;
1054
1077
  let nextWakeAt: number | undefined;
1055
1078
 
@@ -1083,7 +1106,7 @@ export const createReplayCoordinator = ({
1083
1106
  if (blockedKeys.has(entityKey(mutation.collection, mutation.entityId))) {
1084
1107
  continue;
1085
1108
  }
1086
- const decision = await sendSingle(userId, mutation);
1109
+ const decision = await sendSingle(userId, mutation, replayEpoch);
1087
1110
  sentAny = true;
1088
1111
  progressed = progressed || decision.progressed;
1089
1112
  if (decision.authPaused) {
@@ -1142,7 +1165,7 @@ export const createReplayCoordinator = ({
1142
1165
  // A lone eligible mutation: sending it as a "batch of one" adds no
1143
1166
  // value and costs an extra round-trip on unsupported servers — reuse
1144
1167
  // the single-send path directly (still counts as this pass's send).
1145
- const decision = await sendSingle(userId, chunk[0]);
1168
+ const decision = await sendSingle(userId, chunk[0], replayEpoch);
1146
1169
  progressed = progressed || decision.progressed;
1147
1170
  if (decision.authPaused) {
1148
1171
  return {authPaused: true, progressed};
@@ -1164,7 +1187,14 @@ export const createReplayCoordinator = ({
1164
1187
  continue;
1165
1188
  }
1166
1189
 
1167
- const {decisions, unsupported, haltedAt, shortResponse} = await sendChunk(userId, chunk);
1190
+ const {decisions, unsupported, haltedAt, shortResponse, superseded} = await sendChunk(
1191
+ userId,
1192
+ chunk,
1193
+ replayEpoch
1194
+ );
1195
+ if (superseded) {
1196
+ return {authPaused: false, progressed, stopReplayCall: true};
1197
+ }
1168
1198
  if (unsupported) {
1169
1199
  // FIX 5: only latch after BATCH_UNSUPPORTED_LATCH_THRESHOLD
1170
1200
  // consecutive unsupported results — a single slow-but-supported
@@ -1236,6 +1266,7 @@ export const createReplayCoordinator = ({
1236
1266
  // A fresh replay call supersedes any pending timed wake-up — it is about
1237
1267
  // to drain right now.
1238
1268
  clearWakeTimer(userId);
1269
+ const replayEpoch = lifecycleEpoch;
1239
1270
  // B5: (re)start this call's progress counters. `total` is a lower bound —
1240
1271
  // snapshotted once at entry — since more may enqueue mid-drain; onProgress
1241
1272
  // still reports every attempt made.
@@ -1250,10 +1281,10 @@ export const createReplayCoordinator = ({
1250
1281
  // the host may have gone offline or paused — an internally-scheduled
1251
1282
  // continuation must never race past that.
1252
1283
  for (;;) {
1253
- if (!shouldDrain()) {
1284
+ if (replayEpoch !== lifecycleEpoch || !shouldDrain()) {
1254
1285
  break;
1255
1286
  }
1256
- const pass = await drainOnce(userId);
1287
+ const pass = await drainOnce(userId, replayEpoch);
1257
1288
  if (pass.progressed) {
1258
1289
  onDrainPass?.({userId});
1259
1290
  }
@@ -1306,6 +1337,7 @@ export const createReplayCoordinator = ({
1306
1337
 
1307
1338
  /** FIX 3: full lifecycle reset — see the `ReplayCoordinator.reset` doc comment. */
1308
1339
  const reset = (): void => {
1340
+ lifecycleEpoch += 1;
1309
1341
  for (const userId of [...wakeTimers.keys()]) {
1310
1342
  clearWakeTimer(userId);
1311
1343
  }
@@ -349,6 +349,41 @@ describe("createSocketTransport", () => {
349
349
  expect(seen).toHaveLength(1);
350
350
  });
351
351
 
352
+ it("coalesces deltas delivered across tasks until the next animation frame", async () => {
353
+ const originalRequestAnimationFrame = globalThis.requestAnimationFrame;
354
+ let flushFrame: FrameRequestCallback | undefined;
355
+ globalThis.requestAnimationFrame = (callback: FrameRequestCallback): number => {
356
+ flushFrame = callback;
357
+ return 1;
358
+ };
359
+ try {
360
+ const receiver = makeTransport();
361
+ const batches: SyncDelta[][] = [];
362
+ receiver.onDeltaBatch?.((deltas) => batches.push(deltas));
363
+ await receiver.connect();
364
+
365
+ const first: SyncDelta = {
366
+ collection: "todos",
367
+ data: {title: "first"},
368
+ id: "t1",
369
+ method: "create",
370
+ seq: 1,
371
+ stream: "todos|owner:u1",
372
+ };
373
+ const second: SyncDelta = {...first, data: {title: "second"}, id: "t2", seq: 2};
374
+ server.sockets[0]?.emit("sync:delta", first);
375
+ await waitUntil(() => flushFrame !== undefined);
376
+ server.sockets[0]?.emit("sync:delta", second);
377
+ await new Promise((resolve) => setTimeout(resolve, 20));
378
+
379
+ expect(batches).toEqual([]);
380
+ flushFrame?.(0);
381
+ expect(batches).toEqual([[first, second]]);
382
+ } finally {
383
+ globalThis.requestAnimationFrame = originalRequestAnimationFrame;
384
+ }
385
+ });
386
+
352
387
  it("sendMutationBatch resolves results from the Socket.io ack callback (FIX 5)", async () => {
353
388
  server.mutateBatchHandler = (request, socket, ack) => {
354
389
  socket.emit("sync:batchReceived", {batchId: request.batchId});
@@ -109,6 +109,7 @@ export const createSocketTransport = ({
109
109
  }: SocketTransportConfig): SyncTransport => {
110
110
  const deltaListeners = new Set<(delta: SyncDelta) => void>();
111
111
  const subscribedListeners = new Set<(subscribed: SyncSubscribed) => void>();
112
+ const deltaBatchListeners = new Set<(deltas: SyncDelta[]) => void>();
112
113
  const statusListeners = new Set<(status: TransportStatus) => void>();
113
114
  const pending = new Map<string, PendingMutation>();
114
115
  const pendingBatches = new Map<
@@ -127,6 +128,33 @@ export const createSocketTransport = ({
127
128
  let nextBatchId = 1;
128
129
  const subscribed = new Set<string>();
129
130
  const subscribeMode = new Map<string, "window">();
131
+ const inboundDeltaBatches = new Map<(deltas: SyncDelta[]) => void, SyncDelta[]>();
132
+ let isInboundDeltaBatchScheduled = false;
133
+
134
+ const scheduleInboundDeltaBatchFlush = (): void => {
135
+ if (isInboundDeltaBatchScheduled) {
136
+ return;
137
+ }
138
+ isInboundDeltaBatchScheduled = true;
139
+ // Socket.IO can deliver a high-volume stream in separate tasks. Deferring to
140
+ // the next paint coalesces that stream into one store transaction, so React
141
+ // does not render once per delta. Non-DOM environments retain microtask
142
+ // semantics for SSR and transport tests.
143
+ if (typeof globalThis.requestAnimationFrame === "function") {
144
+ globalThis.requestAnimationFrame(flushInboundDeltaBatch);
145
+ return;
146
+ }
147
+ queueMicrotask(flushInboundDeltaBatch);
148
+ };
149
+
150
+ const flushInboundDeltaBatch = (): void => {
151
+ isInboundDeltaBatchScheduled = false;
152
+ const batches = [...inboundDeltaBatches];
153
+ inboundDeltaBatches.clear();
154
+ for (const [listener, deltas] of batches) {
155
+ listener(deltas);
156
+ }
157
+ };
130
158
 
131
159
  const socket: Socket = io(baseUrl, {
132
160
  auth: (callback) => {
@@ -191,6 +219,15 @@ export const createSocketTransport = ({
191
219
  for (const listener of deltaListeners) {
192
220
  listener(delta);
193
221
  }
222
+ if (deltaBatchListeners.size === 0) {
223
+ return;
224
+ }
225
+ for (const listener of deltaBatchListeners) {
226
+ const batch = inboundDeltaBatches.get(listener) ?? [];
227
+ batch.push(delta);
228
+ inboundDeltaBatches.set(listener, batch);
229
+ }
230
+ scheduleInboundDeltaBatchFlush();
194
231
  });
195
232
  socket.on(
196
233
  "sync:subscribed",
@@ -429,6 +466,13 @@ export const createSocketTransport = ({
429
466
  deltaListeners.delete(callback);
430
467
  };
431
468
  },
469
+ onDeltaBatch: (callback: (deltas: SyncDelta[]) => void): (() => void) => {
470
+ deltaBatchListeners.add(callback);
471
+ return () => {
472
+ deltaBatchListeners.delete(callback);
473
+ inboundDeltaBatches.delete(callback);
474
+ };
475
+ },
432
476
  onStatusChange: (callback: (status: TransportStatus) => void): (() => void) => {
433
477
  statusListeners.add(callback);
434
478
  return () => {
@@ -78,6 +78,12 @@ export interface SyncTransport {
78
78
  * doubles) satisfy the contract; callers must treat its absence as "never confirmed".
79
79
  */
80
80
  onSubscribed?: (callback: (subscribed: SyncSubscribed) => void) => () => void;
81
+ /**
82
+ * Optional burst-aware inbound subscription. Transports that receive rapid
83
+ * `sync:delta` events can deliver one arrival-ordered batch so the client
84
+ * commits it atomically. `onDelta` remains the compatibility path.
85
+ */
86
+ onDeltaBatch?: (callback: (deltas: SyncDelta[]) => void) => () => void;
81
87
  /** Subscribe to connection status changes. Returns an unsubscribe function. */
82
88
  onStatusChange: (callback: (status: TransportStatus) => void) => () => void;
83
89
  }