@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,246 @@
1
+ import type { KeyProvider } from "./crypto/types";
2
+ import { type SyncDebugLog, type SyncDebugLogOptions } from "./debug/debugLog";
3
+ import { type Outbox } from "./mutations/outbox";
4
+ import type { DefaultPersisterFactoryConfig, PersisterFactory } from "./persisters/types";
5
+ import { type SyncStore } from "./storage/store";
6
+ import { type HttpChannel } from "./sync/httpChannel";
7
+ import type { SyncTransport } from "./sync/transport";
8
+ import type { AuthProvider, ConflictResolutionStrategy, SyncMutationOperation, SyncStatus } from "./types";
9
+ /** Periodic reconcile interval when not configured (5 minutes). */
10
+ export declare const DEFAULT_RECONCILE_INTERVAL_MS: number;
11
+ /** Minimum interval between seq-jump-triggered reconciles per stream (30s). */
12
+ export declare const DEFAULT_SEQ_JUMP_RECONCILE_MIN_INTERVAL_MS = 30000;
13
+ /** E5: default local tombstone retention window (90 days), matching the server's (C7). */
14
+ export declare const DEFAULT_TOMBSTONE_RETENTION_MS: number;
15
+ /**
16
+ * `start()` auth-resolution retry defaults. A host app only calls `start()` once it
17
+ * already believes the user is authenticated (e.g. right after its own login flow
18
+ * resolved), so a `null` from `authProvider.getUserId()` on the first attempt is far
19
+ * more likely a transient hiccup — the session cookie/token not yet queryable, or a
20
+ * one-off fetch failure racing a just-completed navigation — than a genuine
21
+ * logged-out state. Retrying briefly avoids `start()` giving up permanently on a call
22
+ * site that (by design, see the client.ts start() doc) never retries itself.
23
+ */
24
+ export declare const DEFAULT_START_AUTH_RETRY_ATTEMPTS = 3;
25
+ export declare const DEFAULT_START_AUTH_RETRY_DELAY_MS = 250;
26
+ export interface SyncDbConfig {
27
+ /** App/store name; used as the persisted database name. */
28
+ name: string;
29
+ /** Collections to sync (become local entity tables and subscriptions). */
30
+ collections: string[];
31
+ authProvider: AuthProvider;
32
+ /** Server origin; required unless both transport and httpChannel are injected. */
33
+ baseUrl?: string;
34
+ /** Transport override (tests inject a fake; default is the socket transport). */
35
+ transport?: SyncTransport;
36
+ /** HTTP channel override (default is built from baseUrl when present). */
37
+ httpChannel?: HttpChannel;
38
+ /** Persister factory override (default is the platform default factory). */
39
+ persisterFactory?: PersisterFactory;
40
+ /** Encryption key provider forwarded to the default persister factory (web). */
41
+ keyProvider?: KeyProvider;
42
+ /**
43
+ * Test-only IndexedDB read/write overrides forwarded to the default web
44
+ * persister factory (e.g. to simulate a read error or a quota-exceeded
45
+ * write in tests without a real broken IndexedDB). Ignored on native and
46
+ * ignored entirely when `persisterFactory` is overridden.
47
+ */
48
+ idbGetImpl?: DefaultPersisterFactoryConfig["idbGetImpl"];
49
+ idbSetImpl?: DefaultPersisterFactoryConfig["idbSetImpl"];
50
+ /** Periodic reconcile interval in ms; 0 disables (default 5 minutes). */
51
+ reconcileIntervalMs?: number;
52
+ /** Rate limit for seq-jump-triggered reconciles per stream (default 30s). */
53
+ seqJumpReconcileMinIntervalMs?: number;
54
+ /** Millisecond clock, injectable for deterministic rate-limit tests. */
55
+ now?: () => number;
56
+ /** Random source in [0, 1), injectable for deterministic backoff-jitter tests. */
57
+ random?: () => number;
58
+ /**
59
+ * Enable the in-memory debug event log (patches, mutations, acks/nacks,
60
+ * conflicts, reconcile/replay, connectivity). `true` uses defaults; pass
61
+ * options to size the buffer. Off by default — zero overhead when disabled.
62
+ * Powers the sync debugger UI and the future MCP introspection surface.
63
+ */
64
+ debug?: boolean | SyncDebugLogOptions;
65
+ /**
66
+ * Fired at most once per auth-pause episode when the client enters
67
+ * `paused: "auth"` (INV-2), so the host app can show a re-login prompt.
68
+ * Clears and can fire again after a subsequent pause episode.
69
+ */
70
+ onAuthRequired?: () => void;
71
+ /**
72
+ * When true, `client.signOut()` wipes local data for the current user (in
73
+ * addition to clearing auth state). Local data is otherwise NEVER wiped on
74
+ * logout or 401 (INV-2) — only on a confirmed different-user login, or via
75
+ * this explicit, host-app-initiated opt-in.
76
+ */
77
+ wipeOnSignOut?: boolean;
78
+ /** Max mutations per batched drain send (B3, default 50; server caps at 100). */
79
+ batchSize?: number;
80
+ /**
81
+ * B4: when true, a conflict halts the ENTIRE drain instead of just blocking
82
+ * its entity. Default false (per-entity blocking — see README "Conflict
83
+ * handling modes").
84
+ */
85
+ haltQueueOnConflict?: boolean;
86
+ /**
87
+ * E3(b): invoked when persisted local data cannot be decrypted (web only —
88
+ * corrupt data, or a rotated/lost encryption key). DEFAULT BEHAVIOR when
89
+ * omitted: wipe all local data for the current user, re-stamp the schema
90
+ * version, and run a full snapshot re-bootstrap — always preceded by a
91
+ * `console.warn`. Pass this to override that default (e.g. to prompt the
92
+ * user before wiping); when provided, the client's own wipe/re-bootstrap is
93
+ * skipped and the host app is fully responsible for recovery.
94
+ */
95
+ onDecryptFailure?: () => void;
96
+ /**
97
+ * E5: client-side compaction — local tombstone rows (`deleted: true`) older
98
+ * than this window (from their `deletedAt` stamp) are deleted after each
99
+ * successful reconcile. Default 90 days, matching the server's own
100
+ * tombstone retention (C7); keep the two in sync — compacting locally
101
+ * before the server's retention window elapses risks a client permanently
102
+ * missing a delete it hasn't converged on yet. 0 disables compaction.
103
+ */
104
+ tombstoneRetentionMs?: number;
105
+ /**
106
+ * Number of `authProvider.getUserId()` attempts `start()` makes before giving up
107
+ * with "requires an authenticated user" (default {@link DEFAULT_START_AUTH_RETRY_ATTEMPTS}).
108
+ * A host app calls `start()` only once it believes the user is signed in, so an
109
+ * initial `null` is usually a transient auth-provider hiccup (e.g. a session fetch
110
+ * racing a just-completed login) rather than a real logged-out state — retrying
111
+ * a few times avoids `start()` permanently failing on that race. Set to 1 to
112
+ * disable retrying.
113
+ */
114
+ startAuthRetryAttempts?: number;
115
+ /** Delay between `start()` auth-resolution retries (default {@link DEFAULT_START_AUTH_RETRY_DELAY_MS}). */
116
+ startAuthRetryDelayMs?: number;
117
+ }
118
+ /**
119
+ * Why a {@link SyncDb.forceResync} call could not run (or could not finish).
120
+ *
121
+ * `"superseded"` means a `stop()`/`start()` cycle or a different-user login took over
122
+ * mid-flight, so the resync abandoned its work rather than writing into a store that
123
+ * now belongs to another lifecycle or user — distinct from `"noStreams"` (the server
124
+ * reported no streams for this user, and there was no local set to fall back on),
125
+ * which is a stable outcome that retrying will reproduce.
126
+ */
127
+ export type ForceResyncSkipReason = "noHttpChannel" | "offline" | "authPaused" | "noStreams" | "superseded";
128
+ /** Outcome of a {@link SyncDb.forceResync} call. */
129
+ export interface ForceResyncResult {
130
+ /** False when the resync could not run at all; `reason` explains why. */
131
+ ok: boolean;
132
+ reason?: ForceResyncSkipReason;
133
+ /** Streams purged and re-bootstrapped. */
134
+ streams: number;
135
+ /** Local entity rows deleted before re-bootstrapping. */
136
+ purged: number;
137
+ /** Entities re-fetched by the point-lookup repair pass. */
138
+ repaired: number;
139
+ }
140
+ export interface MutateArgs {
141
+ collection: string;
142
+ operation: SyncMutationOperation;
143
+ /** Target entity id; required for update/delete, generated for create. */
144
+ id?: string;
145
+ /** Fields to write (create/update). */
146
+ data?: Record<string, unknown>;
147
+ }
148
+ export interface SyncDb {
149
+ /** Local-first entity store (the UI's source of truth). */
150
+ readonly store: SyncStore;
151
+ /** Durable mutation outbox. */
152
+ readonly outbox: Outbox;
153
+ /**
154
+ * Resolve the user, run the wipe-on-user-change check, start persistence,
155
+ * connect the transport, subscribe collections, and start the periodic
156
+ * reconcile timer. Resolves even when the transport cannot connect
157
+ * (local-first: the app works offline and syncs when connectivity returns).
158
+ */
159
+ start: () => Promise<void>;
160
+ /** Disconnect, stop persistence, clear timers, and remove listeners. */
161
+ stop: () => Promise<void>;
162
+ /**
163
+ * Simulate a network outage: disconnect the transport and pause replay,
164
+ * reconcile, and the periodic timer. Unlike stop(), the resolved user and
165
+ * persistence stay alive, so mutations keep applying locally and queueing
166
+ * in the durable outbox. `getSyncStatus().isOnline` reports false until
167
+ * goOnline() (or a stop()/start() cycle) restores connectivity.
168
+ */
169
+ goOffline: () => void;
170
+ /**
171
+ * End a simulated outage: reconnect the transport, resubscribe, and restart
172
+ * the periodic timer. The reconnect status event triggers a reconcile and
173
+ * replays the queued outbox.
174
+ */
175
+ goOnline: () => Promise<void>;
176
+ /**
177
+ * Apply a mutation optimistically to the local store, enqueue it in the
178
+ * outbox, and kick off a fire-and-forget replay. Returns the generated
179
+ * mutation id and the entity id (generated for creates).
180
+ */
181
+ mutate: (args: MutateArgs) => {
182
+ mutationId: string;
183
+ id: string;
184
+ };
185
+ /** Snapshot-from-cursor catch-up for every collection (no-op without HTTP). */
186
+ reconcile: () => Promise<void>;
187
+ /**
188
+ * Purge every known stream locally and re-bootstrap from cursor 0. Use when
189
+ * devices have diverged and a full server snapshot is needed without wiping
190
+ * the outbox or conflicts. Reports what it did (or why it could not run) so a
191
+ * caller can surface the outcome instead of a silent no-op.
192
+ */
193
+ forceResync: () => Promise<ForceResyncResult>;
194
+ /** Drain queued mutations for the current user now. */
195
+ replayOutbox: () => Promise<void>;
196
+ /** Resolve a recorded conflict with the given strategy. */
197
+ resolveConflict: (args: {
198
+ mutationId: string;
199
+ strategy: ConflictResolutionStrategy;
200
+ }) => void;
201
+ /**
202
+ * B4: re-enable an entity's queued successors after a terminal validation
203
+ * failure blocked them. Does not touch unresolved conflicts (those clear
204
+ * via `resolveConflict`); kicks off a replay so the re-enabled mutations
205
+ * drain immediately rather than waiting for the next trigger.
206
+ */
207
+ retryFailed: (args: {
208
+ entityId: string;
209
+ }) => void;
210
+ /**
211
+ * Explicit, host-app-initiated sign-out. Tears the client down like `stop()`
212
+ * (transport disconnected, listeners and timers cleared, persister flushed and
213
+ * destroyed) and clears the in-memory current-user pointer; wipes local data
214
+ * ONLY when `wipeOnSignOut` is configured (INV-2 — a bare 401/logout event
215
+ * never triggers this on its own). Safe to call whether or not the client is
216
+ * currently paused, and safe to race against `start()`/`stop()`/an auth
217
+ * change. Call `start()` again to sync as the next signed-in user.
218
+ */
219
+ signOut: () => Promise<void>;
220
+ /** Aggregate sync state for status UI. */
221
+ getSyncStatus: () => SyncStatus;
222
+ /**
223
+ * Subscribe to non-store status inputs (connectivity, syncing activity).
224
+ * `getSyncStatus()` is a snapshot; store-backed inputs (outbox, conflicts,
225
+ * cursors) already emit through TinyBase listeners on `store.raw`, but
226
+ * `isOnline`/`isSyncing` live outside the store — this hook covers them.
227
+ * Returns an unsubscribe function.
228
+ */
229
+ onStatusChange: (callback: () => void) => () => void;
230
+ /**
231
+ * In-memory debug event log when `config.debug` is enabled; otherwise
232
+ * undefined. Its `snapshot()` is a plain serializable object suitable for
233
+ * returning directly over MCP.
234
+ */
235
+ readonly debug?: SyncDebugLog;
236
+ }
237
+ /**
238
+ * Assemble the full local-first client: store + outbox + persister + transport
239
+ * + HTTP channel + replay coordinator + reconcile heuristics.
240
+ *
241
+ * Reconcile triggers: transport (re)connect, rate-limited seq-jump hints from
242
+ * deltas, and a periodic timer. Replay triggers: (re)connect, auth changes,
243
+ * and every `mutate()`.
244
+ */
245
+ export declare const createSyncDb: (config: SyncDbConfig) => SyncDb;
246
+ //# sourceMappingURL=client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}