@baukit/sync-client 0.18.3 → 0.19.0

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 (45) hide show
  1. package/dist/browser.d.ts.map +1 -1
  2. package/dist/browser.js +9 -7
  3. package/dist/browser.js.map +1 -1
  4. package/dist/conformance-cases.d.ts +4 -0
  5. package/dist/conformance-cases.d.ts.map +1 -0
  6. package/dist/conformance-cases.js +242 -0
  7. package/dist/conformance-cases.js.map +1 -0
  8. package/dist/conformance-kit.d.ts +23 -0
  9. package/dist/conformance-kit.d.ts.map +1 -0
  10. package/dist/conformance-kit.js +85 -0
  11. package/dist/conformance-kit.js.map +1 -0
  12. package/dist/conformance-resync-cases.d.ts +4 -0
  13. package/dist/conformance-resync-cases.d.ts.map +1 -0
  14. package/dist/conformance-resync-cases.js +143 -0
  15. package/dist/conformance-resync-cases.js.map +1 -0
  16. package/dist/conformance-support.d.ts +17 -0
  17. package/dist/conformance-support.d.ts.map +1 -0
  18. package/dist/conformance-support.js +62 -0
  19. package/dist/conformance-support.js.map +1 -0
  20. package/dist/conformance.d.ts.map +1 -1
  21. package/dist/conformance.js +6 -437
  22. package/dist/conformance.js.map +1 -1
  23. package/dist/expo.d.ts.map +1 -1
  24. package/dist/expo.js +3 -2
  25. package/dist/expo.js.map +1 -1
  26. package/dist/push-batch.js +1 -1
  27. package/dist/push-batch.js.map +1 -1
  28. package/dist/timer-handles.d.ts +12 -0
  29. package/dist/timer-handles.d.ts.map +1 -0
  30. package/dist/timer-handles.js +19 -0
  31. package/dist/timer-handles.js.map +1 -0
  32. package/dist/transport.js +1 -1
  33. package/dist/transport.js.map +1 -1
  34. package/package.json +3 -3
  35. package/src/browser.ts +11 -8
  36. package/src/conformance-cases.ts +496 -0
  37. package/src/conformance-kit.ts +159 -0
  38. package/src/conformance-resync-cases.ts +378 -0
  39. package/src/conformance-support.ts +91 -0
  40. package/src/conformance.ts +6 -671
  41. package/src/expo.ts +6 -6
  42. package/src/push-batch.ts +1 -1
  43. package/src/timer-handles.test.ts +33 -0
  44. package/src/timer-handles.ts +31 -0
  45. package/src/transport.ts +1 -1
@@ -0,0 +1,496 @@
1
+ import type { SyncConformanceTestCase } from './conformance.js';
2
+ import type { SyncConformanceKit } from './conformance-kit.js';
3
+ import {
4
+ assert,
5
+ change,
6
+ childChange,
7
+ expectFailure,
8
+ parentChange,
9
+ sameRows,
10
+ tombstone,
11
+ } from './conformance-support.js';
12
+
13
+ export function coreSyncConformanceCases<
14
+ TClient,
15
+ TServer,
16
+ TPending,
17
+ TPushRequest,
18
+ TPushResponse,
19
+ TPullResponse,
20
+ TRemoteChange,
21
+ TCursor,
22
+ >(
23
+ kit: SyncConformanceKit<
24
+ TClient,
25
+ TServer,
26
+ TPending,
27
+ TPushRequest,
28
+ TPushResponse,
29
+ TPullResponse,
30
+ TRemoteChange,
31
+ TCursor
32
+ >,
33
+ ): SyncConformanceTestCase[] {
34
+ return [
35
+ ...replayCases(kit),
36
+ ...cursorCases(kit),
37
+ ...pullValidationCases(kit),
38
+ ...submissionOrderingCases(kit),
39
+ ...failureCases(kit),
40
+ ...rejectionCases(kit),
41
+ ...convergenceCases(kit),
42
+ ];
43
+ }
44
+
45
+ function replayCases<
46
+ TClient,
47
+ TServer,
48
+ TPending,
49
+ TPushRequest,
50
+ TPushResponse,
51
+ TPullResponse,
52
+ TRemoteChange,
53
+ TCursor,
54
+ >(
55
+ kit: SyncConformanceKit<
56
+ TClient,
57
+ TServer,
58
+ TPending,
59
+ TPushRequest,
60
+ TPushResponse,
61
+ TPullResponse,
62
+ TRemoteChange,
63
+ TCursor
64
+ >,
65
+ ): SyncConformanceTestCase[] {
66
+ const { adapter, inScenario, pending } = kit;
67
+ return [
68
+ {
69
+ name: 'replayed pushes create one server change',
70
+ run: () =>
71
+ inScenario(async ({ clientA, server }) => {
72
+ await adapter.outbox.enqueue(clientA, change('change-replay', 'replay', 10, 'once'));
73
+ const submitted = await pending(clientA);
74
+ const request = await adapter.wire.encodePush(submitted);
75
+ const first = await adapter.server.acceptPush(server, request);
76
+ const second = await adapter.server.acceptPush(server, request);
77
+ await adapter.wire.decodePush(first, submitted);
78
+ await adapter.wire.decodePush(second, submitted);
79
+ const rows = (await adapter.server.snapshot(server)).filter(
80
+ (row) => row.entityType === 'record' && row.entityId === 'replay',
81
+ );
82
+ assert(rows.length === 1, 'replay created a duplicate server row');
83
+ }),
84
+ },
85
+ ];
86
+ }
87
+
88
+ function cursorCases<
89
+ TClient,
90
+ TServer,
91
+ TPending,
92
+ TPushRequest,
93
+ TPushResponse,
94
+ TPullResponse,
95
+ TRemoteChange,
96
+ TCursor,
97
+ >(
98
+ kit: SyncConformanceKit<
99
+ TClient,
100
+ TServer,
101
+ TPending,
102
+ TPushRequest,
103
+ TPushResponse,
104
+ TPullResponse,
105
+ TRemoteChange,
106
+ TCursor
107
+ >,
108
+ ): SyncConformanceTestCase[] {
109
+ const { adapter, inScenario, assertPendingState, pullPage, pullAll } = kit;
110
+ return [
111
+ {
112
+ name: 'an interrupted local transaction preserves data, cursor, and pending work',
113
+ run: () =>
114
+ inScenario(async ({ clientA, server }) => {
115
+ await adapter.outbox.enqueue(clientA, change('change-pending', 'pending', 30, 'local'));
116
+ await adapter.server.seed(server, change('seed-first', 'first', 10, 'remote first'));
117
+ await adapter.server.seed(server, change('seed-second', 'second', 20, 'remote second'));
118
+ const cursorBefore = await adapter.local.readCursor(clientA);
119
+ const rowsBefore = await adapter.local.snapshot(clientA);
120
+ await expectFailure(
121
+ () => pullPage(clientA, server, { failAfterChanges: 1 }).then(() => undefined),
122
+ 'local apply failure resolved successfully',
123
+ );
124
+ const cursorAfter = await adapter.local.readCursor(clientA);
125
+ const rowsAfter = await adapter.local.snapshot(clientA);
126
+ assert(
127
+ adapter.wire.compareCursors(cursorAfter, cursorBefore) === 0,
128
+ 'local apply failure advanced the cursor',
129
+ );
130
+ assert(sameRows(rowsAfter, rowsBefore), 'local apply failure committed part of the page');
131
+ await assertPendingState(clientA, 1);
132
+ }),
133
+ },
134
+ {
135
+ name: 'pull cursors advance monotonically across pages',
136
+ run: () =>
137
+ inScenario(async ({ clientA, server }) => {
138
+ await adapter.server.seed(server, change('seed-one', 'one', 10, 'one'));
139
+ await adapter.server.seed(server, change('seed-two', 'two', 20, 'two'));
140
+ await adapter.server.seed(server, change('seed-three', 'three', 30, 'three'));
141
+ const start = await adapter.local.readCursor(clientA);
142
+ await pullAll(clientA, server);
143
+ const end = await adapter.local.readCursor(clientA);
144
+ assert(adapter.wire.compareCursors(end, start) > 0, 'pull did not advance the cursor');
145
+ assert(
146
+ sameRows(await adapter.local.snapshot(clientA), await adapter.server.snapshot(server)),
147
+ 'paged pull skipped or duplicated server state',
148
+ );
149
+ }),
150
+ },
151
+ ];
152
+ }
153
+
154
+ function pullValidationCases<
155
+ TClient,
156
+ TServer,
157
+ TPending,
158
+ TPushRequest,
159
+ TPushResponse,
160
+ TPullResponse,
161
+ TRemoteChange,
162
+ TCursor,
163
+ >(
164
+ kit: SyncConformanceKit<
165
+ TClient,
166
+ TServer,
167
+ TPending,
168
+ TPushRequest,
169
+ TPushResponse,
170
+ TPullResponse,
171
+ TRemoteChange,
172
+ TCursor
173
+ >,
174
+ ): SyncConformanceTestCase[] {
175
+ const { adapter, inScenario, assertPendingState, push, pullPage, pullAll } = kit;
176
+ return [
177
+ {
178
+ name: 'a regressing pull cursor is rejected before local apply',
179
+ run: () =>
180
+ inScenario(async ({ clientA, server }) => {
181
+ await adapter.server.seed(server, change('seed-regress', 'regress', 10, 'remote'));
182
+ await pullAll(clientA, server);
183
+ const cursor = await adapter.local.readCursor(clientA);
184
+ const rows = await adapter.local.snapshot(clientA);
185
+ await adapter.server.faultNextPull(server, 'regress');
186
+ await expectFailure(
187
+ () => pullPage(clientA, server).then(() => undefined),
188
+ 'regressing cursor was accepted',
189
+ );
190
+ assert(
191
+ adapter.wire.compareCursors(await adapter.local.readCursor(clientA), cursor) === 0,
192
+ 'regressing page changed the cursor',
193
+ );
194
+ assert(
195
+ sameRows(await adapter.local.snapshot(clientA), rows),
196
+ 'regressing page changed data',
197
+ );
198
+ }),
199
+ },
200
+ {
201
+ name: 'hasMore requires cursor progress',
202
+ run: () =>
203
+ inScenario(async ({ clientA, server }) => {
204
+ const cursor = await adapter.local.readCursor(clientA);
205
+ await adapter.server.faultNextPull(server, 'stall');
206
+ await expectFailure(
207
+ () => pullPage(clientA, server).then(() => undefined),
208
+ 'hasMore without cursor progress was accepted',
209
+ );
210
+ assert(
211
+ adapter.wire.compareCursors(await adapter.local.readCursor(clientA), cursor) === 0,
212
+ 'stalled page changed the cursor',
213
+ );
214
+ }),
215
+ },
216
+ {
217
+ name: 'partial push outcomes are rejected before acknowledgement',
218
+ run: () =>
219
+ inScenario(async ({ clientA, server }) => {
220
+ await adapter.outbox.enqueue(clientA, change('change-covered-a', 'covered-a', 10, 'a'));
221
+ await adapter.outbox.enqueue(clientA, change('change-covered-b', 'covered-b', 20, 'b'));
222
+ await adapter.server.omitNextPushOutcome(server);
223
+ await expectFailure(() => push(clientA, server), 'partial push outcomes were accepted');
224
+ await assertPendingState(clientA, 2);
225
+ }),
226
+ },
227
+ ];
228
+ }
229
+
230
+ function submissionOrderingCases<
231
+ TClient,
232
+ TServer,
233
+ TPending,
234
+ TPushRequest,
235
+ TPushResponse,
236
+ TPullResponse,
237
+ TRemoteChange,
238
+ TCursor,
239
+ >(
240
+ kit: SyncConformanceKit<
241
+ TClient,
242
+ TServer,
243
+ TPending,
244
+ TPushRequest,
245
+ TPushResponse,
246
+ TPullResponse,
247
+ TRemoteChange,
248
+ TCursor
249
+ >,
250
+ ): SyncConformanceTestCase[] {
251
+ const { adapter, inScenario, pending, assertPendingState, submit, applySubmittedBatchOutcome } =
252
+ kit;
253
+ return [
254
+ {
255
+ name: 'an older accepted submission settles only its exact pending rows',
256
+ run: () =>
257
+ inScenario(async ({ clientA, server }) => {
258
+ await adapter.outbox.enqueue(clientA, change('change-overlap-a', 'overlap', 10, 'A'));
259
+ const submissionA = await submit(clientA, server);
260
+ await adapter.outbox.enqueue(clientA, change('change-overlap-b', 'overlap', 30, 'B'));
261
+ await submit(clientA, server);
262
+
263
+ await applySubmittedBatchOutcome(clientA, submissionA);
264
+
265
+ const remaining = await pending(clientA);
266
+ assert(remaining.length === 1, 'accepted submission removed a newer pending row');
267
+ assert(
268
+ remaining[0] !== undefined &&
269
+ adapter.outbox.pendingId(remaining[0]) === 'change-overlap-b',
270
+ 'accepted submission settled the wrong pending ID',
271
+ );
272
+ const rows = await adapter.local.snapshot(clientA);
273
+ const visible = rows.find(
274
+ (row) => row.entityType === 'record' && row.entityId === 'overlap',
275
+ );
276
+ assert(visible?.value === 'B', 'accepted submission replaced the newer local value');
277
+ await assertPendingState(clientA, 1);
278
+ }),
279
+ },
280
+ {
281
+ name: 'an older rejected submission cannot replace a newer pending value',
282
+ run: () =>
283
+ inScenario(async ({ clientA, server }) => {
284
+ await adapter.server.seed(server, change('seed-overlap', 'overlap', 20, 'server'));
285
+ await adapter.outbox.enqueue(clientA, change('change-overlap-a', 'overlap', 10, 'A'));
286
+ const submissionA = await submit(clientA, server);
287
+ await adapter.outbox.enqueue(clientA, change('change-overlap-b', 'overlap', 30, 'B'));
288
+ await submit(clientA, server);
289
+
290
+ await applySubmittedBatchOutcome(clientA, submissionA);
291
+
292
+ const remaining = await pending(clientA);
293
+ assert(remaining.length === 1, 'rejected submission removed a newer pending row');
294
+ assert(
295
+ remaining[0] !== undefined &&
296
+ adapter.outbox.pendingId(remaining[0]) === 'change-overlap-b',
297
+ 'rejected submission settled the wrong pending ID',
298
+ );
299
+ const rows = await adapter.local.snapshot(clientA);
300
+ const visible = rows.find(
301
+ (row) => row.entityType === 'record' && row.entityId === 'overlap',
302
+ );
303
+ assert(visible?.value === 'B', 'rejected server row replaced the newer local value');
304
+ assert(
305
+ (await adapter.outbox.listRejected(clientA)).length === 1,
306
+ 'rejected submission did not record its rejection',
307
+ );
308
+ await assertPendingState(clientA, 1);
309
+ }),
310
+ },
311
+ ];
312
+ }
313
+
314
+ function failureCases<
315
+ TClient,
316
+ TServer,
317
+ TPending,
318
+ TPushRequest,
319
+ TPushResponse,
320
+ TPullResponse,
321
+ TRemoteChange,
322
+ TCursor,
323
+ >(
324
+ kit: SyncConformanceKit<
325
+ TClient,
326
+ TServer,
327
+ TPending,
328
+ TPushRequest,
329
+ TPushResponse,
330
+ TPullResponse,
331
+ TRemoteChange,
332
+ TCursor
333
+ >,
334
+ ): SyncConformanceTestCase[] {
335
+ const { adapter, inScenario, assertPendingState, push, pullPage } = kit;
336
+ return [
337
+ {
338
+ name: 'a stale pull commits its cursor without replacing a pending local value',
339
+ run: () =>
340
+ inScenario(async ({ clientA, server }) => {
341
+ await adapter.server.seed(server, change('seed-stale-pull', 'stale-pull', 20, 'server'));
342
+ await adapter.outbox.enqueue(
343
+ clientA,
344
+ change('change-stale-pull', 'stale-pull', 20, 'local'),
345
+ );
346
+ const cursorBefore = await adapter.local.readCursor(clientA);
347
+
348
+ await pullPage(clientA, server);
349
+
350
+ const cursorAfter = await adapter.local.readCursor(clientA);
351
+ assert(
352
+ adapter.wire.compareCursors(cursorAfter, cursorBefore) > 0,
353
+ 'stale pull did not commit its cursor',
354
+ );
355
+ const rows = await adapter.local.snapshot(clientA);
356
+ const visible = rows.find(
357
+ (row) => row.entityType === 'record' && row.entityId === 'stale-pull',
358
+ );
359
+ assert(visible?.value === 'local', 'stale pull replaced the pending local value');
360
+ await assertPendingState(clientA, 1);
361
+ }),
362
+ },
363
+ {
364
+ name: 'network failure keeps pending state truthful',
365
+ run: () =>
366
+ inScenario(async ({ clientA, server }) => {
367
+ await adapter.outbox.enqueue(clientA, change('change-network', 'network', 10, 'local'));
368
+ await adapter.server.failNextPush(server, 'network');
369
+ await expectFailure(() => push(clientA, server), 'network failure resolved successfully');
370
+ await assertPendingState(clientA, 1);
371
+ }),
372
+ },
373
+ ];
374
+ }
375
+
376
+ function rejectionCases<
377
+ TClient,
378
+ TServer,
379
+ TPending,
380
+ TPushRequest,
381
+ TPushResponse,
382
+ TPullResponse,
383
+ TRemoteChange,
384
+ TCursor,
385
+ >(
386
+ kit: SyncConformanceKit<
387
+ TClient,
388
+ TServer,
389
+ TPending,
390
+ TPushRequest,
391
+ TPushResponse,
392
+ TPullResponse,
393
+ TRemoteChange,
394
+ TCursor
395
+ >,
396
+ ): SyncConformanceTestCase[] {
397
+ const { adapter, inScenario, assertPendingState, push } = kit;
398
+ return [
399
+ {
400
+ name: 'server failure keeps pending state truthful',
401
+ run: () =>
402
+ inScenario(async ({ clientA, server }) => {
403
+ await adapter.outbox.enqueue(clientA, change('change-server', 'server', 10, 'local'));
404
+ await adapter.server.failNextPush(server, 'server');
405
+ await expectFailure(() => push(clientA, server), 'server failure resolved successfully');
406
+ await assertPendingState(clientA, 1);
407
+ }),
408
+ },
409
+ {
410
+ name: 'complete rejection outcomes are recorded without hidden pending work',
411
+ run: () =>
412
+ inScenario(async ({ clientA, server }) => {
413
+ await adapter.server.seed(server, change('seed-newer', 'rejected', 20, 'server'));
414
+ await adapter.outbox.enqueue(clientA, change('change-older', 'rejected', 10, 'local'));
415
+ await push(clientA, server);
416
+ await assertPendingState(clientA, 0);
417
+ const rejected = await adapter.outbox.listRejected(clientA);
418
+ assert(rejected.length === 1, 'actionable rejection was not recorded');
419
+ assert(rejected[0]?.entityId === 'rejected', 'wrong rejection was recorded');
420
+ }),
421
+ },
422
+ ];
423
+ }
424
+
425
+ function convergenceCases<
426
+ TClient,
427
+ TServer,
428
+ TPending,
429
+ TPushRequest,
430
+ TPushResponse,
431
+ TPullResponse,
432
+ TRemoteChange,
433
+ TCursor,
434
+ >(
435
+ kit: SyncConformanceKit<
436
+ TClient,
437
+ TServer,
438
+ TPending,
439
+ TPushRequest,
440
+ TPushResponse,
441
+ TPullResponse,
442
+ TRemoteChange,
443
+ TCursor
444
+ >,
445
+ ): SyncConformanceTestCase[] {
446
+ const { adapter, inScenario, assertPendingState, push, pullAll } = kit;
447
+ return [
448
+ {
449
+ name: 'pushes referenced records before dependent records',
450
+ run: () =>
451
+ inScenario(async ({ clientA, server }) => {
452
+ await adapter.outbox.enqueue(clientA, childChange);
453
+ await adapter.outbox.enqueue(clientA, parentChange);
454
+ await push(clientA, server);
455
+ await assertPendingState(clientA, 0);
456
+ const rows = await adapter.server.snapshot(server);
457
+ assert(
458
+ rows.some((row) => row.entityType === 'container' && row.entityId === 'parent'),
459
+ 'referenced record did not reach the server',
460
+ );
461
+ assert(
462
+ rows.some((row) => row.entityType === 'item' && row.entityId === 'child'),
463
+ 'dependent record was rejected because push order was unsafe',
464
+ );
465
+ }),
466
+ },
467
+ {
468
+ name: 'two clients converge after alternating sync, including a tombstone',
469
+ run: () =>
470
+ inScenario(async ({ clientA, clientB, server }) => {
471
+ await adapter.outbox.enqueue(clientA, change('change-a', 'alpha', 10, 'from A'));
472
+ await adapter.outbox.enqueue(clientB, change('change-b', 'beta', 20, 'from B'));
473
+ await push(clientA, server);
474
+ await pullAll(clientB, server);
475
+ await push(clientB, server);
476
+ await pullAll(clientA, server);
477
+ await adapter.outbox.enqueue(clientB, tombstone('change-delete', 'alpha', 30));
478
+ await push(clientB, server);
479
+ await pullAll(clientA, server);
480
+ await pullAll(clientB, server);
481
+
482
+ const rowsA = await adapter.local.snapshot(clientA);
483
+ const rowsB = await adapter.local.snapshot(clientB);
484
+ const serverRows = await adapter.server.snapshot(server);
485
+ assert(sameRows(rowsA, rowsB), 'clients did not converge to the same state');
486
+ assert(sameRows(rowsA, serverRows), 'clients did not converge to server state');
487
+ const deleted = rowsA.find(
488
+ (row) => row.entityType === 'record' && row.entityId === 'alpha',
489
+ );
490
+ assert(deleted?.deleted === true, 'tombstone did not converge');
491
+ await assertPendingState(clientA, 0);
492
+ await assertPendingState(clientB, 0);
493
+ }),
494
+ },
495
+ ];
496
+ }
@@ -0,0 +1,159 @@
1
+ import type {
2
+ SyncConformanceAdapter,
3
+ SyncConformanceFullResyncCallbacks,
4
+ SyncConformanceLocalApplyOptions,
5
+ SyncConformancePushResult,
6
+ SyncConformanceScenario,
7
+ SyncConformanceStaleCursor,
8
+ } from './conformance.js';
9
+ import { assert, fail, PAGE_SIZE, type TestContext } from './conformance-support.js';
10
+ import { validatePullPage } from './transport.js';
11
+
12
+ export interface SyncConformanceSubmission<TPending, TPushResponse, TRemoteChange> {
13
+ readonly submitted: readonly TPending[];
14
+ readonly response: TPushResponse;
15
+ readonly outcome: SyncConformancePushResult<TPending, TRemoteChange>;
16
+ }
17
+
18
+ /** Scenario helpers shared by every conformance case. */
19
+ export class SyncConformanceKit<
20
+ TClient,
21
+ TServer,
22
+ TPending,
23
+ TPushRequest,
24
+ TPushResponse,
25
+ TPullResponse,
26
+ TRemoteChange,
27
+ TCursor,
28
+ > {
29
+ public constructor(
30
+ public readonly adapter: SyncConformanceAdapter<
31
+ TClient,
32
+ TServer,
33
+ TPending,
34
+ TPushRequest,
35
+ TPushResponse,
36
+ TPullResponse,
37
+ TRemoteChange,
38
+ TCursor
39
+ >,
40
+ ) {}
41
+
42
+ public readonly inScenario = async (
43
+ run: (context: TestContext<TClient, TServer>) => Promise<void>,
44
+ ): Promise<void> => {
45
+ const scenario: SyncConformanceScenario<TClient, TServer> = await this.adapter.createScenario();
46
+ const [clientA, clientB] = scenario.clients;
47
+ try {
48
+ await run({ clientA, clientB, server: scenario.server });
49
+ } finally {
50
+ await this.adapter.disposeScenario?.(scenario);
51
+ }
52
+ };
53
+
54
+ public readonly pending = async (client: TClient): Promise<readonly TPending[]> =>
55
+ this.adapter.outbox.listPending(client);
56
+
57
+ public readonly assertPendingState = async (
58
+ client: TClient,
59
+ expectedCount: number,
60
+ ): Promise<void> => {
61
+ const actual = await this.pending(client);
62
+ const reported = await this.adapter.local.readPendingState(client);
63
+ assert(
64
+ actual.length === expectedCount,
65
+ `expected ${String(expectedCount)} pending changes, received ${String(actual.length)}`,
66
+ );
67
+ assert(
68
+ reported.pendingCount === actual.length,
69
+ 'reported pending count differs from the outbox',
70
+ );
71
+ assert(reported.pending === actual.length > 0, 'reported pending flag differs from the outbox');
72
+ };
73
+
74
+ public readonly submit = async (
75
+ client: TClient,
76
+ server: TServer,
77
+ ): Promise<SyncConformanceSubmission<TPending, TPushResponse, TRemoteChange>> => {
78
+ const submitted = await this.pending(client);
79
+ assert(submitted.length > 0, 'cannot submit an empty pending batch');
80
+ const request = await this.adapter.wire.encodePush(submitted);
81
+ const response = await this.adapter.server.acceptPush(server, request);
82
+ const outcome = await this.adapter.wire.decodePush(response, submitted);
83
+ return { submitted, response, outcome };
84
+ };
85
+
86
+ public readonly applySubmittedBatchOutcome = async (
87
+ client: TClient,
88
+ submission: SyncConformanceSubmission<TPending, TPushResponse, TRemoteChange>,
89
+ ): Promise<void> => {
90
+ await this.adapter.local.applySubmittedBatchOutcome(client, {
91
+ submitted: submission.submitted,
92
+ response: submission.response,
93
+ ...submission.outcome,
94
+ });
95
+ };
96
+
97
+ public readonly push = async (client: TClient, server: TServer): Promise<void> => {
98
+ const submitted = await this.pending(client);
99
+ if (submitted.length === 0) return;
100
+ await this.applySubmittedBatchOutcome(client, await this.submit(client, server));
101
+ };
102
+
103
+ public readonly pullPage = async (
104
+ client: TClient,
105
+ server: TServer,
106
+ options?: SyncConformanceLocalApplyOptions,
107
+ ): Promise<boolean> => {
108
+ const cursor = (await this.adapter.local.readCursor(client)) as TCursor;
109
+ const response = await this.adapter.server.servePull(server, cursor, PAGE_SIZE);
110
+ const page = await this.adapter.wire.decodePull(response);
111
+ validatePullPage(cursor, page, (left, right) => this.adapter.wire.compareCursors(left, right));
112
+ await this.adapter.local.applyPullPage(client, page, options);
113
+ return page.hasMore;
114
+ };
115
+
116
+ public readonly pullAll = async (client: TClient, server: TServer): Promise<void> => {
117
+ let hasMore = true;
118
+ while (hasMore) hasMore = await this.pullPage(client, server);
119
+ };
120
+
121
+ public readonly expectStalePull = async (
122
+ client: TClient,
123
+ server: TServer,
124
+ fullResync: SyncConformanceFullResyncCallbacks<TClient, TServer, TCursor>,
125
+ ): Promise<SyncConformanceStaleCursor<TCursor>> => {
126
+ const cursor = await this.adapter.local.readCursor(client);
127
+ try {
128
+ await this.adapter.server.servePull(server, cursor, PAGE_SIZE);
129
+ } catch (error) {
130
+ const stale = fullResync.decodeStaleCursor(error);
131
+ if (stale === null) throw error;
132
+ assert(
133
+ this.adapter.wire.compareCursors(stale.horizon, cursor) > 0,
134
+ 'stale cursor response did not contain a newer purge horizon',
135
+ );
136
+ return stale;
137
+ }
138
+ fail('stale cursor returned a pull page');
139
+ };
140
+
141
+ public readonly recoverFromStaleCursor = async (
142
+ client: TClient,
143
+ server: TServer,
144
+ fullResync: SyncConformanceFullResyncCallbacks<TClient, TServer, TCursor>,
145
+ ): Promise<'completed' | 'deferred'> => {
146
+ const stale = await this.expectStalePull(client, server, fullResync);
147
+ if (!(await fullResync.isResetSafe(client, stale))) return 'deferred';
148
+ await fullResync.reset(client, stale);
149
+ assert(
150
+ this.adapter.wire.compareCursors(
151
+ await this.adapter.local.readCursor(client),
152
+ fullResync.zeroCursor,
153
+ ) === 0,
154
+ 'full-resync reset did not store cursor zero',
155
+ );
156
+ await this.pullAll(client, server);
157
+ return 'completed';
158
+ };
159
+ }