@baukit/sync-client 0.18.2 → 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,378 @@
1
+ import type {
2
+ SyncConformanceFullResyncCallbacks,
3
+ SyncConformanceRow,
4
+ SyncConformanceTestCase,
5
+ } from './conformance.js';
6
+ import type { SyncConformanceKit } from './conformance-kit.js';
7
+ import {
8
+ PAGE_SIZE,
9
+ assert,
10
+ change,
11
+ childChange,
12
+ expectFailure,
13
+ parentChange,
14
+ sameRows,
15
+ } from './conformance-support.js';
16
+ import { validatePullPage } from './transport.js';
17
+
18
+ export function fullResyncConformanceCases<
19
+ TClient,
20
+ TServer,
21
+ TPending,
22
+ TPushRequest,
23
+ TPushResponse,
24
+ TPullResponse,
25
+ TRemoteChange,
26
+ TCursor,
27
+ >(
28
+ kit: SyncConformanceKit<
29
+ TClient,
30
+ TServer,
31
+ TPending,
32
+ TPushRequest,
33
+ TPushResponse,
34
+ TPullResponse,
35
+ TRemoteChange,
36
+ TCursor
37
+ >,
38
+ fullResync: SyncConformanceFullResyncCallbacks<TClient, TServer, TCursor>,
39
+ ): SyncConformanceTestCase[] {
40
+ return [
41
+ ...purgeHorizonCases(kit, fullResync),
42
+ ...fullResyncResetCases(kit, fullResync),
43
+ ...interruptedResetCases(kit, fullResync),
44
+ ...deferredResetCases(kit, fullResync),
45
+ ...repeatedStaleCursorCases(kit, fullResync),
46
+ ];
47
+ }
48
+
49
+ function purgeHorizonCases<
50
+ TClient,
51
+ TServer,
52
+ TPending,
53
+ TPushRequest,
54
+ TPushResponse,
55
+ TPullResponse,
56
+ TRemoteChange,
57
+ TCursor,
58
+ >(
59
+ kit: SyncConformanceKit<
60
+ TClient,
61
+ TServer,
62
+ TPending,
63
+ TPushRequest,
64
+ TPushResponse,
65
+ TPullResponse,
66
+ TRemoteChange,
67
+ TCursor
68
+ >,
69
+ fullResync: SyncConformanceFullResyncCallbacks<TClient, TServer, TCursor>,
70
+ ): SyncConformanceTestCase[] {
71
+ const { adapter, inScenario, pullAll, expectStalePull } = kit;
72
+ return [
73
+ {
74
+ name: 'purge horizons are monotonic and cursor zero requests a full rebuild',
75
+ run: () =>
76
+ inScenario(async ({ clientA, server }) => {
77
+ const first = change('horizon-first', 'horizon-first', 10, 'first');
78
+ const second = change('horizon-second', 'horizon-second', 20, 'second');
79
+ await adapter.server.seed(server, first);
80
+ await adapter.server.seed(server, second);
81
+ await pullAll(clientA, server);
82
+ const oldCursor = await adapter.local.readCursor(clientA);
83
+
84
+ const firstHorizon = await fullResync.purgeTombstones(server, [first]);
85
+ const secondHorizon = await fullResync.purgeTombstones(server, [second]);
86
+ assert(
87
+ adapter.wire.compareCursors(firstHorizon, oldCursor) > 0,
88
+ 'first purge did not advance the owner horizon past the old cursor',
89
+ );
90
+ assert(
91
+ adapter.wire.compareCursors(secondHorizon, firstHorizon) >= 0,
92
+ 'owner purge horizon regressed',
93
+ );
94
+
95
+ const stale = await expectStalePull(clientA, server, fullResync);
96
+ assert(
97
+ adapter.wire.compareCursors(stale.horizon, secondHorizon) === 0,
98
+ 'stale cursor response did not contain the current owner horizon',
99
+ );
100
+
101
+ const response = await adapter.server.servePull(server, fullResync.zeroCursor, PAGE_SIZE);
102
+ const page = await adapter.wire.decodePull(response);
103
+ validatePullPage(fullResync.zeroCursor, page, (left, right) =>
104
+ adapter.wire.compareCursors(left, right),
105
+ );
106
+ }),
107
+ },
108
+ ];
109
+ }
110
+
111
+ function fullResyncResetCases<
112
+ TClient,
113
+ TServer,
114
+ TPending,
115
+ TPushRequest,
116
+ TPushResponse,
117
+ TPullResponse,
118
+ TRemoteChange,
119
+ TCursor,
120
+ >(
121
+ kit: SyncConformanceKit<
122
+ TClient,
123
+ TServer,
124
+ TPending,
125
+ TPushRequest,
126
+ TPushResponse,
127
+ TPullResponse,
128
+ TRemoteChange,
129
+ TCursor
130
+ >,
131
+ fullResync: SyncConformanceFullResyncCallbacks<TClient, TServer, TCursor>,
132
+ ): SyncConformanceTestCase[] {
133
+ const { adapter, inScenario, assertPendingState, push, pullAll, expectStalePull } = kit;
134
+ return [
135
+ {
136
+ name: 'full resync clears parent, child, and pull-only rows but preserves repair work',
137
+ run: () =>
138
+ inScenario(async ({ clientA, server }) => {
139
+ const pullOnly = change('pull-only-seed', 'pull-only', 12, 'server only');
140
+ const pendingRemote = change('pending-seed', 'pending-edit', 20, 'server value');
141
+ const rejectedRemote = change('rejected-seed', 'rejected-edit', 50, 'server value');
142
+ await adapter.server.seed(server, parentChange);
143
+ await adapter.server.seed(server, childChange);
144
+ await adapter.server.seed(server, pullOnly);
145
+ await adapter.server.seed(server, pendingRemote);
146
+ await adapter.server.seed(server, rejectedRemote);
147
+ await pullAll(clientA, server);
148
+
149
+ await adapter.outbox.enqueue(
150
+ clientA,
151
+ change('rejected-local', 'rejected-edit', 40, 'rejected value'),
152
+ );
153
+ await push(clientA, server);
154
+ await adapter.outbox.enqueue(
155
+ clientA,
156
+ change('pending-local', 'pending-edit', 60, 'pending value'),
157
+ );
158
+ await fullResync.purgeTombstones(server, [childChange, parentChange, pullOnly]);
159
+ const stale = await expectStalePull(clientA, server, fullResync);
160
+
161
+ await fullResync.reset(clientA, stale);
162
+
163
+ assert(
164
+ adapter.wire.compareCursors(
165
+ await adapter.local.readCursor(clientA),
166
+ fullResync.zeroCursor,
167
+ ) === 0,
168
+ 'reset did not atomically store cursor zero',
169
+ );
170
+ await assertPendingState(clientA, 1);
171
+ assert(
172
+ (await adapter.outbox.listRejected(clientA)).length === 1,
173
+ 'reset removed an explicit rejection record',
174
+ );
175
+ assertResetRows(await adapter.local.snapshot(clientA));
176
+
177
+ await push(clientA, server);
178
+ await pullAll(clientA, server);
179
+ await assertPendingState(clientA, 0);
180
+ assert(
181
+ (await adapter.outbox.listRejected(clientA)).length === 1,
182
+ 'full rebuild removed an unresolved rejection',
183
+ );
184
+ }),
185
+ },
186
+ ];
187
+ }
188
+
189
+ function interruptedResetCases<
190
+ TClient,
191
+ TServer,
192
+ TPending,
193
+ TPushRequest,
194
+ TPushResponse,
195
+ TPullResponse,
196
+ TRemoteChange,
197
+ TCursor,
198
+ >(
199
+ kit: SyncConformanceKit<
200
+ TClient,
201
+ TServer,
202
+ TPending,
203
+ TPushRequest,
204
+ TPushResponse,
205
+ TPullResponse,
206
+ TRemoteChange,
207
+ TCursor
208
+ >,
209
+ fullResync: SyncConformanceFullResyncCallbacks<TClient, TServer, TCursor>,
210
+ ): SyncConformanceTestCase[] {
211
+ const { adapter, inScenario, assertPendingState, pullAll, expectStalePull } = kit;
212
+ return [
213
+ {
214
+ name: 'an interrupted full-resync reset rolls back rows and cursor',
215
+ run: () =>
216
+ inScenario(async ({ clientA, server }) => {
217
+ const first = change('reset-first', 'reset-first', 10, 'first');
218
+ const second = change('reset-second', 'reset-second', 20, 'second');
219
+ await adapter.server.seed(server, first);
220
+ await adapter.server.seed(server, second);
221
+ await pullAll(clientA, server);
222
+ await adapter.outbox.enqueue(clientA, change('reset-pending', 'pending', 30, 'local'));
223
+ await fullResync.purgeTombstones(server, [first, second]);
224
+ const stale = await expectStalePull(clientA, server, fullResync);
225
+ const cursorBefore = await adapter.local.readCursor(clientA);
226
+ const rowsBefore = await adapter.local.snapshot(clientA);
227
+
228
+ await expectFailure(
229
+ () => Promise.resolve(fullResync.reset(clientA, stale, { failAfterRows: 1 })),
230
+ 'injected full-resync reset failure resolved successfully',
231
+ );
232
+
233
+ assert(
234
+ adapter.wire.compareCursors(await adapter.local.readCursor(clientA), cursorBefore) ===
235
+ 0,
236
+ 'failed full-resync reset changed the cursor',
237
+ );
238
+ assert(
239
+ sameRows(await adapter.local.snapshot(clientA), rowsBefore),
240
+ 'failed full-resync reset committed a partial row deletion',
241
+ );
242
+ await assertPendingState(clientA, 1);
243
+ }),
244
+ },
245
+ ];
246
+ }
247
+
248
+ function deferredResetCases<
249
+ TClient,
250
+ TServer,
251
+ TPending,
252
+ TPushRequest,
253
+ TPushResponse,
254
+ TPullResponse,
255
+ TRemoteChange,
256
+ TCursor,
257
+ >(
258
+ kit: SyncConformanceKit<
259
+ TClient,
260
+ TServer,
261
+ TPending,
262
+ TPushRequest,
263
+ TPushResponse,
264
+ TPullResponse,
265
+ TRemoteChange,
266
+ TCursor
267
+ >,
268
+ fullResync: SyncConformanceFullResyncCallbacks<TClient, TServer, TCursor>,
269
+ ): SyncConformanceTestCase[] {
270
+ const { adapter, inScenario, pullAll, recoverFromStaleCursor } = kit;
271
+ return [
272
+ {
273
+ name: 'the product safety hook can defer a disruptive reset',
274
+ run: () =>
275
+ inScenario(async ({ clientA, server }) => {
276
+ const remote = change('defer-seed', 'defer', 10, 'remote');
277
+ await adapter.server.seed(server, remote);
278
+ await pullAll(clientA, server);
279
+ await fullResync.purgeTombstones(server, [remote]);
280
+ await fullResync.setResetSafe(clientA, false);
281
+ const cursorBefore = await adapter.local.readCursor(clientA);
282
+ const rowsBefore = await adapter.local.snapshot(clientA);
283
+
284
+ const result = await recoverFromStaleCursor(clientA, server, fullResync);
285
+
286
+ assert(result === 'deferred', 'unsafe reset was not deferred');
287
+ assert((await fullResync.readResetCount(clientA)) === 0, 'deferred reset ran anyway');
288
+ assert(
289
+ adapter.wire.compareCursors(await adapter.local.readCursor(clientA), cursorBefore) ===
290
+ 0,
291
+ 'deferred reset changed the cursor',
292
+ );
293
+ assert(
294
+ sameRows(await adapter.local.snapshot(clientA), rowsBefore),
295
+ 'deferred reset changed local rows',
296
+ );
297
+ }),
298
+ },
299
+ ];
300
+ }
301
+
302
+ function repeatedStaleCursorCases<
303
+ TClient,
304
+ TServer,
305
+ TPending,
306
+ TPushRequest,
307
+ TPushResponse,
308
+ TPullResponse,
309
+ TRemoteChange,
310
+ TCursor,
311
+ >(
312
+ kit: SyncConformanceKit<
313
+ TClient,
314
+ TServer,
315
+ TPending,
316
+ TPushRequest,
317
+ TPushResponse,
318
+ TPullResponse,
319
+ TRemoteChange,
320
+ TCursor
321
+ >,
322
+ fullResync: SyncConformanceFullResyncCallbacks<TClient, TServer, TCursor>,
323
+ ): SyncConformanceTestCase[] {
324
+ const { adapter, inScenario, pullAll, recoverFromStaleCursor } = kit;
325
+ return [
326
+ {
327
+ name: 'a second stale cursor after reset stops without another reset',
328
+ run: () =>
329
+ inScenario(async ({ clientA, server }) => {
330
+ const remote = change('repeat-stale-seed', 'repeat-stale', 10, 'remote');
331
+ await adapter.server.seed(server, remote);
332
+ await pullAll(clientA, server);
333
+ const horizon = await fullResync.purgeTombstones(server, [remote]);
334
+ await fullResync.rejectNextZeroCursor(server, horizon);
335
+
336
+ await expectFailure(
337
+ () => recoverFromStaleCursor(clientA, server, fullResync).then(() => undefined),
338
+ 'second stale cursor restarted full resync',
339
+ );
340
+
341
+ assert(
342
+ (await fullResync.readResetCount(clientA)) === 1,
343
+ 'second stale cursor caused another reset',
344
+ );
345
+ assert(
346
+ adapter.wire.compareCursors(
347
+ await adapter.local.readCursor(clientA),
348
+ fullResync.zeroCursor,
349
+ ) === 0,
350
+ 'failed full rebuild did not leave the explicit rebuild cursor',
351
+ );
352
+ }),
353
+ },
354
+ ];
355
+ }
356
+
357
+ function assertResetRows(resetRows: readonly SyncConformanceRow[]): void {
358
+ assert(
359
+ !resetRows.some((row) => row.entityType === 'container' && row.entityId === 'parent'),
360
+ 'reset retained a server-backed parent',
361
+ );
362
+ assert(
363
+ !resetRows.some((row) => row.entityType === 'item' && row.entityId === 'child'),
364
+ 'reset retained a server-backed child',
365
+ );
366
+ assert(
367
+ !resetRows.some((row) => row.entityType === 'record' && row.entityId === 'pull-only'),
368
+ 'reset retained a pull-only row',
369
+ );
370
+ assert(
371
+ resetRows.some((row) => row.entityId === 'pending-edit' && row.value === 'pending value'),
372
+ 'reset removed the row for a pending local edit',
373
+ );
374
+ assert(
375
+ resetRows.some((row) => row.entityId === 'rejected-edit'),
376
+ 'reset removed the row attached to an explicit rejection',
377
+ );
378
+ }
@@ -0,0 +1,91 @@
1
+ import type { SyncConformanceChange, SyncConformanceRow } from './conformance.js';
2
+
3
+ export interface TestContext<TClient, TServer> {
4
+ clientA: TClient;
5
+ clientB: TClient;
6
+ server: TServer;
7
+ }
8
+
9
+ export const PAGE_SIZE = 2;
10
+
11
+ export const parentChange: SyncConformanceChange = {
12
+ changeId: 'change-parent',
13
+ entityType: 'container',
14
+ entityId: 'parent',
15
+ operation: 'upsert',
16
+ value: 'parent value',
17
+ logicalTime: 10,
18
+ };
19
+
20
+ export const childChange: SyncConformanceChange = {
21
+ changeId: 'change-child',
22
+ entityType: 'item',
23
+ entityId: 'child',
24
+ operation: 'upsert',
25
+ value: 'child value',
26
+ logicalTime: 11,
27
+ dependsOn: { entityType: 'container', entityId: 'parent' },
28
+ };
29
+
30
+ export function change(
31
+ changeId: string,
32
+ entityId: string,
33
+ logicalTime: number,
34
+ value: string,
35
+ ): SyncConformanceChange {
36
+ return {
37
+ changeId,
38
+ entityType: 'record',
39
+ entityId,
40
+ operation: 'upsert',
41
+ value,
42
+ logicalTime,
43
+ };
44
+ }
45
+
46
+ export function tombstone(
47
+ changeId: string,
48
+ entityId: string,
49
+ logicalTime: number,
50
+ ): SyncConformanceChange {
51
+ return {
52
+ changeId,
53
+ entityType: 'record',
54
+ entityId,
55
+ operation: 'delete',
56
+ value: null,
57
+ logicalTime,
58
+ };
59
+ }
60
+
61
+ export function fail(message: string): never {
62
+ throw new Error(`Sync conformance failed: ${message}`);
63
+ }
64
+
65
+ export function assert(condition: boolean, message: string): asserts condition {
66
+ if (!condition) fail(message);
67
+ }
68
+
69
+ export function sortedRows(rows: readonly SyncConformanceRow[]): SyncConformanceRow[] {
70
+ return [...rows].sort(
71
+ (left, right) =>
72
+ left.entityType.localeCompare(right.entityType) ||
73
+ left.entityId.localeCompare(right.entityId),
74
+ );
75
+ }
76
+
77
+ export function sameRows(
78
+ left: readonly SyncConformanceRow[],
79
+ right: readonly SyncConformanceRow[],
80
+ ): boolean {
81
+ return JSON.stringify(sortedRows(left)) === JSON.stringify(sortedRows(right));
82
+ }
83
+
84
+ export async function expectFailure(run: () => Promise<void>, message: string): Promise<void> {
85
+ try {
86
+ await run();
87
+ } catch {
88
+ return;
89
+ }
90
+ fail(message);
91
+ }