@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,212 @@
1
+ import type { SyncDebugLog } from "../debug/debugLog";
2
+ import type { Outbox } from "../mutations/outbox";
3
+ import type { SyncStore } from "../storage/store";
4
+ import type { OutboxMutation, SyncMutateBatchRequest, SyncMutateRequest } from "../types";
5
+ import { type SendMutationBatchResult, type SendMutationResult } from "./transport";
6
+ /** Error-nack retries beyond this attempt count become terminal failures. */
7
+ export declare const MAX_ERROR_NACK_ATTEMPTS = 5;
8
+ /** Base delay for the error-nack exponential backoff (doubles per attempt). */
9
+ export declare const ERROR_NACK_BASE_BACKOFF_MS = 1000;
10
+ /** Base delay for transport-failure backoff (unlimited retries, same cap/jitter shape). */
11
+ export declare const TRANSPORT_FAILURE_BASE_BACKOFF_MS = 1000;
12
+ /** Cap applied to every jittered backoff (error-nack and transport-failure alike). */
13
+ export declare const MAX_BACKOFF_MS = 30000;
14
+ /**
15
+ * FIX 5: consecutive `unsupported` batch results required before the
16
+ * per-connection `batchUnsupported` latch engages — a single slow-but-
17
+ * supported batch (grace elapsed with no receipt is impossible once a
18
+ * receipt lands, but a genuinely borderline network hiccup could still
19
+ * produce one stray `unsupported`) must never permanently downgrade the
20
+ * session to single-sends.
21
+ */
22
+ export declare const BATCH_UNSUPPORTED_LATCH_THRESHOLD = 2;
23
+ /**
24
+ * FIX 5: while latched `batchUnsupported`, re-probe batch support on this
25
+ * interval even without a reconnect — a load balancer could route later
26
+ * sends to an upgraded instance, or the original instance could itself be
27
+ * upgraded, without the connection ever dropping.
28
+ */
29
+ export declare const BATCH_UNSUPPORTED_REPROBE_INTERVAL_MS = 60000;
30
+ export interface ReplayResult {
31
+ /** Set when replay stopped early because the server rejected our auth. */
32
+ paused?: "auth";
33
+ }
34
+ export interface ReplayCoordinator {
35
+ /**
36
+ * Drain the user's queued mutations in one global FIFO pass ordered by
37
+ * `enqueueOrder` (INV-1) — never per-collection parallel. Resolves once the
38
+ * queue is fully empty or parked (auth pause, or every remaining mutation is
39
+ * backing off). A second call for the same user while one is running
40
+ * returns the in-flight promise.
41
+ */
42
+ replay: (args: {
43
+ userId: string;
44
+ }) => Promise<ReplayResult>;
45
+ /**
46
+ * Clear the single armed wake-up timer (if any) for a user. Called from
47
+ * `client.stop()` so no post-stop send can fire.
48
+ */
49
+ dispose: (args?: {
50
+ userId?: string;
51
+ }) => void;
52
+ /**
53
+ * FIX 3: clear ALL in-memory coordinator state — every armed wake-up timer
54
+ * (all users), retry/backoff bookkeeping (`retryAt`, `transportFailures`),
55
+ * `authPauseNotified`, the batch-capability latch (`batchUnsupported`), drain
56
+ * progress counters, and `validationBlockedEntities` — so a lifecycle
57
+ * boundary (client `dispose()`, or a different-user login's wipe path)
58
+ * never leaks state across users or across a stop/start cycle. Unlike
59
+ * `dispose()` (which only clears one user's timer), this is a full reset:
60
+ * call it from `dispose()` itself AND from the different-user wipe path.
61
+ */
62
+ reset: () => void;
63
+ /**
64
+ * Re-probe batch support on the next drain (B3): called on transport
65
+ * reconnect, since a previous `batchUnsupported` determination may have been
66
+ * against an old server that has since been upgraded (or the reconnect landed
67
+ * on a different, batch-capable instance behind a load balancer).
68
+ */
69
+ notifyReconnect: () => void;
70
+ /**
71
+ * Re-enable an entity's blocked queued successors (B4) after a terminal
72
+ * validation failure: subsequent drains stop skipping mutations for this
73
+ * entity. Does not touch unresolved conflicts — those clear via
74
+ * `resolveConflict`.
75
+ */
76
+ retryFailed: (args: {
77
+ entityId: string;
78
+ }) => void;
79
+ /** Entity ids currently blocked by an unresolved conflict or a skipped validation failure (B4). */
80
+ getBlockedEntities: (args: {
81
+ userId: string;
82
+ }) => string[];
83
+ /**
84
+ * Current drain progress snapshot for a user (B5): `draining` is true only
85
+ * while a `replay()` call for this user is in flight. `sentThisDrain` /
86
+ * `totalThisDrain` reflect the most recent (or in-progress) drain.
87
+ */
88
+ getDrainProgress: (args: {
89
+ userId: string;
90
+ }) => {
91
+ draining: boolean;
92
+ sentThisDrain: number;
93
+ totalThisDrain: number;
94
+ };
95
+ }
96
+ export interface CreateReplayCoordinatorArgs {
97
+ store: SyncStore;
98
+ outbox: Outbox;
99
+ sendMutation: (request: SyncMutateRequest) => Promise<SendMutationResult>;
100
+ /**
101
+ * Batch send function (B3). When present, the coordinator builds contiguous
102
+ * chunks of the global FIFO queue (≤ `batchSize`) and sends them here instead
103
+ * of one `sendMutation` per mutation, falling back to single sends when the
104
+ * batch transport reports `unsupported` or is absent.
105
+ */
106
+ sendMutationBatch?: (request: SyncMutateBatchRequest) => Promise<SendMutationBatchResult>;
107
+ /** Max mutations per batch chunk (default {@link DEFAULT_BATCH_SIZE}). */
108
+ batchSize?: number;
109
+ /**
110
+ * When true (B4), a conflict halts the ENTIRE drain instead of just blocking
111
+ * its entity. Default false (per-entity blocking).
112
+ */
113
+ haltQueueOnConflict?: boolean;
114
+ /** Millisecond clock, injectable for deterministic backoff tests. */
115
+ now?: () => number;
116
+ /** Random source in [0, 1), injectable for deterministic jitter tests. */
117
+ random?: () => number;
118
+ /** Optional debug log; when present, each mutation outcome is recorded. */
119
+ debug?: SyncDebugLog;
120
+ /**
121
+ * Called whenever a drain parks on an armed wake-up timer, so the host can
122
+ * schedule the callback (defaults to the global `setTimeout`/`clearTimeout`).
123
+ */
124
+ setTimeoutFn?: (handler: () => void, ms: number) => unknown;
125
+ clearTimeoutFn?: (handle: unknown) => void;
126
+ /**
127
+ * Called after a drain pass that made forward progress (at least one ack)
128
+ * so the caller can prune acked rows (A5). Optional — tests that don't care
129
+ * about pruning may omit it.
130
+ */
131
+ onDrainPass?: (args: {
132
+ userId: string;
133
+ }) => void;
134
+ /**
135
+ * Called the first time a drain pass for a user enters the auth-paused
136
+ * state (A4). Not called again until the pause clears and re-triggers.
137
+ */
138
+ onAuthPause?: (args: {
139
+ userId: string;
140
+ }) => void;
141
+ /**
142
+ * B5: called after each mutation/chunk send attempt with drain progress —
143
+ * `sentThisDrain` (attempts made so far in this `replay()` call) and
144
+ * `totalThisDrain` (queue length observed when this `replay()` call began,
145
+ * a lower bound since more may enqueue mid-drain). Lets the host surface a
146
+ * progress indicator (e.g. "12 / 40 synced").
147
+ */
148
+ onProgress?: (args: {
149
+ userId: string;
150
+ sentThisDrain: number;
151
+ totalThisDrain: number;
152
+ }) => void;
153
+ /**
154
+ * Consulted before every drain attempt — including internally-scheduled
155
+ * ones (the armed wake-up timer and the mid-drain-enqueue recheck) that
156
+ * bypass the caller's own call site. Lets the host gate sending on state the
157
+ * coordinator does not itself track (simulated offline, auth pause at the
158
+ * client level). Defaults to always-allow.
159
+ */
160
+ shouldDrain?: () => boolean;
161
+ /**
162
+ * Called when a mutation is terminal and the entity's `pendingMutationId` was
163
+ * released without a server ack seq — skipped server deltas may need repair.
164
+ */
165
+ onEntityReleasedWithoutServerAck?: (mutation: OutboxMutation) => void;
166
+ }
167
+ /**
168
+ * Bridges the durable outbox and the send channel, resolving each mutation's
169
+ * server outcome:
170
+ *
171
+ * - **ack** → markAcked, clear the entity's `pendingMutationId` (when it still
172
+ * belongs to this mutation) and stamp the acked seq;
173
+ * - **nack conflict** → markConflicted + record a `_conflicts` row; the
174
+ * entity's optimistic state stays in place until the user resolves. The
175
+ * ENTITY is blocked (B4): later drains skip its other queued mutations
176
+ * until the conflict resolves, unless `haltQueueOnConflict` is set, in
177
+ * which case the whole drain halts instead;
178
+ * - **nack unauthorized** / thrown `AuthRequiredError` → back to queued and
179
+ * pause replay for the user (`{paused: "auth"}`), consuming NO retry budget
180
+ * (INV-2); the next replay call (after re-auth) retries;
181
+ * - **nack validation** → markFailed (terminal) and release the entity's
182
+ * `pendingMutationId` so future deltas are not blocked forever. The ENTITY
183
+ * is blocked (B4) — its queued successors are skipped until `retryFailed`;
184
+ * - **nack error** → back to queued with jittered exponential backoff against
185
+ * the dedicated `errorNackCount` budget, terminal markFailed after
186
+ * {@link MAX_ERROR_NACK_ATTEMPTS} attempts. HALTS THE WHOLE DRAIN (B4);
187
+ * - **send rejection** (timeout / network / disconnect) → back to queued with
188
+ * unlimited jittered exponential backoff (never terminal, never burns the
189
+ * error-nack budget) and the drain parks until the backoff elapses. HALTS
190
+ * THE WHOLE DRAIN (B4);
191
+ * - **nack rate_limited** → treated EXACTLY like a transport failure (FIX 1):
192
+ * back to queued with the same unlimited jittered backoff (respecting the
193
+ * server's `retryAfterMs` as a floor when present), NEVER touching
194
+ * `errorNackCount` or `attemptCount`'s terminality — a rate limit is never
195
+ * allowed to burn the durable-data retry budget. HALTS THE WHOLE DRAIN (B4).
196
+ *
197
+ * The drain is a SINGLE global FIFO over `enqueueOrder` (INV-1) — no more
198
+ * per-collection parallelism. `replay()` keeps re-running drain passes until
199
+ * the queue is empty or parked; when it parks on a backoff, a single
200
+ * `setTimeout` wakes the next drain automatically so callers never need to
201
+ * poll.
202
+ *
203
+ * B3 layers a batched send on top: each pass sends the next contiguous chunk
204
+ * of the FIFO queue (≤ `batchSize`, at most one mutation per entity per
205
+ * chunk) through `sendMutationBatch` when available, walking the results in
206
+ * order with the same per-outcome handlers above, then applying the B4
207
+ * stop-the-line policy to whatever the batch response implies. Chunks with no
208
+ * eligible mutations (everything blocked/backing off) fall through exactly
209
+ * like the single-send path.
210
+ */
211
+ export declare const createReplayCoordinator: ({ store, outbox, sendMutation, sendMutationBatch, batchSize, haltQueueOnConflict, now, random, debug, setTimeoutFn, clearTimeoutFn, onDrainPass, onAuthPause, onProgress, onEntityReleasedWithoutServerAck, shouldDrain, }: CreateReplayCoordinatorArgs) => ReplayCoordinator;
212
+ //# sourceMappingURL=replayCoordinator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"replayCoordinator.d.ts","sourceRoot":"","sources":["../../src/sync/replayCoordinator.ts"],"names":[],"mappings":"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"}