@terreno/syncdb 57.2.0 → 57.4.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 (147) hide show
  1. package/README.md +13 -3
  2. package/dist/auth/betterAuthReactClient.d.ts +17 -0
  3. package/dist/auth/betterAuthReactClient.d.ts.map +1 -0
  4. package/dist/auth/betterAuthReactClient.js +11 -0
  5. package/dist/auth/betterAuthReactClient.js.map +1 -0
  6. package/dist/auth/betterAuthReactClient.test.d.ts +2 -0
  7. package/dist/auth/betterAuthReactClient.test.d.ts.map +1 -0
  8. package/dist/auth/betterAuthReactClient.test.js +43 -0
  9. package/dist/auth/betterAuthReactClient.test.js.map +1 -0
  10. package/dist/client.adminWindowMutation.test.d.ts +2 -0
  11. package/dist/client.adminWindowMutation.test.d.ts.map +1 -0
  12. package/dist/client.adminWindowMutation.test.js +65 -0
  13. package/dist/client.adminWindowMutation.test.js.map +1 -0
  14. package/dist/client.d.ts +22 -0
  15. package/dist/client.d.ts.map +1 -1
  16. package/dist/client.js +109 -7
  17. package/dist/client.js.map +1 -1
  18. package/dist/client.test.js +435 -2
  19. package/dist/client.test.js.map +1 -1
  20. package/dist/codegen/emitSdk.js +3 -3
  21. package/dist/codegen/emitSdk.js.map +1 -1
  22. package/dist/codegen/generate.test.js +122 -4
  23. package/dist/codegen/generate.test.js.map +1 -1
  24. package/dist/codegen/safeIdentifiers.d.ts +5 -0
  25. package/dist/codegen/safeIdentifiers.d.ts.map +1 -1
  26. package/dist/codegen/safeIdentifiers.js +8 -0
  27. package/dist/codegen/safeIdentifiers.js.map +1 -1
  28. package/dist/codegen/safeIdentifiers.test.js +20 -8
  29. package/dist/codegen/safeIdentifiers.test.js.map +1 -1
  30. package/dist/codegen/types.d.ts +4 -3
  31. package/dist/codegen/types.d.ts.map +1 -1
  32. package/dist/debug/debugChannel.test.js +5 -0
  33. package/dist/debug/debugChannel.test.js.map +1 -1
  34. package/dist/debug/debugLog.d.ts +1 -0
  35. package/dist/debug/debugLog.d.ts.map +1 -1
  36. package/dist/debug/debugLog.js +1 -0
  37. package/dist/debug/debugLog.js.map +1 -1
  38. package/dist/index.d.ts +1 -0
  39. package/dist/index.d.ts.map +1 -1
  40. package/dist/index.js +1 -0
  41. package/dist/index.js.map +1 -1
  42. package/dist/isolated/defaultPersisterFactoryNativeErrors.isolated.d.ts +2 -0
  43. package/dist/isolated/defaultPersisterFactoryNativeErrors.isolated.d.ts.map +1 -0
  44. package/dist/isolated/defaultPersisterFactoryNativeErrors.isolated.js +19 -0
  45. package/dist/isolated/defaultPersisterFactoryNativeErrors.isolated.js.map +1 -0
  46. package/dist/mutations/outbox.d.ts +7 -3
  47. package/dist/mutations/outbox.d.ts.map +1 -1
  48. package/dist/mutations/outbox.js +6 -0
  49. package/dist/mutations/outbox.js.map +1 -1
  50. package/dist/mutations/outbox.test.js +17 -0
  51. package/dist/mutations/outbox.test.js.map +1 -1
  52. package/dist/persisters/encryptedIndexedDbPersister.d.ts +2 -1
  53. package/dist/persisters/encryptedIndexedDbPersister.d.ts.map +1 -1
  54. package/dist/persisters/encryptedIndexedDbPersister.js +24 -0
  55. package/dist/persisters/encryptedIndexedDbPersister.js.map +1 -1
  56. package/dist/persisters/encryptedIndexedDbPersister.test.js +26 -0
  57. package/dist/persisters/encryptedIndexedDbPersister.test.js.map +1 -1
  58. package/dist/persisters/types.d.ts +9 -1
  59. package/dist/persisters/types.d.ts.map +1 -1
  60. package/dist/storage/idb.d.ts +1 -0
  61. package/dist/storage/idb.d.ts.map +1 -1
  62. package/dist/storage/idb.js +1 -0
  63. package/dist/storage/idb.js.map +1 -1
  64. package/dist/storage/schema.d.ts.map +1 -1
  65. package/dist/storage/schema.js +1 -0
  66. package/dist/storage/schema.js.map +1 -1
  67. package/dist/storage/store.d.ts +3 -2
  68. package/dist/storage/store.d.ts.map +1 -1
  69. package/dist/storage/types.d.ts +1 -7
  70. package/dist/storage/types.d.ts.map +1 -1
  71. package/dist/sync/deltaApplier.d.ts +2 -0
  72. package/dist/sync/deltaApplier.d.ts.map +1 -1
  73. package/dist/sync/deltaApplier.js +9 -0
  74. package/dist/sync/deltaApplier.js.map +1 -1
  75. package/dist/sync/deltaApplier.test.js +63 -0
  76. package/dist/sync/deltaApplier.test.js.map +1 -1
  77. package/dist/sync/entityRepair.d.ts +1 -0
  78. package/dist/sync/entityRepair.d.ts.map +1 -1
  79. package/dist/sync/entityRepair.js +1 -0
  80. package/dist/sync/entityRepair.js.map +1 -1
  81. package/dist/sync/httpChannel.d.ts +3 -1
  82. package/dist/sync/httpChannel.d.ts.map +1 -1
  83. package/dist/sync/httpChannel.js +3 -1
  84. package/dist/sync/httpChannel.js.map +1 -1
  85. package/dist/sync/httpChannel.test.js +68 -0
  86. package/dist/sync/httpChannel.test.js.map +1 -1
  87. package/dist/sync/replayCoordinator.d.ts +6 -12
  88. package/dist/sync/replayCoordinator.d.ts.map +1 -1
  89. package/dist/sync/replayCoordinator.js +9 -2
  90. package/dist/sync/replayCoordinator.js.map +1 -1
  91. package/dist/sync/socketTransport.d.ts +3 -45
  92. package/dist/sync/socketTransport.d.ts.map +1 -1
  93. package/dist/sync/socketTransport.js +31 -9
  94. package/dist/sync/socketTransport.js.map +1 -1
  95. package/dist/sync/socketTransport.test.js +7 -0
  96. package/dist/sync/socketTransport.test.js.map +1 -1
  97. package/dist/sync/transport.d.ts +3 -1
  98. package/dist/sync/transport.d.ts.map +1 -1
  99. package/dist/sync/windowHydrate.d.ts +25 -0
  100. package/dist/sync/windowHydrate.d.ts.map +1 -0
  101. package/dist/sync/windowHydrate.js +67 -0
  102. package/dist/sync/windowHydrate.js.map +1 -0
  103. package/dist/sync/windowHydrate.test.d.ts +2 -0
  104. package/dist/sync/windowHydrate.test.d.ts.map +1 -0
  105. package/dist/sync/windowHydrate.test.js +164 -0
  106. package/dist/sync/windowHydrate.test.js.map +1 -0
  107. package/dist/testing/fakeTransport.js +1 -1
  108. package/dist/testing/fakeTransport.js.map +1 -1
  109. package/dist/types.d.ts +23 -0
  110. package/dist/types.d.ts.map +1 -1
  111. package/package.json +17 -2
  112. package/src/auth/betterAuthReactClient.test.ts +50 -0
  113. package/src/auth/betterAuthReactClient.ts +33 -0
  114. package/src/client.adminWindowMutation.test.ts +69 -0
  115. package/src/client.test.ts +480 -2
  116. package/src/client.ts +147 -6
  117. package/src/codegen/emitSdk.ts +3 -3
  118. package/src/codegen/generate.test.ts +137 -4
  119. package/src/codegen/safeIdentifiers.test.ts +37 -10
  120. package/src/codegen/safeIdentifiers.ts +17 -0
  121. package/src/codegen/types.ts +3 -3
  122. package/src/debug/debugChannel.test.ts +6 -0
  123. package/src/debug/debugLog.ts +1 -0
  124. package/src/index.ts +4 -0
  125. package/src/isolated/defaultPersisterFactoryNativeErrors.isolated.ts +23 -0
  126. package/src/mutations/outbox.test.ts +20 -0
  127. package/src/mutations/outbox.ts +11 -3
  128. package/src/persisters/encryptedIndexedDbPersister.test.ts +29 -0
  129. package/src/persisters/encryptedIndexedDbPersister.ts +27 -1
  130. package/src/persisters/types.ts +10 -1
  131. package/src/storage/idb.ts +1 -0
  132. package/src/storage/schema.ts +1 -0
  133. package/src/storage/store.ts +2 -2
  134. package/src/storage/types.ts +1 -8
  135. package/src/sync/deltaApplier.test.ts +70 -0
  136. package/src/sync/deltaApplier.ts +10 -0
  137. package/src/sync/entityRepair.ts +1 -0
  138. package/src/sync/httpChannel.test.ts +82 -0
  139. package/src/sync/httpChannel.ts +5 -0
  140. package/src/sync/replayCoordinator.ts +10 -3
  141. package/src/sync/socketTransport.test.ts +10 -2
  142. package/src/sync/socketTransport.ts +64 -22
  143. package/src/sync/transport.ts +1 -1
  144. package/src/sync/windowHydrate.test.ts +179 -0
  145. package/src/sync/windowHydrate.ts +97 -0
  146. package/src/testing/fakeTransport.ts +1 -1
  147. package/src/types.ts +24 -0
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Isolated: mock expo-sqlite as missing or incomplete so loadExpoSqlite error
3
+ * paths do not leak into the rest of the suite.
4
+ */
5
+ import {describe, expect, it, mock} from "bun:test";
6
+
7
+ mock.module("expo-sqlite", () => ({}));
8
+ mock.module("tinybase/persisters/persister-expo-sqlite", () => ({
9
+ createExpoSqlitePersister: () => ({}),
10
+ }));
11
+
12
+ import {createDefaultPersisterFactory} from "../persisters/defaultPersisterFactory.native";
13
+ import {createSyncStore} from "../storage/store";
14
+
15
+ describe("createDefaultPersisterFactory (native errors)", () => {
16
+ it("throws when expo-sqlite has no openDatabaseSync", () => {
17
+ const factory = createDefaultPersisterFactory();
18
+ const store = createSyncStore({collections: ["todos"]});
19
+ expect(() => factory({databaseName: "terreno-syncdb.db", store: store.raw})).toThrow(
20
+ /expo-sqlite peer/
21
+ );
22
+ });
23
+ });
@@ -266,6 +266,26 @@ describe("state machine transitions", () => {
266
266
  expect(outbox.getMutation({mutationId: retry.mutationId})?.baseVersion).toBe(3);
267
267
  });
268
268
 
269
+ it("requeue preserves an admin-window mutation mode", () => {
270
+ const outbox = makeOutbox();
271
+ outbox.enqueue({
272
+ args: {title: "Admin retry"},
273
+ collection: "todos",
274
+ entityId: "t1",
275
+ mutationId: "m1",
276
+ mutationMode: "adminWindow",
277
+ operation: "update",
278
+ userId: "user-1",
279
+ });
280
+ outbox.markInFlight({mutationId: "m1"});
281
+ outbox.markConflicted({mutationId: "m1"});
282
+
283
+ const retry = outbox.requeue({baseVersion: 9, mutationId: "m1"});
284
+
285
+ expect(retry.mutationMode).toBe("adminWindow");
286
+ expect(outbox.getMutation({mutationId: retry.mutationId})?.mutationMode).toBe("adminWindow");
287
+ });
288
+
269
289
  it("requeue copies maxAttempts onto the cloned row", () => {
270
290
  const outbox = makeOutbox();
271
291
  outbox.enqueue({
@@ -3,11 +3,12 @@ import type {Row} from "tinybase";
3
3
 
4
4
  import type {SyncStore} from "../storage/store";
5
5
  import {CONFLICTS_TABLE, OUTBOX_TABLE, type OutboxRow} from "../storage/types";
6
- import type {OutboxMutation, OutboxStatus, SyncMutationOperation} from "../types";
6
+ import type {OutboxMutation, OutboxStatus, SyncMutationMode, SyncMutationOperation} from "../types";
7
7
 
8
8
  const defaultNow = (): string => DateTime.now().toISO();
9
9
 
10
10
  /** Default number of failed rows retained by `prune()` for debugging/UI. */
11
+ /** @internal */
11
12
  export const DEFAULT_KEEP_FAILED = 50;
12
13
 
13
14
  /** Generate a stable client mutation id (idempotency key). */
@@ -46,12 +47,13 @@ const rowToMutation = (mutationId: string, row: Partial<OutboxRow>): OutboxMutat
46
47
  errorNackCount: row.errorNackCount ?? 0,
47
48
  maxAttempts: typeof row.maxAttempts === "number" ? row.maxAttempts : undefined,
48
49
  mutationId,
50
+ mutationMode: row.mutationMode,
49
51
  operation: (row.operation ?? "update") as SyncMutationOperation,
50
52
  status: (row.status ?? "queued") as OutboxStatus,
51
53
  userId: row.userId ?? "",
52
54
  });
53
55
 
54
- export interface EnqueueArgs {
56
+ interface EnqueueArgs {
55
57
  collection: string;
56
58
  operation: SyncMutationOperation;
57
59
  entityId: string;
@@ -68,9 +70,11 @@ export interface EnqueueArgs {
68
70
  userId: string;
69
71
  /** Optional explicit id (defaults to a generated UUID; useful in tests). */
70
72
  mutationId?: string;
73
+ /** Admin-window marker persisted for replay after restart. */
74
+ mutationMode?: SyncMutationMode;
71
75
  }
72
76
 
73
- export interface RecoverStartupStateResult {
77
+ interface RecoverStartupStateResult {
74
78
  /** mutationIds that were stranded `inFlight` and moved back to `queued`. */
75
79
  recoveredInFlight: string[];
76
80
  /** entityIds whose stale `pendingMutationId` was cleared (acked-with-pending). */
@@ -255,6 +259,9 @@ export const createOutbox = ({
255
259
  if (args.maxAttempts !== undefined) {
256
260
  row.maxAttempts = args.maxAttempts;
257
261
  }
262
+ if (args.mutationMode !== undefined) {
263
+ row.mutationMode = args.mutationMode;
264
+ }
258
265
  store.raw.setRow(OUTBOX_TABLE, mutationId, row as unknown as Row);
259
266
  return rowToMutation(mutationId, row);
260
267
  };
@@ -353,6 +360,7 @@ export const createOutbox = ({
353
360
  enqueueOrder: row.enqueueOrder ?? 0,
354
361
  entityId: row.entityId ?? "",
355
362
  errorNackCount: 0,
363
+ ...(row.mutationMode !== undefined ? {mutationMode: row.mutationMode} : {}),
356
364
  operation: row.operation ?? "update",
357
365
  status: "queued",
358
366
  userId: row.userId ?? "",
@@ -1,6 +1,7 @@
1
1
  import "fake-indexeddb/auto";
2
2
 
3
3
  import {describe, expect, it, mock} from "bun:test";
4
+ import {assert} from "chai";
4
5
 
5
6
  import {createAesGcmCodec} from "../crypto/aesGcmCodec";
6
7
  import {identityCodec} from "../crypto/identityCodec";
@@ -303,6 +304,34 @@ describe("createEncryptedIndexedDbPersister", () => {
303
304
  expect(target.getEntity({collection: "todos", id: "t1"})?.data).toEqual({title: "three"});
304
305
  });
305
306
 
307
+ it("flush() persists the latest store state without waiting for the save debounce", async () => {
308
+ const databaseName = uniqueDbName();
309
+ const codec = createAesGcmCodec({key: await generateKey()});
310
+ const source = makeStore();
311
+ const persister = createEncryptedIndexedDbPersister({
312
+ codec,
313
+ databaseName,
314
+ saveDebounceMs: 500,
315
+ store: source.raw,
316
+ });
317
+ await persister.startAutoSave();
318
+
319
+ source.upsertEntity({collection: "todos", data: {title: "durable now"}, id: "t1"});
320
+ await persister.flush?.();
321
+
322
+ const target = makeStore();
323
+ await createEncryptedIndexedDbPersister({
324
+ codec,
325
+ databaseName,
326
+ saveDebounceMs: 0,
327
+ store: target.raw,
328
+ }).load();
329
+ assert.deepEqual(target.getEntity({collection: "todos", id: "t1"})?.data, {
330
+ title: "durable now",
331
+ });
332
+ await persister.destroy();
333
+ });
334
+
306
335
  it("destroy() cancels a pending debounced save and writes nothing after (E3e)", async () => {
307
336
  const databaseName = uniqueDbName();
308
337
  let encodeCount = 0;
@@ -3,6 +3,7 @@ import {createCustomPersister, type Persister, Persists} from "tinybase/persiste
3
3
 
4
4
  import type {PayloadCodec} from "../crypto/types";
5
5
  import {idbGet, idbSet} from "../storage/idb";
6
+ import type {SyncPersister} from "./types";
6
7
 
7
8
  /** Object-store record key holding the single encrypted blob. */
8
9
  const RECORD_KEY = "content";
@@ -66,7 +67,7 @@ export const createEncryptedIndexedDbPersister = ({
66
67
  idbGetImpl?: typeof idbGet;
67
68
  /** Test-only override for the IndexedDB write (default: the real `idbSet`). */
68
69
  idbSetImpl?: typeof idbSet;
69
- }): Persister<Persists.MergeableStoreOnly> => {
70
+ }): Persister<Persists.MergeableStoreOnly> & SyncPersister => {
70
71
  let lastWrittenJson: string | undefined;
71
72
  let pendingSave: PendingSave | undefined;
72
73
  // E3(e): the debounce timer scheduling `flushPendingSave` — tracked so
@@ -113,6 +114,30 @@ export const createEncryptedIndexedDbPersister = ({
113
114
  }
114
115
  };
115
116
 
117
+ const flush = async (): Promise<void> => {
118
+ if (pendingSaveTimer !== undefined) {
119
+ clearTimeout(pendingSaveTimer);
120
+ pendingSaveTimer = undefined;
121
+ }
122
+ const pending = pendingSave;
123
+ if (pending) {
124
+ await flushPendingSave();
125
+ await pending.promise;
126
+ return;
127
+ }
128
+
129
+ const json = JSON.stringify(store.getMergeableContent());
130
+ if (json === lastWrittenJson) {
131
+ return;
132
+ }
133
+ try {
134
+ await writeJson(json);
135
+ } catch (error) {
136
+ onSaveFailure?.(error);
137
+ throw error;
138
+ }
139
+ };
140
+
116
141
  const getPersisted = async (): Promise<MergeableContent | undefined> => {
117
142
  let payload: unknown;
118
143
  try {
@@ -214,5 +239,6 @@ export const createEncryptedIndexedDbPersister = ({
214
239
  pendingSave = undefined;
215
240
  return originalDestroy();
216
241
  },
242
+ flush,
217
243
  };
218
244
  };
@@ -30,7 +30,16 @@ export type PersisterFactory = ({
30
30
  onLoadFailure?: () => void;
31
31
  onSaveFailure?: (error: unknown) => void;
32
32
  };
33
- }) => AnyPersister;
33
+ }) => SyncPersister;
34
+
35
+ /**
36
+ * Persister capabilities used by the sync client beyond TinyBase's standard
37
+ * lifecycle. Web persistence exposes `flush` so durability-sensitive state
38
+ * transitions can bypass its normal trailing debounce.
39
+ */
40
+ export type SyncPersister = AnyPersister & {
41
+ flush?: () => Promise<void>;
42
+ };
34
43
 
35
44
  /**
36
45
  * Options accepted by `createDefaultPersisterFactory` on every platform. Each
@@ -85,6 +85,7 @@ export const idbSet = async ({
85
85
  };
86
86
 
87
87
  /** Delete a single key (no-op when absent). */
88
+ /** @internal */
88
89
  export const idbDelete = async ({
89
90
  databaseName,
90
91
  key,
@@ -84,6 +84,7 @@ export const buildTablesSchema = ({collections}: {collections: string[]}): Table
84
84
  entityId: {type: "string"},
85
85
  errorNackCount: {type: "number"},
86
86
  maxAttempts: {type: "number"},
87
+ mutationMode: {type: "string"},
87
88
  operation: {type: "string"},
88
89
  status: {type: "string"},
89
90
  userId: {type: "string"},
@@ -39,7 +39,7 @@ const rowToEntity = <TData>(id: string, row: Partial<EntityRow>): SyncEntity<TDa
39
39
  stream: row.stream ? row.stream : undefined,
40
40
  });
41
41
 
42
- export interface UpsertEntityArgs {
42
+ interface UpsertEntityArgs {
43
43
  collection: string;
44
44
  id: string;
45
45
  data: unknown;
@@ -53,7 +53,7 @@ export interface UpsertEntityArgs {
53
53
  stream?: string;
54
54
  }
55
55
 
56
- export interface CompactTombstonesResult {
56
+ interface CompactTombstonesResult {
57
57
  /** Number of tombstone rows removed (across all configured collections). */
58
58
  removed: number;
59
59
  }
@@ -66,14 +66,6 @@ export interface EntityRow {
66
66
  stream: string;
67
67
  }
68
68
 
69
- /** Primitive row shape for the `_knownStreams` table; rowId = stream key. */
70
- export interface KnownStreamRow {
71
- /** The collection tag the stream belongs to. */
72
- collection: string;
73
- /** When the stream was first bootstrapped. */
74
- addedAt: string;
75
- }
76
-
77
69
  /** Primitive row shape for the `_outbox` table; rowId = mutationId. */
78
70
  export interface OutboxRow {
79
71
  /** JSON-encoded mutation args. */
@@ -98,6 +90,7 @@ export interface OutboxRow {
98
90
  operation: SyncMutationOperation;
99
91
  status: OutboxStatus;
100
92
  userId: string;
93
+ mutationMode?: "adminWindow";
101
94
  }
102
95
 
103
96
  /** Primitive row shape for the `_cursors` table; rowId = stream key. */
@@ -1,4 +1,5 @@
1
1
  import {describe, expect, it} from "bun:test";
2
+ import {assert} from "chai";
2
3
 
3
4
  import {createSyncStore, type SyncStore} from "../storage/store";
4
5
  import {NEEDS_REPAIR_TABLE} from "../storage/types";
@@ -235,3 +236,72 @@ describe("applyDelta", () => {
235
236
  );
236
237
  });
237
238
  });
239
+
240
+ describe("applyDelta window |admin (Task 3.5)", () => {
241
+ const ADMIN_STREAM = "todos|admin";
242
+
243
+ it("is a no-op for an unknown id (no surprise insert) and still advances the cursor", () => {
244
+ const store = makeStore();
245
+ const result = applyDelta({
246
+ delta: makeDelta({
247
+ data: {title: "surprise"},
248
+ id: "unknown",
249
+ method: "create",
250
+ seq: 4,
251
+ stream: ADMIN_STREAM,
252
+ }),
253
+ store,
254
+ });
255
+ assert.isFalse(result.applied);
256
+ assert.isUndefined(store.getEntity({collection: "todos", id: "unknown"}));
257
+ assert.equal(getCursor({store, stream: ADMIN_STREAM}), 4);
258
+ });
259
+
260
+ it("updates a known id on the admin stream", () => {
261
+ const store = makeStore();
262
+ store.upsertEntity({
263
+ collection: "todos",
264
+ data: {title: "old"},
265
+ id: "t1",
266
+ seq: 1,
267
+ stream: ADMIN_STREAM,
268
+ });
269
+ const result = applyDelta({
270
+ delta: makeDelta({
271
+ data: {title: "new"},
272
+ method: "update",
273
+ seq: 2,
274
+ stream: ADMIN_STREAM,
275
+ }),
276
+ store,
277
+ });
278
+ assert.isTrue(result.applied);
279
+ assert.equal(
280
+ store.getEntity<{title: string}>({collection: "todos", id: "t1"})?.data.title,
281
+ "new"
282
+ );
283
+ });
284
+
285
+ it("delete delta removes a known id and ignores an unknown id", () => {
286
+ const store = makeStore();
287
+ store.upsertEntity({
288
+ collection: "todos",
289
+ data: {title: "gone"},
290
+ id: "t1",
291
+ seq: 1,
292
+ stream: ADMIN_STREAM,
293
+ });
294
+ const known = applyDelta({
295
+ delta: makeDelta({deleted: true, id: "t1", method: "delete", seq: 2, stream: ADMIN_STREAM}),
296
+ store,
297
+ });
298
+ const unknown = applyDelta({
299
+ delta: makeDelta({deleted: true, id: "nope", method: "delete", seq: 3, stream: ADMIN_STREAM}),
300
+ store,
301
+ });
302
+ assert.isTrue(known.applied);
303
+ assert.isTrue(store.getEntity({collection: "todos", id: "t1"})?.deleted);
304
+ assert.isFalse(unknown.applied);
305
+ assert.isUndefined(store.getEntity({collection: "todos", id: "nope"}));
306
+ });
307
+ });
@@ -22,6 +22,8 @@ export interface ApplyDeltaResult {
22
22
  * optimistic state is protected until conflict resolution decides;
23
23
  * - create/update writes data + seq; tombstones set `deleted: true` (keeping
24
24
  * the last known data for conflict UIs);
25
+ * - `{collection}|admin` window streams skip inserts for unknown ids (no surprise
26
+ * rows); Refresh is a REST re-query plus `hydrateWindow`, not a snapshot;
25
27
  * - the cursor for `delta.stream` advances in every case (including skips), so
26
28
  * a skipped delta is never re-fetched on catch-up.
27
29
  */
@@ -66,6 +68,14 @@ export const applyDelta = ({
66
68
  return {applied: false, seqJump};
67
69
  }
68
70
 
71
+ // Admin window (`{collection}|admin`): apply update/delete only for ids already
72
+ // in the local window. Unknown ids wait for REST membership + hydrateWindow
73
+ // (Refresh / load more). Cursor still advances so live seq is not replayed.
74
+ if (!existing && delta.stream.endsWith("|admin")) {
75
+ advanceCursor();
76
+ return {applied: false, seqJump};
77
+ }
78
+
69
79
  const deleted = delta.deleted === true || delta.method === "delete";
70
80
  store.upsertEntity({
71
81
  collection: delta.collection,
@@ -12,6 +12,7 @@ export const MAX_REPAIR_FETCH_IDS = 100;
12
12
  * needs-repair mark) when the entity is still pending or conflicted so a
13
13
  * reconcile-time repair pass cannot clobber optimistic local state.
14
14
  */
15
+ /** @internal */
15
16
  export const applyRepairedEntity = ({
16
17
  store,
17
18
  collection,
@@ -57,6 +57,27 @@ describe("createHttpChannel", () => {
57
57
  expect(headersOf(requests[0]).Authorization).toBe("Bearer token-123");
58
58
  });
59
59
 
60
+ it("attaches X-Organization-Id when an organizationIdProvider returns an id", async () => {
61
+ const {fetchImpl, requests} = makeFetch(() =>
62
+ json({
63
+ cursor: 0,
64
+ entities: [],
65
+ frontierSeq: 0,
66
+ hasMore: false,
67
+ oldestRetainedSeq: 0,
68
+ stream: "todos|owner:u1",
69
+ })
70
+ );
71
+ const channel = createHttpChannel({
72
+ authProvider,
73
+ baseUrl: "http://api",
74
+ fetchImpl,
75
+ organizationIdProvider: () => "org-selected",
76
+ });
77
+ await channel.fetchSnapshotPage({cursor: 0, stream: "todos|owner:u1"});
78
+ expect(headersOf(requests[0])["X-Organization-Id"]).toBe("org-selected");
79
+ });
80
+
60
81
  it("forwards the legacyCursor token (C3) when provided", async () => {
61
82
  const page = {
62
83
  cursor: 0,
@@ -220,6 +241,67 @@ describe("createHttpChannel", () => {
220
241
  });
221
242
  });
222
243
 
244
+ describe("fetchEntities", () => {
245
+ it("GETs /sync/entities with collection and ids", async () => {
246
+ const body = {
247
+ entities: [{data: {title: "a"}, deleted: false, id: "a", seq: 1}],
248
+ };
249
+ const {fetchImpl, requests} = makeFetch(() => json(body));
250
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
251
+ await expect(channel.fetchEntities({collection: "todos", ids: ["a", "b"]})).resolves.toEqual(
252
+ body
253
+ );
254
+ expect(requests[0]?.input).toBe("http://api/sync/entities?collection=todos&ids=a%2Cb");
255
+ });
256
+
257
+ it("rejects on non-ok statuses", async () => {
258
+ const {fetchImpl} = makeFetch(() => json({}, 500));
259
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
260
+ await expect(channel.fetchEntities({collection: "todos", ids: ["a"]})).rejects.toThrow(
261
+ "status 500"
262
+ );
263
+ });
264
+ });
265
+
266
+ describe("sendMutationBatch", () => {
267
+ const batch = {
268
+ mutations: [
269
+ {
270
+ collection: "todos",
271
+ data: {title: "hi"},
272
+ id: "t1",
273
+ mutationId: "m1",
274
+ operation: "create" as const,
275
+ },
276
+ ],
277
+ };
278
+
279
+ it("maps 200 results to a results payload", async () => {
280
+ const results = [{ack: {id: "t1", mutationId: "m1", seq: 1}, type: "ack" as const}];
281
+ const {fetchImpl} = makeFetch(() => json({results}));
282
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
283
+ await expect(channel.sendMutationBatch?.(batch)).resolves.toEqual({results, type: "results"});
284
+ });
285
+
286
+ it("maps 404 to unsupported", async () => {
287
+ const {fetchImpl} = makeFetch(() => json({}, 404));
288
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
289
+ await expect(channel.sendMutationBatch?.(batch)).resolves.toEqual({type: "unsupported"});
290
+ });
291
+
292
+ it("rejects on non-JSON responses", async () => {
293
+ const {fetchImpl} = makeFetch(() => new Response("nope", {status: 500}));
294
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
295
+ await expect(channel.sendMutationBatch?.(batch)).rejects.toThrow("non-JSON");
296
+ });
297
+
298
+ it("rejects when results is missing", async () => {
299
+ const {fetchImpl} = makeFetch(() => json({}));
300
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
301
+ await expect(channel.sendMutationBatch?.(batch)).rejects.toThrow("status 200");
302
+ });
303
+ });
304
+
223
305
  it("uses global fetch when no fetchImpl is provided (network error path)", async () => {
224
306
  const channel = createHttpChannel({
225
307
  authProvider,
@@ -82,6 +82,8 @@ export interface HttpChannelConfig {
82
82
  authProvider: Pick<AuthProvider, "getToken">;
83
83
  /** Fetch implementation override for tests/SSR (defaults to global fetch). */
84
84
  fetchImpl?: FetchLike;
85
+ /** Selected organization id attached as `X-Organization-Id` when present. */
86
+ organizationIdProvider?: () => string | undefined;
85
87
  }
86
88
 
87
89
  /** Create an {@link HttpChannel} speaking @terreno/api's `/sync/*` routes. */
@@ -89,15 +91,18 @@ export const createHttpChannel = ({
89
91
  baseUrl,
90
92
  authProvider,
91
93
  fetchImpl,
94
+ organizationIdProvider,
92
95
  }: HttpChannelConfig): HttpChannel => {
93
96
  const fetcher: FetchLike = fetchImpl ?? ((input, init) => globalThis.fetch(input, init));
94
97
 
95
98
  const request = async (path: string, init?: RequestInit): Promise<Response> => {
96
99
  const token = await authProvider.getToken();
100
+ const organizationId = organizationIdProvider?.()?.trim();
97
101
  const headers: Record<string, string> = {
98
102
  Accept: "application/json",
99
103
  ...(init?.body !== undefined ? {"Content-Type": "application/json"} : {}),
100
104
  ...(token ? {Authorization: `Bearer ${token}`} : {}),
105
+ ...(organizationId ? {"X-Organization-Id": organizationId} : {}),
101
106
  };
102
107
  const response = await fetcher(`${baseUrl}${path}`, {...init, headers});
103
108
  if (response.status === 401) {
@@ -32,15 +32,18 @@ const debugBody = (mutation: OutboxMutation): Record<string, unknown> | string =
32
32
  };
33
33
 
34
34
  /** Error-nack retries beyond this attempt count become terminal failures. */
35
+ /** @internal */
35
36
  export const MAX_ERROR_NACK_ATTEMPTS = 5;
36
37
 
37
38
  /** Base delay for the error-nack exponential backoff (doubles per attempt). */
39
+ /** @internal */
38
40
  export const ERROR_NACK_BASE_BACKOFF_MS = 1_000;
39
41
 
40
42
  /** Base delay for transport-failure backoff (unlimited retries, same cap/jitter shape). */
41
- export const TRANSPORT_FAILURE_BASE_BACKOFF_MS = 1_000;
43
+ const TRANSPORT_FAILURE_BASE_BACKOFF_MS = 1_000;
42
44
 
43
45
  /** Cap applied to every jittered backoff (error-nack and transport-failure alike). */
46
+ /** @internal */
44
47
  export const MAX_BACKOFF_MS = 30_000;
45
48
 
46
49
  /**
@@ -51,7 +54,7 @@ export const MAX_BACKOFF_MS = 30_000;
51
54
  * produce one stray `unsupported`) must never permanently downgrade the
52
55
  * session to single-sends.
53
56
  */
54
- export const BATCH_UNSUPPORTED_LATCH_THRESHOLD = 2;
57
+ const BATCH_UNSUPPORTED_LATCH_THRESHOLD = 2;
55
58
 
56
59
  /**
57
60
  * FIX 5: while latched `batchUnsupported`, re-probe batch support on this
@@ -59,9 +62,10 @@ export const BATCH_UNSUPPORTED_LATCH_THRESHOLD = 2;
59
62
  * sends to an upgraded instance, or the original instance could itself be
60
63
  * upgraded, without the connection ever dropping.
61
64
  */
65
+ /** @internal */
62
66
  export const BATCH_UNSUPPORTED_REPROBE_INTERVAL_MS = 60_000;
63
67
 
64
- export interface ReplayResult {
68
+ interface ReplayResult {
65
69
  /** Set when replay stopped early because the server rejected our auth. */
66
70
  paused?: "auth";
67
71
  }
@@ -384,6 +388,9 @@ export const createReplayCoordinator = ({
384
388
  request.data = {};
385
389
  }
386
390
  }
391
+ if (mutation.mutationMode !== undefined) {
392
+ request.mutationMode = mutation.mutationMode;
393
+ }
387
394
  return request;
388
395
  };
389
396
 
@@ -20,7 +20,7 @@ interface TestServer {
20
20
  /** Sockets that have connected, most recent last. */
21
21
  sockets: ServerSocket[];
22
22
  /** sync:subscribe payloads received, in order. */
23
- subscribes: {collections: string[]}[];
23
+ subscribes: {collections: string[]; mode?: string}[];
24
24
  /** Handler answering sync:mutate; replace per test. */
25
25
  mutateHandler: (request: SyncMutateRequest, socket: ServerSocket) => void;
26
26
  /** Handler answering sync:mutateBatch; replace per test (no-op = unsupported). */
@@ -53,7 +53,7 @@ const startServer = async (): Promise<TestServer> => {
53
53
  };
54
54
  io.on("connection", (socket) => {
55
55
  server.sockets.push(socket);
56
- socket.on("sync:subscribe", (payload: {collections: string[]}) => {
56
+ socket.on("sync:subscribe", (payload: {collections: string[]; mode?: string}) => {
57
57
  server.subscribes.push(payload);
58
58
  });
59
59
  socket.on("sync:mutate", (request: SyncMutateRequest) => {
@@ -142,6 +142,14 @@ describe("createSocketTransport", () => {
142
142
  expect(server.sockets).toHaveLength(1);
143
143
  });
144
144
 
145
+ it("subscribe emits window mode for window collections", async () => {
146
+ const subscriber = makeTransport();
147
+ subscriber.subscribe(["todos"], {mode: "window"});
148
+ await subscriber.connect();
149
+ await waitUntil(() => server.subscribes.length === 1);
150
+ expect(server.subscribes).toEqual([{collections: ["todos"], mode: "window"}]);
151
+ });
152
+
145
153
  it("subscribe emits sync:subscribe when connected and replays it on connect", async () => {
146
154
  const subscriber = makeTransport();
147
155
  // Subscribed before connect: sent once the connection opens.