@terreno/syncdb 56.0.0-beta.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 (317) hide show
  1. package/README.md +419 -0
  2. package/dist/auth/betterAuthAdapter.d.ts +22 -0
  3. package/dist/auth/betterAuthAdapter.d.ts.map +1 -0
  4. package/dist/auth/betterAuthAdapter.js +181 -0
  5. package/dist/auth/betterAuthAdapter.js.map +1 -0
  6. package/dist/auth/betterAuthAdapter.test.d.ts +2 -0
  7. package/dist/auth/betterAuthAdapter.test.d.ts.map +1 -0
  8. package/dist/auth/betterAuthAdapter.test.js +350 -0
  9. package/dist/auth/betterAuthAdapter.test.js.map +1 -0
  10. package/dist/auth/types.d.ts +42 -0
  11. package/dist/auth/types.d.ts.map +1 -0
  12. package/dist/auth/types.js +9 -0
  13. package/dist/auth/types.js.map +1 -0
  14. package/dist/client.d.ts +246 -0
  15. package/dist/client.d.ts.map +1 -0
  16. package/dist/client.js +1415 -0
  17. package/dist/client.js.map +1 -0
  18. package/dist/client.test.d.ts +2 -0
  19. package/dist/client.test.d.ts.map +1 -0
  20. package/dist/client.test.js +2310 -0
  21. package/dist/client.test.js.map +1 -0
  22. package/dist/crypto/aesGcmCodec.d.ts +33 -0
  23. package/dist/crypto/aesGcmCodec.d.ts.map +1 -0
  24. package/dist/crypto/aesGcmCodec.js +80 -0
  25. package/dist/crypto/aesGcmCodec.js.map +1 -0
  26. package/dist/crypto/aesGcmCodec.test.d.ts +2 -0
  27. package/dist/crypto/aesGcmCodec.test.d.ts.map +1 -0
  28. package/dist/crypto/aesGcmCodec.test.js +83 -0
  29. package/dist/crypto/aesGcmCodec.test.js.map +1 -0
  30. package/dist/crypto/identityCodec.d.ts +7 -0
  31. package/dist/crypto/identityCodec.d.ts.map +1 -0
  32. package/dist/crypto/identityCodec.js +9 -0
  33. package/dist/crypto/identityCodec.js.map +1 -0
  34. package/dist/crypto/keyProviders.d.ts +34 -0
  35. package/dist/crypto/keyProviders.d.ts.map +1 -0
  36. package/dist/crypto/keyProviders.js +102 -0
  37. package/dist/crypto/keyProviders.js.map +1 -0
  38. package/dist/crypto/keyProviders.test.d.ts +2 -0
  39. package/dist/crypto/keyProviders.test.d.ts.map +1 -0
  40. package/dist/crypto/keyProviders.test.js +189 -0
  41. package/dist/crypto/keyProviders.test.js.map +1 -0
  42. package/dist/crypto/types.d.ts +24 -0
  43. package/dist/crypto/types.d.ts.map +1 -0
  44. package/dist/crypto/types.js +8 -0
  45. package/dist/crypto/types.js.map +1 -0
  46. package/dist/debug/debugChannel.d.ts +52 -0
  47. package/dist/debug/debugChannel.d.ts.map +1 -0
  48. package/dist/debug/debugChannel.js +73 -0
  49. package/dist/debug/debugChannel.js.map +1 -0
  50. package/dist/debug/debugChannel.test.d.ts +2 -0
  51. package/dist/debug/debugChannel.test.d.ts.map +1 -0
  52. package/dist/debug/debugChannel.test.js +105 -0
  53. package/dist/debug/debugChannel.test.js.map +1 -0
  54. package/dist/debug/debugLog.d.ts +111 -0
  55. package/dist/debug/debugLog.d.ts.map +1 -0
  56. package/dist/debug/debugLog.js +150 -0
  57. package/dist/debug/debugLog.js.map +1 -0
  58. package/dist/debug/debugLog.test.d.ts +2 -0
  59. package/dist/debug/debugLog.test.d.ts.map +1 -0
  60. package/dist/debug/debugLog.test.js +121 -0
  61. package/dist/debug/debugLog.test.js.map +1 -0
  62. package/dist/index.d.ts +46 -0
  63. package/dist/index.d.ts.map +1 -0
  64. package/dist/index.js +51 -0
  65. package/dist/index.js.map +1 -0
  66. package/dist/isolated/defaultPersisterFactoryNative.isolated.d.ts +2 -0
  67. package/dist/isolated/defaultPersisterFactoryNative.isolated.d.ts.map +1 -0
  68. package/dist/isolated/defaultPersisterFactoryNative.isolated.js +38 -0
  69. package/dist/isolated/defaultPersisterFactoryNative.isolated.js.map +1 -0
  70. package/dist/mutations/conflicts.d.ts +31 -0
  71. package/dist/mutations/conflicts.d.ts.map +1 -0
  72. package/dist/mutations/conflicts.js +73 -0
  73. package/dist/mutations/conflicts.js.map +1 -0
  74. package/dist/mutations/outbox.d.ts +174 -0
  75. package/dist/mutations/outbox.d.ts.map +1 -0
  76. package/dist/mutations/outbox.js +385 -0
  77. package/dist/mutations/outbox.js.map +1 -0
  78. package/dist/mutations/outbox.test.d.ts +2 -0
  79. package/dist/mutations/outbox.test.d.ts.map +1 -0
  80. package/dist/mutations/outbox.test.js +643 -0
  81. package/dist/mutations/outbox.test.js.map +1 -0
  82. package/dist/mutations/resolveConflict.d.ts +32 -0
  83. package/dist/mutations/resolveConflict.d.ts.map +1 -0
  84. package/dist/mutations/resolveConflict.js +101 -0
  85. package/dist/mutations/resolveConflict.js.map +1 -0
  86. package/dist/mutations/resolveConflict.test.d.ts +2 -0
  87. package/dist/mutations/resolveConflict.test.d.ts.map +1 -0
  88. package/dist/mutations/resolveConflict.test.js +282 -0
  89. package/dist/mutations/resolveConflict.test.js.map +1 -0
  90. package/dist/persisters/defaultPersisterFactory.d.ts +9 -0
  91. package/dist/persisters/defaultPersisterFactory.d.ts.map +1 -0
  92. package/dist/persisters/defaultPersisterFactory.js +9 -0
  93. package/dist/persisters/defaultPersisterFactory.js.map +1 -0
  94. package/dist/persisters/defaultPersisterFactory.native.d.ts +10 -0
  95. package/dist/persisters/defaultPersisterFactory.native.d.ts.map +1 -0
  96. package/dist/persisters/defaultPersisterFactory.native.js +44 -0
  97. package/dist/persisters/defaultPersisterFactory.native.js.map +1 -0
  98. package/dist/persisters/defaultPersisterFactory.test.d.ts +2 -0
  99. package/dist/persisters/defaultPersisterFactory.test.d.ts.map +1 -0
  100. package/dist/persisters/defaultPersisterFactory.test.js +177 -0
  101. package/dist/persisters/defaultPersisterFactory.test.js.map +1 -0
  102. package/dist/persisters/defaultPersisterFactory.web.d.ts +17 -0
  103. package/dist/persisters/defaultPersisterFactory.web.d.ts.map +1 -0
  104. package/dist/persisters/defaultPersisterFactory.web.js +65 -0
  105. package/dist/persisters/defaultPersisterFactory.web.js.map +1 -0
  106. package/dist/persisters/encryptedIndexedDbPersister.d.ts +46 -0
  107. package/dist/persisters/encryptedIndexedDbPersister.d.ts.map +1 -0
  108. package/dist/persisters/encryptedIndexedDbPersister.js +171 -0
  109. package/dist/persisters/encryptedIndexedDbPersister.js.map +1 -0
  110. package/dist/persisters/encryptedIndexedDbPersister.test.d.ts +2 -0
  111. package/dist/persisters/encryptedIndexedDbPersister.test.d.ts.map +1 -0
  112. package/dist/persisters/encryptedIndexedDbPersister.test.js +352 -0
  113. package/dist/persisters/encryptedIndexedDbPersister.test.js.map +1 -0
  114. package/dist/persisters/memoryPersister.d.ts +19 -0
  115. package/dist/persisters/memoryPersister.d.ts.map +1 -0
  116. package/dist/persisters/memoryPersister.js +31 -0
  117. package/dist/persisters/memoryPersister.js.map +1 -0
  118. package/dist/persisters/memoryPersister.test.d.ts +2 -0
  119. package/dist/persisters/memoryPersister.test.d.ts.map +1 -0
  120. package/dist/persisters/memoryPersister.test.js +113 -0
  121. package/dist/persisters/memoryPersister.test.js.map +1 -0
  122. package/dist/persisters/types.d.ts +65 -0
  123. package/dist/persisters/types.d.ts.map +1 -0
  124. package/dist/persisters/types.js +2 -0
  125. package/dist/persisters/types.js.map +1 -0
  126. package/dist/react/hooks.d.ts +132 -0
  127. package/dist/react/hooks.d.ts.map +1 -0
  128. package/dist/react/hooks.js +269 -0
  129. package/dist/react/hooks.js.map +1 -0
  130. package/dist/react/hooks.test.d.ts +2 -0
  131. package/dist/react/hooks.test.d.ts.map +1 -0
  132. package/dist/react/hooks.test.js +645 -0
  133. package/dist/react/hooks.test.js.map +1 -0
  134. package/dist/react/index.d.ts +11 -0
  135. package/dist/react/index.d.ts.map +1 -0
  136. package/dist/react/index.js +11 -0
  137. package/dist/react/index.js.map +1 -0
  138. package/dist/react/provider.d.ts +11 -0
  139. package/dist/react/provider.d.ts.map +1 -0
  140. package/dist/react/provider.js +17 -0
  141. package/dist/react/provider.js.map +1 -0
  142. package/dist/storage/idb.d.ts +27 -0
  143. package/dist/storage/idb.d.ts.map +1 -0
  144. package/dist/storage/idb.js +72 -0
  145. package/dist/storage/idb.js.map +1 -0
  146. package/dist/storage/idb.test.d.ts +2 -0
  147. package/dist/storage/idb.test.d.ts.map +1 -0
  148. package/dist/storage/idb.test.js +100 -0
  149. package/dist/storage/idb.test.js.map +1 -0
  150. package/dist/storage/purgeUnknownStream.test.d.ts +2 -0
  151. package/dist/storage/purgeUnknownStream.test.d.ts.map +1 -0
  152. package/dist/storage/purgeUnknownStream.test.js +64 -0
  153. package/dist/storage/purgeUnknownStream.test.js.map +1 -0
  154. package/dist/storage/schema.d.ts +33 -0
  155. package/dist/storage/schema.d.ts.map +1 -0
  156. package/dist/storage/schema.js +92 -0
  157. package/dist/storage/schema.js.map +1 -0
  158. package/dist/storage/store.d.ts +136 -0
  159. package/dist/storage/store.d.ts.map +1 -0
  160. package/dist/storage/store.js +275 -0
  161. package/dist/storage/store.js.map +1 -0
  162. package/dist/storage/store.test.d.ts +2 -0
  163. package/dist/storage/store.test.d.ts.map +1 -0
  164. package/dist/storage/store.test.js +357 -0
  165. package/dist/storage/store.test.js.map +1 -0
  166. package/dist/storage/types.d.ts +146 -0
  167. package/dist/storage/types.d.ts.map +1 -0
  168. package/dist/storage/types.js +32 -0
  169. package/dist/storage/types.js.map +1 -0
  170. package/dist/storage/wipe.d.ts +22 -0
  171. package/dist/storage/wipe.d.ts.map +1 -0
  172. package/dist/storage/wipe.js +43 -0
  173. package/dist/storage/wipe.js.map +1 -0
  174. package/dist/storage/wipe.test.d.ts +2 -0
  175. package/dist/storage/wipe.test.d.ts.map +1 -0
  176. package/dist/storage/wipe.test.js +95 -0
  177. package/dist/storage/wipe.test.js.map +1 -0
  178. package/dist/sync/bootstrap.d.ts +64 -0
  179. package/dist/sync/bootstrap.d.ts.map +1 -0
  180. package/dist/sync/bootstrap.js +160 -0
  181. package/dist/sync/bootstrap.js.map +1 -0
  182. package/dist/sync/bootstrap.test.d.ts +2 -0
  183. package/dist/sync/bootstrap.test.d.ts.map +1 -0
  184. package/dist/sync/bootstrap.test.js +447 -0
  185. package/dist/sync/bootstrap.test.js.map +1 -0
  186. package/dist/sync/cursor.d.ts +67 -0
  187. package/dist/sync/cursor.d.ts.map +1 -0
  188. package/dist/sync/cursor.js +74 -0
  189. package/dist/sync/cursor.js.map +1 -0
  190. package/dist/sync/cursor.test.d.ts +2 -0
  191. package/dist/sync/cursor.test.d.ts.map +1 -0
  192. package/dist/sync/cursor.test.js +73 -0
  193. package/dist/sync/cursor.test.js.map +1 -0
  194. package/dist/sync/deltaApplier.d.ts +30 -0
  195. package/dist/sync/deltaApplier.d.ts.map +1 -0
  196. package/dist/sync/deltaApplier.js +61 -0
  197. package/dist/sync/deltaApplier.js.map +1 -0
  198. package/dist/sync/deltaApplier.test.d.ts +2 -0
  199. package/dist/sync/deltaApplier.test.d.ts.map +1 -0
  200. package/dist/sync/deltaApplier.test.js +212 -0
  201. package/dist/sync/deltaApplier.test.js.map +1 -0
  202. package/dist/sync/entityRepair.d.ts +45 -0
  203. package/dist/sync/entityRepair.d.ts.map +1 -0
  204. package/dist/sync/entityRepair.js +91 -0
  205. package/dist/sync/entityRepair.js.map +1 -0
  206. package/dist/sync/entityRepair.test.d.ts +2 -0
  207. package/dist/sync/entityRepair.test.d.ts.map +1 -0
  208. package/dist/sync/entityRepair.test.js +146 -0
  209. package/dist/sync/entityRepair.test.js.map +1 -0
  210. package/dist/sync/httpChannel.d.ts +74 -0
  211. package/dist/sync/httpChannel.d.ts.map +1 -0
  212. package/dist/sync/httpChannel.js +123 -0
  213. package/dist/sync/httpChannel.js.map +1 -0
  214. package/dist/sync/httpChannel.test.d.ts +2 -0
  215. package/dist/sync/httpChannel.test.d.ts.map +1 -0
  216. package/dist/sync/httpChannel.test.js +215 -0
  217. package/dist/sync/httpChannel.test.js.map +1 -0
  218. package/dist/sync/replayCoordinator.d.ts +212 -0
  219. package/dist/sync/replayCoordinator.d.ts.map +1 -0
  220. package/dist/sync/replayCoordinator.js +1110 -0
  221. package/dist/sync/replayCoordinator.js.map +1 -0
  222. package/dist/sync/replayCoordinator.test.d.ts +2 -0
  223. package/dist/sync/replayCoordinator.test.d.ts.map +1 -0
  224. package/dist/sync/replayCoordinator.test.js +1496 -0
  225. package/dist/sync/replayCoordinator.test.js.map +1 -0
  226. package/dist/sync/socketTransport.d.ts +56 -0
  227. package/dist/sync/socketTransport.d.ts.map +1 -0
  228. package/dist/sync/socketTransport.js +292 -0
  229. package/dist/sync/socketTransport.js.map +1 -0
  230. package/dist/sync/socketTransport.test.d.ts +2 -0
  231. package/dist/sync/socketTransport.test.d.ts.map +1 -0
  232. package/dist/sync/socketTransport.test.js +346 -0
  233. package/dist/sync/socketTransport.test.js.map +1 -0
  234. package/dist/sync/transport.d.ts +80 -0
  235. package/dist/sync/transport.d.ts.map +1 -0
  236. package/dist/sync/transport.js +5 -0
  237. package/dist/sync/transport.js.map +1 -0
  238. package/dist/testing/fakeTransport.d.ts +55 -0
  239. package/dist/testing/fakeTransport.d.ts.map +1 -0
  240. package/dist/testing/fakeTransport.js +139 -0
  241. package/dist/testing/fakeTransport.js.map +1 -0
  242. package/dist/testing/fakeTransport.test.d.ts +2 -0
  243. package/dist/testing/fakeTransport.test.d.ts.map +1 -0
  244. package/dist/testing/fakeTransport.test.js +112 -0
  245. package/dist/testing/fakeTransport.test.js.map +1 -0
  246. package/dist/testing/index.d.ts +13 -0
  247. package/dist/testing/index.d.ts.map +1 -0
  248. package/dist/testing/index.js +13 -0
  249. package/dist/testing/index.js.map +1 -0
  250. package/dist/types.d.ts +271 -0
  251. package/dist/types.d.ts.map +1 -0
  252. package/dist/types.js +9 -0
  253. package/dist/types.js.map +1 -0
  254. package/package.json +71 -0
  255. package/src/auth/betterAuthAdapter.test.ts +455 -0
  256. package/src/auth/betterAuthAdapter.ts +214 -0
  257. package/src/auth/types.ts +49 -0
  258. package/src/client.test.ts +2670 -0
  259. package/src/client.ts +1748 -0
  260. package/src/crypto/aesGcmCodec.test.ts +103 -0
  261. package/src/crypto/aesGcmCodec.ts +98 -0
  262. package/src/crypto/identityCodec.ts +10 -0
  263. package/src/crypto/keyProviders.test.ts +228 -0
  264. package/src/crypto/keyProviders.ts +153 -0
  265. package/src/crypto/types.ts +23 -0
  266. package/src/debug/debugChannel.test.ts +121 -0
  267. package/src/debug/debugChannel.ts +112 -0
  268. package/src/debug/debugLog.test.ts +139 -0
  269. package/src/debug/debugLog.ts +272 -0
  270. package/src/index.ts +157 -0
  271. package/src/isolated/defaultPersisterFactoryNative.isolated.ts +45 -0
  272. package/src/mutations/conflicts.ts +108 -0
  273. package/src/mutations/outbox.test.ts +754 -0
  274. package/src/mutations/outbox.ts +585 -0
  275. package/src/mutations/resolveConflict.test.ts +338 -0
  276. package/src/mutations/resolveConflict.ts +115 -0
  277. package/src/persisters/defaultPersisterFactory.native.ts +53 -0
  278. package/src/persisters/defaultPersisterFactory.test.ts +207 -0
  279. package/src/persisters/defaultPersisterFactory.ts +12 -0
  280. package/src/persisters/defaultPersisterFactory.web.ts +78 -0
  281. package/src/persisters/encryptedIndexedDbPersister.test.ts +381 -0
  282. package/src/persisters/encryptedIndexedDbPersister.ts +218 -0
  283. package/src/persisters/memoryPersister.test.ts +136 -0
  284. package/src/persisters/memoryPersister.ts +52 -0
  285. package/src/persisters/types.ts +71 -0
  286. package/src/react/hooks.test.tsx +761 -0
  287. package/src/react/hooks.ts +409 -0
  288. package/src/react/index.ts +11 -0
  289. package/src/react/provider.tsx +27 -0
  290. package/src/storage/idb.test.ts +116 -0
  291. package/src/storage/idb.ts +112 -0
  292. package/src/storage/purgeUnknownStream.test.ts +74 -0
  293. package/src/storage/schema.ts +103 -0
  294. package/src/storage/store.test.ts +424 -0
  295. package/src/storage/store.ts +461 -0
  296. package/src/storage/types.ts +159 -0
  297. package/src/storage/wipe.test.ts +111 -0
  298. package/src/storage/wipe.ts +58 -0
  299. package/src/sync/bootstrap.test.ts +486 -0
  300. package/src/sync/bootstrap.ts +217 -0
  301. package/src/sync/cursor.test.ts +84 -0
  302. package/src/sync/cursor.ts +113 -0
  303. package/src/sync/deltaApplier.test.ts +237 -0
  304. package/src/sync/deltaApplier.ts +84 -0
  305. package/src/sync/entityRepair.test.ts +161 -0
  306. package/src/sync/entityRepair.ts +124 -0
  307. package/src/sync/httpChannel.test.ts +265 -0
  308. package/src/sync/httpChannel.ts +220 -0
  309. package/src/sync/replayCoordinator.test.ts +1709 -0
  310. package/src/sync/replayCoordinator.ts +1370 -0
  311. package/src/sync/socketTransport.test.ts +413 -0
  312. package/src/sync/socketTransport.ts +379 -0
  313. package/src/sync/transport.ts +76 -0
  314. package/src/testing/fakeTransport.test.ts +125 -0
  315. package/src/testing/fakeTransport.ts +206 -0
  316. package/src/testing/index.ts +18 -0
  317. package/src/types.ts +284 -0
@@ -0,0 +1,206 @@
1
+ /**
2
+ * In-memory {@link SyncTransport} double for tests and load harnesses. Published
3
+ * from the `@terreno/syncdb/testing` subpath so the main entry stays free of test
4
+ * doubles.
5
+ */
6
+
7
+ import type {
8
+ SendMutationBatchResult,
9
+ SendMutationResult,
10
+ SyncTransport,
11
+ TransportStatus,
12
+ } from "../sync/transport";
13
+ import type {
14
+ SyncAck,
15
+ SyncDelta,
16
+ SyncMutateBatchRequest,
17
+ SyncMutateRequest,
18
+ SyncNack,
19
+ } from "../types";
20
+
21
+ /** Computes the reply for a sent mutation (may reject to simulate transport failure). */
22
+ export type FakeMutationResponder = (
23
+ request: SyncMutateRequest
24
+ ) => SendMutationResult | Promise<SendMutationResult>;
25
+
26
+ /** Computes the reply for a sent batch (may reject to simulate transport failure). */
27
+ export type FakeBatchResponder = (
28
+ request: SyncMutateBatchRequest
29
+ ) => SendMutationBatchResult | Promise<SendMutationBatchResult>;
30
+
31
+ /** Test-facing controls layered on top of the {@link SyncTransport} contract. */
32
+ export interface FakeTransport extends SyncTransport {
33
+ /** Every mutation sent through the transport, in order. */
34
+ readonly sentMutations: SyncMutateRequest[];
35
+ /** Every batch sent through the transport (as arrays of mutationIds), in order. */
36
+ readonly sentBatches: string[][];
37
+ /** Distinct collections subscribed so far (union across subscribe calls). */
38
+ readonly subscribedCollections: string[];
39
+ /** Deliver a server delta to all onDelta listeners. */
40
+ deliverDelta: (delta: SyncDelta) => void;
41
+ /** Simulate a connect/disconnect; notifies status listeners on change. */
42
+ setConnected: (connected: boolean) => void;
43
+ /**
44
+ * Simulate the D1 server-side session re-validation sweep disconnecting this
45
+ * socket: a disconnect tagged `authExpired: true`, mirroring the real socket
46
+ * transport's `sync:auth-expired` + `disconnect` sequence.
47
+ */
48
+ disconnectWithAuthExpired: () => void;
49
+ /** Queue an ack for the next sendMutation (mutationId/id filled from the request). */
50
+ respondWithAck: (overrides?: Partial<SyncAck>) => void;
51
+ /** Queue a nack for the next sendMutation (mutationId filled from the request). */
52
+ respondWithNack: (nack: Partial<SyncNack> & Pick<SyncNack, "code">) => void;
53
+ /** Queue a one-shot responder for the next sendMutation (may throw/reject). */
54
+ respondWith: (responder: FakeMutationResponder) => void;
55
+ /** Replace the fallback responder used when the queue is empty (undefined = auto-ack). */
56
+ setDefaultResponder: (responder?: FakeMutationResponder) => void;
57
+ /**
58
+ * Replace the batch responder (undefined = auto-ack every mutation in the
59
+ * batch with monotonically increasing seqs, sharing the same counter as
60
+ * single-send auto-ack). Set to a responder returning `{type:
61
+ * "unsupported"}` to simulate an old server without batch support.
62
+ */
63
+ setBatchResponder: (responder?: FakeBatchResponder) => void;
64
+ /** Queue a one-shot responder for the next sendMutationBatch call only. */
65
+ respondBatchWith: (responder: FakeBatchResponder) => void;
66
+ }
67
+
68
+ /**
69
+ * In-memory transport double for unit tests: records sent mutations and
70
+ * subscriptions, lets tests deliver deltas and flip connectivity, and answers
71
+ * `sendMutation` from a one-shot responder queue (falling back to a default
72
+ * responder that acks every mutation with a monotonically increasing seq).
73
+ */
74
+ export const createFakeTransport = (): FakeTransport => {
75
+ const sentMutations: SyncMutateRequest[] = [];
76
+ const sentBatches: string[][] = [];
77
+ const subscribed = new Set<string>();
78
+ const deltaListeners = new Set<(delta: SyncDelta) => void>();
79
+ const statusListeners = new Set<(status: TransportStatus) => void>();
80
+ const responderQueue: FakeMutationResponder[] = [];
81
+ let connected = false;
82
+ let nextSeq = 0;
83
+
84
+ const autoAck: FakeMutationResponder = (request) => {
85
+ nextSeq += 1;
86
+ return {
87
+ ack: {id: request.id ?? `server-${nextSeq}`, mutationId: request.mutationId, seq: nextSeq},
88
+ type: "ack",
89
+ };
90
+ };
91
+ let defaultResponder: FakeMutationResponder = autoAck;
92
+
93
+ const autoAckBatch: FakeBatchResponder = (request) => ({
94
+ results: request.mutations.map((mutation) => {
95
+ nextSeq += 1;
96
+ return {
97
+ ack: {
98
+ id: mutation.id ?? `server-${nextSeq}`,
99
+ mutationId: mutation.mutationId,
100
+ seq: nextSeq,
101
+ },
102
+ type: "ack" as const,
103
+ };
104
+ }),
105
+ type: "results",
106
+ });
107
+ let batchResponder: FakeBatchResponder = autoAckBatch;
108
+ const batchResponderQueue: FakeBatchResponder[] = [];
109
+
110
+ const setConnected = (value: boolean): void => {
111
+ if (connected === value) {
112
+ return;
113
+ }
114
+ connected = value;
115
+ for (const listener of statusListeners) {
116
+ listener({connected: value});
117
+ }
118
+ };
119
+
120
+ return {
121
+ connect: async (): Promise<void> => {
122
+ setConnected(true);
123
+ },
124
+ deliverDelta: (delta: SyncDelta): void => {
125
+ for (const listener of deltaListeners) {
126
+ listener(delta);
127
+ }
128
+ },
129
+ disconnect: (): void => {
130
+ setConnected(false);
131
+ },
132
+ disconnectWithAuthExpired: (): void => {
133
+ connected = false;
134
+ for (const listener of statusListeners) {
135
+ listener({authExpired: true, connected: false});
136
+ }
137
+ },
138
+ onDelta: (callback: (delta: SyncDelta) => void): (() => void) => {
139
+ deltaListeners.add(callback);
140
+ return () => {
141
+ deltaListeners.delete(callback);
142
+ };
143
+ },
144
+ onStatusChange: (callback: (status: TransportStatus) => void): (() => void) => {
145
+ statusListeners.add(callback);
146
+ return () => {
147
+ statusListeners.delete(callback);
148
+ };
149
+ },
150
+ respondBatchWith: (responder: FakeBatchResponder): void => {
151
+ batchResponderQueue.push(responder);
152
+ },
153
+ respondWith: (responder: FakeMutationResponder): void => {
154
+ responderQueue.push(responder);
155
+ },
156
+ respondWithAck: (overrides?: Partial<SyncAck>): void => {
157
+ responderQueue.push((request) => {
158
+ nextSeq += 1;
159
+ return {
160
+ ack: {
161
+ id: request.id ?? `server-${nextSeq}`,
162
+ mutationId: request.mutationId,
163
+ seq: nextSeq,
164
+ ...overrides,
165
+ },
166
+ type: "ack",
167
+ };
168
+ });
169
+ },
170
+ respondWithNack: (nack: Partial<SyncNack> & Pick<SyncNack, "code">): void => {
171
+ responderQueue.push((request) => ({
172
+ nack: {mutationId: request.mutationId, ...nack},
173
+ type: "nack",
174
+ }));
175
+ },
176
+ sendMutation: async (request: SyncMutateRequest): Promise<SendMutationResult> => {
177
+ sentMutations.push(request);
178
+ const responder = responderQueue.shift() ?? defaultResponder;
179
+ return responder(request);
180
+ },
181
+ sendMutationBatch: async (
182
+ request: SyncMutateBatchRequest
183
+ ): Promise<SendMutationBatchResult> => {
184
+ sentBatches.push(request.mutations.map((mutation) => mutation.mutationId));
185
+ const responder = batchResponderQueue.shift() ?? batchResponder;
186
+ return responder(request);
187
+ },
188
+ sentBatches,
189
+ sentMutations,
190
+ setBatchResponder: (responder?: FakeBatchResponder): void => {
191
+ batchResponder = responder ?? autoAckBatch;
192
+ },
193
+ setConnected,
194
+ setDefaultResponder: (responder?: FakeMutationResponder): void => {
195
+ defaultResponder = responder ?? autoAck;
196
+ },
197
+ subscribe: (collections: string[]): void => {
198
+ for (const collection of collections) {
199
+ subscribed.add(collection);
200
+ }
201
+ },
202
+ get subscribedCollections(): string[] {
203
+ return [...subscribed];
204
+ },
205
+ };
206
+ };
@@ -0,0 +1,18 @@
1
+ /**
2
+ * `@terreno/syncdb/testing` — test-only helpers.
3
+ *
4
+ * Doubles and harness utilities live here rather than on the main entry so a
5
+ * production bundle never reaches them and they carry no API-stability promise
6
+ * beyond "useful in tests". Import them explicitly:
7
+ *
8
+ * ```ts
9
+ * import {createFakeTransport} from "@terreno/syncdb/testing";
10
+ * ```
11
+ */
12
+
13
+ export {
14
+ createFakeTransport,
15
+ type FakeBatchResponder,
16
+ type FakeMutationResponder,
17
+ type FakeTransport,
18
+ } from "./fakeTransport";
package/src/types.ts ADDED
@@ -0,0 +1,284 @@
1
+ /**
2
+ * Core types for @terreno/syncdb.
3
+ *
4
+ * The protocol types (deltas, mutations, acks) mirror the server contract defined in
5
+ * @terreno/api's `src/sync/types.ts` — they are duplicated intentionally so this
6
+ * frontend package carries no backend dependency. Keep the two in lockstep.
7
+ */
8
+
9
+ export type SyncMutationOperation = "create" | "update" | "delete";
10
+
11
+ /** A change event delivered by the server via `sync:delta`. */
12
+ export interface SyncDelta {
13
+ /** Collection tag (e.g. "todos"). */
14
+ collection: string;
15
+ /** Document id. */
16
+ id: string;
17
+ method: SyncMutationOperation;
18
+ /** Serialized document data (omitted for tombstone deltas emitted to a previous stream). */
19
+ data?: unknown;
20
+ /** The document's per-stream sequence (`_syncSeq`). */
21
+ seq: number;
22
+ /** Stream key this delta belongs to (e.g. "todos|owner:123"). */
23
+ stream: string;
24
+ /**
25
+ * C1: the stream's stable frontier at emit time. The client advances its cursor to
26
+ * `min(seq, frontierSeq)` so a delta observed out of commit order never advances a
27
+ * cursor past an uncommitted hole. Absent from older servers (treated as `seq`).
28
+ */
29
+ frontierSeq?: number;
30
+ /** True when the entity is soft-deleted. */
31
+ deleted?: boolean;
32
+ }
33
+
34
+ /** A client mutation sent via `sync:mutate` or `POST /sync/mutate`. */
35
+ export interface SyncMutateRequest {
36
+ /** Client-generated stable id; the idempotency key. */
37
+ mutationId: string;
38
+ collection: string;
39
+ operation: SyncMutationOperation;
40
+ /** Target document id (required for update/delete). */
41
+ id?: string;
42
+ /** Fields to write (create/update). */
43
+ data?: Record<string, unknown>;
44
+ /** The seq the client last saw for this document; enables LWW conflict detection. */
45
+ baseVersion?: number;
46
+ }
47
+
48
+ /** Successful mutation acknowledgement. */
49
+ export interface SyncAck {
50
+ mutationId: string;
51
+ /** The document id (server-assigned for creates). */
52
+ id: string;
53
+ /** The document's new seq. */
54
+ seq: number;
55
+ /**
56
+ * Set when the document write succeeded but the server's post-hook threw
57
+ * (informational only — never a reason to retry, roll back, or treat this
58
+ * as anything other than a full success).
59
+ */
60
+ warning?: string;
61
+ }
62
+
63
+ export type SyncNackCode = "conflict" | "unauthorized" | "validation" | "error" | "rate_limited";
64
+
65
+ /** Rejected mutation. Conflict nacks carry the canonical server document. */
66
+ export interface SyncNack {
67
+ mutationId: string;
68
+ code: SyncNackCode;
69
+ /** Canonical serialized server document (conflict nacks). */
70
+ serverDoc?: unknown;
71
+ /** The server document's current seq (conflict nacks). */
72
+ serverSeq?: number;
73
+ /**
74
+ * Set when the conflicting server state is a tombstone rather than a live
75
+ * document (deleted, hard-deleted, or moved out of this client's scope), so
76
+ * `useServer` resolution writes a tombstone instead of a null-data ghost row.
77
+ * A server that omits it is still handled: `serverDoc: null` at a non-zero
78
+ * `serverSeq` means the same thing (see {@link SyncConflict.serverDeleted}).
79
+ */
80
+ serverDeleted?: boolean;
81
+ message?: string;
82
+ /**
83
+ * Minimum time (ms) the client should wait before retrying, filled by the
84
+ * server with the remaining rate-limit window (`rate_limited` nacks only).
85
+ */
86
+ retryAfterMs?: number;
87
+ }
88
+
89
+ /**
90
+ * A batch of client mutations sent via `sync:mutateBatch` or
91
+ * `POST /sync/mutate/batch`. The server applies strictly in array order and
92
+ * stops at the first non-ack outcome.
93
+ */
94
+ export interface SyncMutateBatchRequest {
95
+ /** Ordered mutations; each still carries its own mutationId. */
96
+ mutations: SyncMutateRequest[];
97
+ /**
98
+ * Client-generated correlation id, socket transport only (ignored over
99
+ * HTTP). Echoed back immediately via `sync:batchReceived {batchId}` before
100
+ * processing begins, distinguishing "unsupported" (silence past the grace
101
+ * period) from "slow" (a receipt arrived; keep waiting).
102
+ */
103
+ batchId?: string;
104
+ }
105
+
106
+ /** One result per PROCESSED mutation in a batch, in request order. */
107
+ export type SyncMutateBatchResult = {type: "ack"; ack: SyncAck} | {type: "nack"; nack: SyncNack};
108
+
109
+ /**
110
+ * Response to a batch mutation request.
111
+ *
112
+ * `results.length < request.mutations.length` means the server halted at the
113
+ * first non-ack: `results[results.length - 1]` is that failing outcome, and
114
+ * every mutation after it was NOT attempted — still safe to resend later.
115
+ */
116
+ export interface SyncMutateBatchResponse {
117
+ results: SyncMutateBatchResult[];
118
+ }
119
+
120
+ /** One entity in a `GET /sync/snapshot` page. */
121
+ export interface SyncSnapshotEntity {
122
+ id: string;
123
+ data: unknown;
124
+ seq: number;
125
+ deleted: boolean;
126
+ }
127
+
128
+ /** Response shape of `GET /sync/entities` (point lookup for repair). */
129
+ export interface SyncEntitiesResponse {
130
+ entities: SyncSnapshotEntity[];
131
+ }
132
+
133
+ /** Response shape of `GET /sync/snapshot` (C2: one stream per request). */
134
+ export interface SyncSnapshotResponse {
135
+ /** The stream this page belongs to (echoed from the request). */
136
+ stream: string;
137
+ entities: SyncSnapshotEntity[];
138
+ /** Highest seq in this page (never above `frontierSeq`); pass back as `cursor`. */
139
+ cursor: number;
140
+ hasMore: boolean;
141
+ /** C1: the stream's stable frontier — the client must not advance its cursor beyond this. */
142
+ frontierSeq: number;
143
+ /**
144
+ * C7: the lowest seq still retained for the stream. A stored cursor below this means
145
+ * compacted tombstones may have been missed → re-bootstrap the stream from 0.
146
+ */
147
+ oldestRetainedSeq: number;
148
+ /**
149
+ * C3: opaque forward token for paging the legacy (seq-0) stratum by `_id`. Echoed back
150
+ * verbatim until absent (stratum exhausted), then paging proceeds by seq.
151
+ */
152
+ legacyCursor?: string;
153
+ }
154
+
155
+ /** One stream a user currently belongs to, from `GET /sync/streams`. */
156
+ export interface SyncStreamInfo {
157
+ /** Stream key (e.g. "todos|owner:123"). */
158
+ stream: string;
159
+ /** Collection tag the stream belongs to. */
160
+ collection: string;
161
+ }
162
+
163
+ /** Durable outbox mutation lifecycle. */
164
+ export type OutboxStatus = "queued" | "inFlight" | "acked" | "conflicted" | "failed";
165
+
166
+ /** A locally queued mutation awaiting server acknowledgement. */
167
+ export interface OutboxMutation {
168
+ mutationId: string;
169
+ collection: string;
170
+ operation: SyncMutationOperation;
171
+ entityId: string;
172
+ /** JSON-serialized mutation args. */
173
+ args: string;
174
+ baseVersion?: number;
175
+ status: OutboxStatus;
176
+ /** Diagnostic total attempt count across every send (transport + error-nack). */
177
+ attemptCount: number;
178
+ /** Retry-budget counter incremented only on server error-nacks (see MAX_ERROR_NACK_ATTEMPTS). */
179
+ errorNackCount: number;
180
+ /** The user this mutation belongs to; replay skips mutations from other users. */
181
+ userId: string;
182
+ createdAt: string;
183
+ }
184
+
185
+ /** An unresolved conflict between a local mutation and the canonical server state. */
186
+ export interface SyncConflict {
187
+ mutationId: string;
188
+ collection: string;
189
+ entityId: string;
190
+ /** JSON-serialized local (optimistic) entity data. */
191
+ localData: string;
192
+ /** JSON-serialized canonical server entity data. */
193
+ serverData: string;
194
+ serverSeq: number;
195
+ /**
196
+ * True when the server side of this conflict is a tombstone, so `useServer`
197
+ * resolution must delete the local row rather than write `serverData` over it.
198
+ * Absent for conflicts recorded before the flag existed (and by servers that
199
+ * do not send it) — `serverData: null` at a non-zero `serverSeq` is treated
200
+ * the same way, since the server reported a real seq with no document at it.
201
+ */
202
+ serverDeleted?: boolean;
203
+ dismissed: boolean;
204
+ }
205
+
206
+ export type ConflictResolutionStrategy = "useServer" | "keepMine";
207
+
208
+ /**
209
+ * Health counts for a single collection. Mirrors the collection-agnostic totals
210
+ * on {@link SyncStatus}, letting apps attribute an issue to the data it affects
211
+ * (e.g. one notification per collection rather than one lumped global count).
212
+ */
213
+ export interface SyncCollectionStatus {
214
+ queuedCount: number;
215
+ conflictCount: number;
216
+ failedCount: number;
217
+ }
218
+
219
+ /** Aggregate sync state for status UI. */
220
+ export interface SyncStatus {
221
+ isOnline: boolean;
222
+ isSyncing: boolean;
223
+ queuedCount: number;
224
+ conflictCount: number;
225
+ /** Count of mutations in the terminal `failed` state. */
226
+ failedCount: number;
227
+ /**
228
+ * Set when replay is paused because the server rejected our auth (401 /
229
+ * AuthRequiredError / unauthorized nack / socket auth rejection). Clears
230
+ * automatically when the same user re-authenticates and replay resumes.
231
+ */
232
+ paused?: "auth";
233
+ /**
234
+ * Number of distinct entities currently blocked from draining (B4): an
235
+ * unresolved conflict, or a terminal validation failure whose successors
236
+ * are skipped-and-surfaced pending `client.retryFailed({entityId})`.
237
+ */
238
+ blockedEntities: number;
239
+ /** True while a replay/drain is actively in flight for the current user. */
240
+ draining: boolean;
241
+ /** Mutations attempted so far in the current (or most recent) drain call. */
242
+ sentThisDrain: number;
243
+ /** Queue length observed when the current (or most recent) drain call began. */
244
+ totalThisDrain: number;
245
+ /** Per-stream cursors (stream key → highest applied seq). */
246
+ streams: Record<string, number>;
247
+ /**
248
+ * Per-collection breakdown of the counts above, keyed by collection name.
249
+ * Only collections with at least one queued, conflicted, or failed mutation
250
+ * are present, so an empty object means everything is healthy.
251
+ */
252
+ collections: Record<string, SyncCollectionStatus>;
253
+ /**
254
+ * E3(c)/(a): local persistence health. `"durable"` (default) means the
255
+ * platform persister is backed by real storage (IndexedDB/SQLite);
256
+ * `"memory"` means the web factory fell back to in-memory persistence
257
+ * (no `globalThis.indexedDB` in this environment — data will not survive a
258
+ * reload); `"error"` means the last load attempt hit a storage READ error
259
+ * (distinct from "no data") and the client deliberately skipped autosave to
260
+ * avoid clobbering a still-possibly-intact persisted blob.
261
+ */
262
+ persistence: "durable" | "memory" | "error";
263
+ }
264
+
265
+ /**
266
+ * Narrow authentication surface consumed by syncdb. Satisfied by the Better Auth
267
+ * adapter shipped in this package; syncdb never manages tokens itself.
268
+ */
269
+ export interface AuthProvider {
270
+ /** Current bearer/session token, or null when signed out. Called per request. */
271
+ getToken: () => Promise<string | null>;
272
+ /** Current user id, or null when signed out. */
273
+ getUserId: () => Promise<string | null>;
274
+ /** Subscribe to auth changes (login, logout, user switch). Returns unsubscribe. */
275
+ onAuthChange: (callback: () => void) => () => void;
276
+ /**
277
+ * Optional silent token refresh. When present, the client calls it exactly
278
+ * once per auth-pause episode before surfacing the pause to the app;
279
+ * resolving `true` means the refresh likely succeeded and replay should be
280
+ * retried immediately. Adapters without a meaningful refresh path (or that
281
+ * refresh transparently inside `getToken`) may omit this.
282
+ */
283
+ refresh?: () => Promise<boolean>;
284
+ }