@terreno/syncdb 57.3.0 → 57.6.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 (160) 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/auth/betterAuthReactClient.d.ts +17 -0
  5. package/dist/auth/betterAuthReactClient.d.ts.map +1 -0
  6. package/dist/auth/betterAuthReactClient.js +11 -0
  7. package/dist/auth/betterAuthReactClient.js.map +1 -0
  8. package/dist/auth/betterAuthReactClient.test.d.ts +2 -0
  9. package/dist/auth/betterAuthReactClient.test.d.ts.map +1 -0
  10. package/dist/auth/betterAuthReactClient.test.js +43 -0
  11. package/dist/auth/betterAuthReactClient.test.js.map +1 -0
  12. package/dist/client.adminWindowMutation.test.d.ts +2 -0
  13. package/dist/client.adminWindowMutation.test.d.ts.map +1 -0
  14. package/dist/client.adminWindowMutation.test.js +65 -0
  15. package/dist/client.adminWindowMutation.test.js.map +1 -0
  16. package/dist/client.d.ts +22 -0
  17. package/dist/client.d.ts.map +1 -1
  18. package/dist/client.js +89 -12
  19. package/dist/client.js.map +1 -1
  20. package/dist/client.test.js +308 -12
  21. package/dist/client.test.js.map +1 -1
  22. package/dist/codegen/emitSdk.js +3 -3
  23. package/dist/codegen/emitSdk.js.map +1 -1
  24. package/dist/codegen/generate.test.js +32 -2
  25. package/dist/codegen/generate.test.js.map +1 -1
  26. package/dist/codegen/safeIdentifiers.d.ts +5 -0
  27. package/dist/codegen/safeIdentifiers.d.ts.map +1 -1
  28. package/dist/codegen/safeIdentifiers.js +8 -0
  29. package/dist/codegen/safeIdentifiers.js.map +1 -1
  30. package/dist/codegen/safeIdentifiers.test.js +20 -8
  31. package/dist/codegen/safeIdentifiers.test.js.map +1 -1
  32. package/dist/codegen/types.d.ts +4 -3
  33. package/dist/codegen/types.d.ts.map +1 -1
  34. package/dist/crypto/keyProviders.js +1 -1
  35. package/dist/crypto/keyProviders.js.map +1 -1
  36. package/dist/debug/debugChannel.test.js +5 -0
  37. package/dist/debug/debugChannel.test.js.map +1 -1
  38. package/dist/debug/debugLog.d.ts +1 -0
  39. package/dist/debug/debugLog.d.ts.map +1 -1
  40. package/dist/debug/debugLog.js +1 -0
  41. package/dist/debug/debugLog.js.map +1 -1
  42. package/dist/debug/devtools.d.ts +6 -0
  43. package/dist/debug/devtools.d.ts.map +1 -0
  44. package/dist/debug/devtools.js +111 -0
  45. package/dist/debug/devtools.js.map +1 -0
  46. package/dist/debug/devtools.test.d.ts +2 -0
  47. package/dist/debug/devtools.test.d.ts.map +1 -0
  48. package/dist/debug/devtools.test.js +168 -0
  49. package/dist/debug/devtools.test.js.map +1 -0
  50. package/dist/index.d.ts +1 -0
  51. package/dist/index.d.ts.map +1 -1
  52. package/dist/index.js +1 -0
  53. package/dist/index.js.map +1 -1
  54. package/dist/isolated/defaultPersisterFactoryNativeErrors.isolated.d.ts +2 -0
  55. package/dist/isolated/defaultPersisterFactoryNativeErrors.isolated.d.ts.map +1 -0
  56. package/dist/isolated/defaultPersisterFactoryNativeErrors.isolated.js +19 -0
  57. package/dist/isolated/defaultPersisterFactoryNativeErrors.isolated.js.map +1 -0
  58. package/dist/mutations/outbox.d.ts +7 -3
  59. package/dist/mutations/outbox.d.ts.map +1 -1
  60. package/dist/mutations/outbox.js +6 -0
  61. package/dist/mutations/outbox.js.map +1 -1
  62. package/dist/mutations/outbox.test.js +17 -0
  63. package/dist/mutations/outbox.test.js.map +1 -1
  64. package/dist/react/collectionHooks.js +2 -2
  65. package/dist/react/collectionHooks.js.map +1 -1
  66. package/dist/storage/idb.d.ts +1 -0
  67. package/dist/storage/idb.d.ts.map +1 -1
  68. package/dist/storage/idb.js +1 -0
  69. package/dist/storage/idb.js.map +1 -1
  70. package/dist/storage/schema.d.ts.map +1 -1
  71. package/dist/storage/schema.js +1 -0
  72. package/dist/storage/schema.js.map +1 -1
  73. package/dist/storage/store.d.ts +3 -2
  74. package/dist/storage/store.d.ts.map +1 -1
  75. package/dist/storage/store.test.js +6 -6
  76. package/dist/storage/store.test.js.map +1 -1
  77. package/dist/storage/types.d.ts +1 -7
  78. package/dist/storage/types.d.ts.map +1 -1
  79. package/dist/sync/deltaApplier.d.ts +2 -0
  80. package/dist/sync/deltaApplier.d.ts.map +1 -1
  81. package/dist/sync/deltaApplier.js +9 -0
  82. package/dist/sync/deltaApplier.js.map +1 -1
  83. package/dist/sync/deltaApplier.test.js +63 -0
  84. package/dist/sync/deltaApplier.test.js.map +1 -1
  85. package/dist/sync/entityRepair.d.ts +1 -0
  86. package/dist/sync/entityRepair.d.ts.map +1 -1
  87. package/dist/sync/entityRepair.js +1 -0
  88. package/dist/sync/entityRepair.js.map +1 -1
  89. package/dist/sync/httpChannel.d.ts +3 -1
  90. package/dist/sync/httpChannel.d.ts.map +1 -1
  91. package/dist/sync/httpChannel.js +3 -1
  92. package/dist/sync/httpChannel.js.map +1 -1
  93. package/dist/sync/httpChannel.test.js +68 -0
  94. package/dist/sync/httpChannel.test.js.map +1 -1
  95. package/dist/sync/replayCoordinator.d.ts +6 -12
  96. package/dist/sync/replayCoordinator.d.ts.map +1 -1
  97. package/dist/sync/replayCoordinator.js +44 -16
  98. package/dist/sync/replayCoordinator.js.map +1 -1
  99. package/dist/sync/replayCoordinator.test.js +29 -10
  100. package/dist/sync/replayCoordinator.test.js.map +1 -1
  101. package/dist/sync/socketTransport.d.ts +3 -45
  102. package/dist/sync/socketTransport.d.ts.map +1 -1
  103. package/dist/sync/socketTransport.js +73 -9
  104. package/dist/sync/socketTransport.js.map +1 -1
  105. package/dist/sync/socketTransport.test.js +41 -1
  106. package/dist/sync/socketTransport.test.js.map +1 -1
  107. package/dist/sync/transport.d.ts +9 -1
  108. package/dist/sync/transport.d.ts.map +1 -1
  109. package/dist/sync/transport.js +1 -1
  110. package/dist/sync/transport.js.map +1 -1
  111. package/dist/sync/windowHydrate.d.ts +25 -0
  112. package/dist/sync/windowHydrate.d.ts.map +1 -0
  113. package/dist/sync/windowHydrate.js +67 -0
  114. package/dist/sync/windowHydrate.js.map +1 -0
  115. package/dist/sync/windowHydrate.test.d.ts +2 -0
  116. package/dist/sync/windowHydrate.test.d.ts.map +1 -0
  117. package/dist/sync/windowHydrate.test.js +164 -0
  118. package/dist/sync/windowHydrate.test.js.map +1 -0
  119. package/dist/testing/fakeTransport.js +1 -1
  120. package/dist/testing/fakeTransport.js.map +1 -1
  121. package/dist/types.d.ts +15 -0
  122. package/dist/types.d.ts.map +1 -1
  123. package/package.json +9 -4
  124. package/src/auth/betterAuthReactClient.test.ts +50 -0
  125. package/src/auth/betterAuthReactClient.ts +33 -0
  126. package/src/client.adminWindowMutation.test.ts +69 -0
  127. package/src/client.test.ts +321 -3
  128. package/src/client.ts +125 -8
  129. package/src/codegen/emitSdk.ts +3 -3
  130. package/src/codegen/generate.test.ts +35 -2
  131. package/src/codegen/safeIdentifiers.test.ts +37 -10
  132. package/src/codegen/safeIdentifiers.ts +17 -0
  133. package/src/codegen/types.ts +3 -3
  134. package/src/debug/debugChannel.test.ts +6 -0
  135. package/src/debug/debugLog.ts +1 -0
  136. package/src/debug/devtools.test.ts +234 -0
  137. package/src/debug/devtools.ts +196 -0
  138. package/src/index.ts +4 -0
  139. package/src/isolated/defaultPersisterFactoryNativeErrors.isolated.ts +23 -0
  140. package/src/mutations/outbox.test.ts +20 -0
  141. package/src/mutations/outbox.ts +11 -3
  142. package/src/react/collectionHooks.ts +2 -2
  143. package/src/storage/idb.ts +1 -0
  144. package/src/storage/schema.ts +1 -0
  145. package/src/storage/store.ts +2 -2
  146. package/src/storage/types.ts +1 -8
  147. package/src/sync/deltaApplier.test.ts +70 -0
  148. package/src/sync/deltaApplier.ts +10 -0
  149. package/src/sync/entityRepair.ts +1 -0
  150. package/src/sync/httpChannel.test.ts +82 -0
  151. package/src/sync/httpChannel.ts +5 -0
  152. package/src/sync/replayCoordinator.test.ts +28 -0
  153. package/src/sync/replayCoordinator.ts +53 -14
  154. package/src/sync/socketTransport.test.ts +45 -2
  155. package/src/sync/socketTransport.ts +106 -20
  156. package/src/sync/transport.ts +7 -1
  157. package/src/sync/windowHydrate.test.ts +179 -0
  158. package/src/sync/windowHydrate.ts +97 -0
  159. package/src/testing/fakeTransport.ts +1 -1
  160. package/src/types.ts +16 -0
@@ -13,6 +13,7 @@ import {idbGet} from "./storage/idb";
13
13
  import {SYNC_SCHEMA_VERSION} from "./storage/schema";
14
14
  import {CURSORS_TABLE} from "./storage/types";
15
15
  import {AuthRequiredError, type HttpChannel} from "./sync/httpChannel";
16
+ import type {SyncTransport} from "./sync/transport";
16
17
  import {createFakeTransport, type FakeTransport} from "./testing/fakeTransport";
17
18
  import type {AuthProvider, SyncDelta, SyncSnapshotResponse, SyncStreamInfo} from "./types";
18
19
 
@@ -26,6 +27,16 @@ const flush = async (): Promise<void> => {
26
27
  await new Promise((resolve) => setTimeout(resolve, 5));
27
28
  };
28
29
 
30
+ const waitUntil = async (predicate: () => boolean, maxAttempts = 20): Promise<void> => {
31
+ for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
32
+ if (predicate()) {
33
+ return;
34
+ }
35
+ await flush();
36
+ }
37
+ throw new Error("waitUntil timed out");
38
+ };
39
+
29
40
  interface FakeAuth {
30
41
  provider: AuthProvider;
31
42
  setUserId: (userId: string | null) => void;
@@ -197,9 +208,9 @@ const makeObservableTransport = (base: FakeTransport): ObservableTransport => {
197
208
  events.push("disconnect");
198
209
  base.disconnect();
199
210
  },
200
- subscribe: (collections: string[]): void => {
211
+ subscribe: (collections: string[], options?: {mode?: "window"}): void => {
201
212
  events.push("subscribe");
202
- base.subscribe(collections);
213
+ base.subscribe(collections, options);
203
214
  },
204
215
  },
205
216
  };
@@ -416,6 +427,62 @@ describe("createSyncDb", () => {
416
427
  await client.stop();
417
428
  });
418
429
 
430
+ it("batches an inbound delta burst into one store notification while retaining per-delta debug and reconcile behavior", async () => {
431
+ const harness = makeHarness({debug: true});
432
+ const batchTransport: SyncTransport = {
433
+ ...harness.transport,
434
+ onDeltaBatch: (callback: (deltas: SyncDelta[]) => void): (() => void) => {
435
+ const pending: SyncDelta[] = [];
436
+ let isScheduled = false;
437
+ return harness.transport.onDelta((delta: SyncDelta): void => {
438
+ pending.push(delta);
439
+ if (isScheduled) {
440
+ return;
441
+ }
442
+ isScheduled = true;
443
+ queueMicrotask(() => {
444
+ isScheduled = false;
445
+ callback(pending.splice(0));
446
+ });
447
+ });
448
+ },
449
+ };
450
+ const client = createSyncDb({...harness.config, transport: batchTransport});
451
+ await client.start();
452
+ await flush();
453
+ const baselineFetchCount = harness.http.state.fetchCount;
454
+ let tableListenerCount = 0;
455
+ const listenerId = client.store.raw.addTableListener("todos", () => {
456
+ tableListenerCount += 1;
457
+ });
458
+
459
+ harness.transport.deliverDelta(makeDelta({id: "t1", seq: 1}));
460
+ harness.transport.deliverDelta(makeDelta({id: "t2", seq: 2}));
461
+ // This jump must retain the existing reconcile hint behavior.
462
+ harness.transport.deliverDelta(makeDelta({id: "t3", seq: 4}));
463
+ await flush();
464
+
465
+ client.store.raw.delListener(listenerId);
466
+ expect(tableListenerCount).toBe(1);
467
+ expect(client.store.listEntities({collection: "todos"}).map((entity) => entity.id)).toEqual([
468
+ "t1",
469
+ "t2",
470
+ "t3",
471
+ ]);
472
+ expect(
473
+ client.debug
474
+ ?.getEvents()
475
+ .filter((event) => event.type === "delta")
476
+ .map((event) => ({entityId: event.entityId, seq: event.seq}))
477
+ ).toEqual([
478
+ {entityId: "t1", seq: 1},
479
+ {entityId: "t2", seq: 2},
480
+ {entityId: "t3", seq: 4},
481
+ ]);
482
+ expect(harness.http.state.fetchCount).toBe(baselineFetchCount + 1);
483
+ await client.stop();
484
+ });
485
+
419
486
  describe("reconcile triggers", () => {
420
487
  it("reconciles and replays when the transport (re)connects", async () => {
421
488
  const harness = makeHarness();
@@ -496,6 +563,21 @@ describe("createSyncDb", () => {
496
563
  await expect(client.reconcile()).resolves.toBeUndefined();
497
564
  await client.stop();
498
565
  });
566
+
567
+ it("window collection reconcile interval does not GET /sync/snapshot", async () => {
568
+ const snapshotStreams: string[] = [];
569
+ const harness = makeHarness({reconcileIntervalMs: 20, windowCollections: ["todos"]});
570
+ const fetchSnapshotPage = harness.http.channel.fetchSnapshotPage;
571
+ harness.http.channel.fetchSnapshotPage = async (args) => {
572
+ snapshotStreams.push(args.stream);
573
+ return fetchSnapshotPage(args);
574
+ };
575
+ const client = createSyncDb(harness.config);
576
+ await client.start();
577
+ await new Promise((resolve) => setTimeout(resolve, 70));
578
+ assert.deepEqual(snapshotStreams, []);
579
+ await client.stop();
580
+ });
499
581
  });
500
582
 
501
583
  describe("subscribe confirmation catch-up", () => {
@@ -554,6 +636,30 @@ describe("createSyncDb", () => {
554
636
  await client.stop();
555
637
  });
556
638
 
639
+ it("window subscribe confirmation does not GET /sync/snapshot", async () => {
640
+ const harness = makeHarness({windowCollections: ["todos"]});
641
+ const snapshotStreams: string[] = [];
642
+ const fetchSnapshotPage = harness.http.channel.fetchSnapshotPage;
643
+ harness.http.channel.fetchSnapshotPage = async (args) => {
644
+ snapshotStreams.push(args.stream);
645
+ return fetchSnapshotPage(args);
646
+ };
647
+ const client = createSyncDb(harness.config);
648
+ await client.start();
649
+ await flush();
650
+ snapshotStreams.length = 0;
651
+
652
+ harness.transport.confirmSubscribed({
653
+ collection: "todos",
654
+ mode: "window",
655
+ streams: ["todos|admin"],
656
+ });
657
+ await flush();
658
+
659
+ assert.deepEqual(snapshotStreams, []);
660
+ await client.stop();
661
+ });
662
+
557
663
  it("does not page while simulated-offline", async () => {
558
664
  const harness = makeHarness();
559
665
  const client = createSyncDb(harness.config);
@@ -829,7 +935,7 @@ describe("createSyncDb", () => {
829
935
 
830
936
  harness.auth.setUserId("u2");
831
937
  harness.auth.emitAuthChange();
832
- await flush();
938
+ await waitUntil(() => client.store.getLastUserId() === "u2");
833
939
  expect(client.store.listEntities({collection: "todos"})).toEqual([]);
834
940
  expect(client.store.getLastUserId()).toBe("u2");
835
941
  await client.stop();
@@ -2986,4 +3092,216 @@ describe("createSyncDb", () => {
2986
3092
  }
2987
3093
  });
2988
3094
  });
3095
+
3096
+ describe("forceResync", () => {
3097
+ it("skips when there is no HTTP channel", async () => {
3098
+ const harness = makeHarness();
3099
+ const client = createSyncDb({
3100
+ ...harness.config,
3101
+ httpChannel: undefined,
3102
+ });
3103
+ const result = await client.forceResync();
3104
+ assert.deepEqual(result, {
3105
+ ok: false,
3106
+ purged: 0,
3107
+ reason: "noHttpChannel",
3108
+ repaired: 0,
3109
+ streams: 0,
3110
+ });
3111
+ });
3112
+
3113
+ it("skips while simulated offline", async () => {
3114
+ const harness = makeHarness();
3115
+ const client = createSyncDb(harness.config);
3116
+ await client.start();
3117
+ client.goOffline();
3118
+ const result = await client.forceResync();
3119
+ assert.equal(result.ok, false);
3120
+ assert.equal(result.reason, "offline");
3121
+ await client.stop();
3122
+ });
3123
+
3124
+ it("skips while auth-paused", async () => {
3125
+ const harness = makeHarness();
3126
+ harness.http.state.streamsError = new AuthRequiredError();
3127
+ const client = createSyncDb(harness.config);
3128
+ await client.start();
3129
+ await flush();
3130
+ const result = await client.forceResync();
3131
+ assert.equal(result.ok, false);
3132
+ assert.equal(result.reason, "authPaused");
3133
+ await client.stop();
3134
+ });
3135
+
3136
+ it("skips when the server and local store have no streams", async () => {
3137
+ const harness = makeHarness();
3138
+ harness.http.state.streams = [];
3139
+ const client = createSyncDb(harness.config);
3140
+ await client.start();
3141
+ await flush();
3142
+ const result = await client.forceResync();
3143
+ assert.equal(result.ok, false);
3144
+ assert.equal(result.reason, "noStreams");
3145
+ await client.stop();
3146
+ });
3147
+
3148
+ it("purges local rows and re-bootstraps from the snapshot", async () => {
3149
+ const harness = makeHarness();
3150
+ harness.http.state.pages[DEFAULT_STREAM] = {
3151
+ cursor: 1,
3152
+ entities: [{data: {title: "stale"}, deleted: false, id: "local-1", seq: 1}],
3153
+ frontierSeq: 1,
3154
+ hasMore: false,
3155
+ oldestRetainedSeq: 0,
3156
+ stream: DEFAULT_STREAM,
3157
+ };
3158
+ const client = createSyncDb(harness.config);
3159
+ await client.start();
3160
+ await flush();
3161
+ assert.deepEqual(client.store.getEntity({collection: "todos", id: "local-1"})?.data, {
3162
+ title: "stale",
3163
+ });
3164
+
3165
+ harness.http.state.pages[DEFAULT_STREAM] = {
3166
+ cursor: 9,
3167
+ entities: [{data: {title: "fresh"}, deleted: false, id: "server-1", seq: 9}],
3168
+ frontierSeq: 9,
3169
+ hasMore: false,
3170
+ oldestRetainedSeq: 0,
3171
+ stream: DEFAULT_STREAM,
3172
+ };
3173
+ const result = await client.forceResync();
3174
+ assert.equal(result.ok, true);
3175
+ assert.isAtLeast(result.streams, 1);
3176
+ assert.isAtLeast(result.purged, 1);
3177
+ assert.equal(client.store.getEntity({collection: "todos", id: "local-1"}), undefined);
3178
+ assert.deepEqual(client.store.getEntity({collection: "todos", id: "server-1"})?.data, {
3179
+ title: "fresh",
3180
+ });
3181
+ await client.stop();
3182
+ });
3183
+
3184
+ it("falls back to locally known streams when discovery 401s", async () => {
3185
+ const harness = makeHarness();
3186
+ harness.http.state.pages[DEFAULT_STREAM] = {
3187
+ cursor: 2,
3188
+ entities: [{data: {title: "kept"}, deleted: false, id: "k1", seq: 2}],
3189
+ frontierSeq: 2,
3190
+ hasMore: false,
3191
+ oldestRetainedSeq: 0,
3192
+ stream: DEFAULT_STREAM,
3193
+ };
3194
+ const client = createSyncDb(harness.config);
3195
+ await client.start();
3196
+ await flush();
3197
+ harness.http.state.streamsError = new AuthRequiredError();
3198
+ const result = await client.forceResync();
3199
+ assert.equal(result.ok, true);
3200
+ assert.equal(result.streams, 1);
3201
+ assert.deepEqual(client.store.getEntity({collection: "todos", id: "k1"})?.data, {
3202
+ title: "kept",
3203
+ });
3204
+ await client.stop();
3205
+ });
3206
+
3207
+ it("pauses and reports authPaused when a snapshot page 401s mid-resync", async () => {
3208
+ const harness = makeHarness();
3209
+ const client = createSyncDb(harness.config);
3210
+ await client.start();
3211
+ await flush();
3212
+ harness.http.channel.fetchSnapshotPage = async () => {
3213
+ throw new AuthRequiredError();
3214
+ };
3215
+ const result = await client.forceResync();
3216
+ assert.equal(result.ok, false);
3217
+ assert.equal(result.reason, "authPaused");
3218
+ assert.equal(client.getSyncStatus().paused, "auth");
3219
+ await client.stop();
3220
+ });
3221
+
3222
+ it("rethrows a non-auth discovery error", async () => {
3223
+ const harness = makeHarness();
3224
+ const client = createSyncDb(harness.config);
3225
+ await client.start();
3226
+ await flush();
3227
+ harness.http.state.streamsError = new Error("resync boom");
3228
+ await expect(client.forceResync()).rejects.toThrow("resync boom");
3229
+ await client.stop();
3230
+ });
3231
+
3232
+ it("repairs marked entities after re-bootstrap", async () => {
3233
+ const harness = makeHarness();
3234
+ harness.http.state.pages[DEFAULT_STREAM] = {
3235
+ cursor: 1,
3236
+ entities: [{data: {title: "broken"}, deleted: false, id: "r1", seq: 1}],
3237
+ frontierSeq: 1,
3238
+ hasMore: false,
3239
+ oldestRetainedSeq: 0,
3240
+ stream: DEFAULT_STREAM,
3241
+ };
3242
+ const client = createSyncDb(harness.config);
3243
+ await client.start();
3244
+ await flush();
3245
+ client.store.markNeedsRepair({
3246
+ collection: "todos",
3247
+ entityId: "r1",
3248
+ missedSeq: 1,
3249
+ stream: DEFAULT_STREAM,
3250
+ });
3251
+ harness.http.channel.fetchEntities = async () => ({
3252
+ entities: [
3253
+ {
3254
+ data: {title: "repaired"},
3255
+ deleted: false,
3256
+ id: "r1",
3257
+ seq: 2,
3258
+ stream: DEFAULT_STREAM,
3259
+ },
3260
+ ],
3261
+ });
3262
+ const result = await client.forceResync();
3263
+ assert.equal(result.ok, true);
3264
+ await client.stop();
3265
+ });
3266
+
3267
+ it("abandons the resync when the user changes during discovery", async () => {
3268
+ const harness = makeHarness();
3269
+ const client = createSyncDb(harness.config);
3270
+ await client.start();
3271
+ await flush();
3272
+ const originalFetch = harness.http.channel.fetchStreams;
3273
+ harness.http.channel.fetchStreams = async () => {
3274
+ harness.auth.setUserId("other-user");
3275
+ harness.auth.emitAuthChange();
3276
+ for (let attempt = 0; attempt < 50; attempt += 1) {
3277
+ if (client.store.getLastUserId() === "other-user") {
3278
+ break;
3279
+ }
3280
+ await flush();
3281
+ }
3282
+ return originalFetch();
3283
+ };
3284
+ const result = await client.forceResync();
3285
+ assert.equal(result.ok, false);
3286
+ assert.equal(result.reason, "superseded");
3287
+ await client.stop();
3288
+ });
3289
+
3290
+ it("abandons the resync when the user changes during bootstrap", async () => {
3291
+ const harness = makeHarness();
3292
+ const client = createSyncDb(harness.config);
3293
+ await client.start();
3294
+ await flush();
3295
+ harness.http.channel.fetchSnapshotPage = async ({stream}) => {
3296
+ harness.auth.setUserId("other-user");
3297
+ harness.auth.emitAuthChange();
3298
+ await flush();
3299
+ return emptyPage(stream);
3300
+ };
3301
+ const result = await client.forceResync();
3302
+ assert.equal(result.ok, false);
3303
+ assert.equal(result.reason, "superseded");
3304
+ await client.stop();
3305
+ });
3306
+ });
2989
3307
  });
package/src/client.ts CHANGED
@@ -5,6 +5,7 @@ import {createServerKeyProvider, DEFAULT_KEY_CACHE_DB_NAME} from "./crypto/keyPr
5
5
  import type {KeyProvider} from "./crypto/types";
6
6
  import {attachDebugChannel, type DebugChannelBridge} from "./debug/debugChannel";
7
7
  import {resolveDebugLog, type SyncDebugLog, type SyncDebugLogOptions} from "./debug/debugLog";
8
+ import {registerSyncDbDevtools} from "./debug/devtools";
8
9
  import {getConflict, listConflicts, pruneGhostConflicts} from "./mutations/conflicts";
9
10
  import {createOutbox, generateMutationId, type Outbox} from "./mutations/outbox";
10
11
  import {resolveConflict as applyConflictResolution} from "./mutations/resolveConflict";
@@ -22,6 +23,7 @@ import {AuthRequiredError, createHttpChannel, type HttpChannel} from "./sync/htt
22
23
  import {createReplayCoordinator, type ReplayCoordinator} from "./sync/replayCoordinator";
23
24
  import {createSocketTransport} from "./sync/socketTransport";
24
25
  import type {SendMutationBatchResult, SendMutationResult, SyncTransport} from "./sync/transport";
26
+ import {type HydrateWindowEntitiesResult, hydrateWindowEntities} from "./sync/windowHydrate";
25
27
  import type {
26
28
  AuthProvider,
27
29
  ConflictResolutionStrategy,
@@ -67,6 +69,12 @@ export interface SyncDbConfig {
67
69
  baseUrl?: string;
68
70
  /** Transport override (tests inject a fake; default is the socket transport). */
69
71
  transport?: SyncTransport;
72
+ /**
73
+ * Optional selected organization id for `X-Organization-Id` on HTTP sync
74
+ * calls and the `organizationId` field on socket mutate payloads. Read at
75
+ * send time so admin org switches apply without reconnecting.
76
+ */
77
+ organizationIdProvider?: () => string | undefined;
70
78
  /** HTTP channel override (default is built from baseUrl when present). */
71
79
  httpChannel?: HttpChannel;
72
80
  /** Persister factory override (default is the platform default factory). */
@@ -83,6 +91,12 @@ export interface SyncDbConfig {
83
91
  idbSetImpl?: DefaultPersisterFactoryConfig["idbSetImpl"];
84
92
  /** Periodic reconcile interval in ms; 0 disables (default 5 minutes). */
85
93
  reconcileIntervalMs?: number;
94
+ /**
95
+ * Collections that subscribe in admin window mode: join `{collection}|admin`,
96
+ * skip `GET /sync/snapshot` paging (startup, catch-up, and the reconcile timer).
97
+ * Hydrate rows via REST membership + `/sync/entities` instead.
98
+ */
99
+ windowCollections?: string[];
86
100
  /** Rate limit for seq-jump-triggered reconciles per stream (default 30s). */
87
101
  seqJumpReconcileMinIntervalMs?: number;
88
102
  /** Millisecond clock, injectable for deterministic rate-limit tests. */
@@ -229,6 +243,15 @@ export interface SyncDb {
229
243
  mutate: (args: MutateArgs) => {mutationId: string; id: string};
230
244
  /** Snapshot-from-cursor catch-up for every collection (no-op without HTTP). */
231
245
  reconcile: () => Promise<void>;
246
+ /**
247
+ * Upsert a window of known ids (admin membership). Missing rows are fetched
248
+ * from `GET /sync/entities`; ids the server does not return are ignored.
249
+ */
250
+ hydrateWindow: (args: {
251
+ collection: string;
252
+ ids: string[];
253
+ restRows?: Record<string, unknown>;
254
+ }) => Promise<HydrateWindowEntitiesResult>;
232
255
  /**
233
256
  * Purge every known stream locally and re-bootstrap from cursor 0. Use when
234
257
  * devices have diverged and a full server snapshot is needed without wiping
@@ -295,17 +318,43 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
295
318
  authProvider: config.authProvider,
296
319
  // biome-ignore lint/style/noNonNullAssertion: guarded above — no transport implies baseUrl.
297
320
  baseUrl: config.baseUrl!,
321
+ organizationIdProvider: config.organizationIdProvider,
298
322
  });
299
323
  const httpChannel =
300
324
  config.httpChannel ??
301
325
  (config.baseUrl
302
- ? createHttpChannel({authProvider: config.authProvider, baseUrl: config.baseUrl})
326
+ ? createHttpChannel({
327
+ authProvider: config.authProvider,
328
+ baseUrl: config.baseUrl,
329
+ organizationIdProvider: config.organizationIdProvider,
330
+ })
303
331
  : undefined);
304
332
 
305
333
  const store = createSyncStore({
306
334
  collections: config.collections,
307
335
  now: () => DateTime.fromMillis(now()).toISO() ?? new Date(now()).toISOString(),
308
336
  });
337
+ const windowCollectionSet = new Set(config.windowCollections ?? []);
338
+ const isWindowCollection = (collection: string): boolean => windowCollectionSet.has(collection);
339
+ const skipSnapshotPaging = ({
340
+ collection,
341
+ stream,
342
+ mode,
343
+ }: {
344
+ collection: string;
345
+ stream: string;
346
+ mode?: "window";
347
+ }): boolean => isWindowCollection(collection) || mode === "window" || stream.endsWith("|admin");
348
+ const subscribeConfiguredCollections = (): void => {
349
+ const windowed = config.collections.filter((collection) => isWindowCollection(collection));
350
+ const full = config.collections.filter((collection) => !isWindowCollection(collection));
351
+ if (full.length > 0) {
352
+ transport.subscribe(full);
353
+ }
354
+ if (windowed.length > 0) {
355
+ transport.subscribe(windowed, {mode: "window"});
356
+ }
357
+ };
309
358
  const outbox = createOutbox({store});
310
359
  const debugLog = resolveDebugLog(config.debug);
311
360
  // Mirror the debug log across browser windows/tabs (web only) so a debugger
@@ -391,6 +440,15 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
391
440
  return result;
392
441
  };
393
442
 
443
+ const waitForLifecycleIdle = async (): Promise<void> => {
444
+ let pending = lifecycle;
445
+ await pending;
446
+ while (pending !== lifecycle) {
447
+ pending = lifecycle;
448
+ await pending;
449
+ }
450
+ };
451
+
394
452
  const notifyStatusChange = (): void => {
395
453
  for (const listener of statusListeners) {
396
454
  listener();
@@ -649,6 +707,9 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
649
707
  return;
650
708
  }
651
709
  for (const [stream, collection] of streams) {
710
+ if (skipSnapshotPaging({collection, stream})) {
711
+ continue;
712
+ }
652
713
  await bootstrapStream({channel: httpChannel, collection, store, stream});
653
714
  if (isSuperseded()) {
654
715
  return;
@@ -739,9 +800,11 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
739
800
  */
740
801
  const catchUpSubscribedStreams = async ({
741
802
  collection,
803
+ mode,
742
804
  streams,
743
805
  }: {
744
806
  collection: string;
807
+ mode?: "window";
745
808
  streams: string[];
746
809
  }): Promise<void> => {
747
810
  if (!httpChannel || simulatedOffline || authPaused || streams.length === 0) {
@@ -750,6 +813,9 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
750
813
  if (!store.collections.includes(collection)) {
751
814
  return;
752
815
  }
816
+ if (mode === "window" || isWindowCollection(collection)) {
817
+ return;
818
+ }
753
819
  const myGeneration = generation;
754
820
  const myUserId = currentUserId;
755
821
  const isSuperseded = (): boolean => generation !== myGeneration || currentUserId !== myUserId;
@@ -759,6 +825,9 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
759
825
  if (isSuperseded()) {
760
826
  return;
761
827
  }
828
+ if (skipSnapshotPaging({collection, mode, stream})) {
829
+ continue;
830
+ }
762
831
  store.addKnownStream({collection, stream});
763
832
  await bootstrapStream({channel: httpChannel, collection, store, stream});
764
833
  }
@@ -870,6 +939,7 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
870
939
  // the ways a device diverges in the first place, so it cannot be trusted as
871
940
  // the authoritative list for a repair operation.
872
941
  const streams = await syncStreams({isSuperseded});
942
+ await waitForLifecycleIdle();
873
943
  if (isSuperseded()) {
874
944
  return skip("superseded");
875
945
  }
@@ -898,6 +968,7 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
898
968
  purged += store.purgeStream({stream});
899
969
  store.addKnownStream({collection, stream});
900
970
  await bootstrapStream({channel: httpChannel, collection, store, stream});
971
+ await waitForLifecycleIdle();
901
972
  if (isSuperseded()) {
902
973
  return {ok: false, purged, reason: "superseded", repaired, streams: streamInfos.length};
903
974
  }
@@ -1247,13 +1318,32 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
1247
1318
  const bindDeltaHandler = (): void => {
1248
1319
  const myEpoch = connectionEpoch;
1249
1320
  const unbindPrevious = unbindDeltaHandler;
1250
- unbindDeltaHandler = transport.onDelta((delta: SyncDelta): void => {
1321
+ const isCurrentEpoch = (): boolean => {
1251
1322
  if (myEpoch !== connectionEpoch) {
1252
1323
  // A stale connection's delta arriving after a bounce for a new user.
1253
- return;
1324
+ return false;
1254
1325
  }
1255
- handleDelta(delta);
1256
- });
1326
+ return true;
1327
+ };
1328
+ if (transport.onDeltaBatch) {
1329
+ unbindDeltaHandler = transport.onDeltaBatch((deltas: SyncDelta[]): void => {
1330
+ if (!isCurrentEpoch()) {
1331
+ return;
1332
+ }
1333
+ store.raw.transaction(() => {
1334
+ for (const delta of deltas) {
1335
+ handleDelta(delta);
1336
+ }
1337
+ });
1338
+ });
1339
+ } else {
1340
+ unbindDeltaHandler = transport.onDelta((delta: SyncDelta): void => {
1341
+ if (!isCurrentEpoch()) {
1342
+ return;
1343
+ }
1344
+ handleDelta(delta);
1345
+ });
1346
+ }
1257
1347
  unbindPrevious?.();
1258
1348
  };
1259
1349
 
@@ -1280,7 +1370,7 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
1280
1370
  warn("transport reconnect after user change failed; continuing offline")(error);
1281
1371
  }
1282
1372
  bindDeltaHandler();
1283
- transport.subscribe(config.collections);
1373
+ subscribeConfiguredCollections();
1284
1374
  };
1285
1375
 
1286
1376
  const handleStatusChange = ({
@@ -1516,7 +1606,7 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
1516
1606
  if (generation !== myGeneration) {
1517
1607
  return;
1518
1608
  }
1519
- transport.subscribe(config.collections);
1609
+ subscribeConfiguredCollections();
1520
1610
  // C2: run an initial stream discovery + per-stream bootstrap on start (not only via
1521
1611
  // the reconnect status event) so a client that starts offline-then-online, or with a
1522
1612
  // warm socket, still backfills newly-joined streams and drains legacy cursors.
@@ -1647,6 +1737,7 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
1647
1737
  entityId,
1648
1738
  ...(maxAttempts !== undefined ? {maxAttempts} : {}),
1649
1739
  mutationId,
1740
+ ...(windowCollectionSet.has(collection) ? {mutationMode: "adminWindow" as const} : {}),
1650
1741
  operation,
1651
1742
  userId: currentUserId,
1652
1743
  });
@@ -1774,6 +1865,27 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
1774
1865
  return statuses;
1775
1866
  };
1776
1867
 
1868
+ const hydrateWindow = async ({
1869
+ collection,
1870
+ ids,
1871
+ restRows,
1872
+ }: {
1873
+ collection: string;
1874
+ ids: string[];
1875
+ restRows?: Record<string, unknown>;
1876
+ }): Promise<HydrateWindowEntitiesResult> => {
1877
+ if (!httpChannel) {
1878
+ throw new Error("hydrateWindow requires an HTTP channel");
1879
+ }
1880
+ return hydrateWindowEntities({
1881
+ channel: httpChannel,
1882
+ collection,
1883
+ ids,
1884
+ restRows,
1885
+ store,
1886
+ });
1887
+ };
1888
+
1777
1889
  const getSyncStatus = (): SyncStatus => {
1778
1890
  const drainProgress = currentUserId
1779
1891
  ? coordinator.getDrainProgress({userId: currentUserId})
@@ -1860,12 +1972,13 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
1860
1972
  }
1861
1973
  });
1862
1974
 
1863
- return {
1975
+ const client: SyncDb = {
1864
1976
  debug: debugLog,
1865
1977
  forceResync,
1866
1978
  getSyncStatus,
1867
1979
  goOffline,
1868
1980
  goOnline,
1981
+ hydrateWindow,
1869
1982
  mutate,
1870
1983
  onStatusChange,
1871
1984
  outbox,
@@ -1878,4 +1991,8 @@ export const createSyncDb = (config: SyncDbConfig): SyncDb => {
1878
1991
  stop,
1879
1992
  store,
1880
1993
  };
1994
+ if (debugLog) {
1995
+ registerSyncDbDevtools({client, name: config.name});
1996
+ }
1997
+ return client;
1881
1998
  };
@@ -1,6 +1,6 @@
1
1
  import {emitInterface} from "./emitTypes";
2
2
  import {friendlyHookNames} from "./hookNames";
3
- import {assertTsIdentifier, emitTsString} from "./safeIdentifiers";
3
+ import {assertSyncCollectionName, assertTsIdentifier, emitTsString} from "./safeIdentifiers";
4
4
  import type {CodegenConfigFile, DiscoveredCollection} from "./types";
5
5
 
6
6
  const GENERATED_HEADER = `// GENERATED by @terreno/syncdb (terreno-syncdb-codegen). Do not edit.
@@ -38,7 +38,7 @@ export const emitSdk = ({
38
38
  const names: string[] = [];
39
39
 
40
40
  for (const collection of collections) {
41
- const collectionName = assertTsIdentifier({
41
+ const collectionName = assertSyncCollectionName({
42
42
  label: "collection",
43
43
  value: collection.collection,
44
44
  });
@@ -60,7 +60,7 @@ export const emitSdk = ({
60
60
  typeBlocks.push(emitInterface({name: updateName, schema: collection.updateSchema}));
61
61
 
62
62
  const hooks = friendlyHookNames({
63
- collection: collectionName,
63
+ collection: collection.collection,
64
64
  entityName,
65
65
  });
66
66
  const list = assertTsIdentifier({label: "hook name", value: hooks.list});