@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,218 @@
1
+ import type {MergeableContent, MergeableStore} from "tinybase";
2
+ import {createCustomPersister, type Persister, Persists} from "tinybase/persisters";
3
+
4
+ import type {PayloadCodec} from "../crypto/types";
5
+ import {idbGet, idbSet} from "../storage/idb";
6
+
7
+ /** Object-store record key holding the single encrypted blob. */
8
+ const RECORD_KEY = "content";
9
+
10
+ /** Default trailing debounce applied to saves (autosave can fire per transaction). */
11
+ const DEFAULT_SAVE_DEBOUNCE_MS = 500;
12
+
13
+ interface PendingSave {
14
+ promise: Promise<void>;
15
+ resolve: () => void;
16
+ reject: (error: unknown) => void;
17
+ }
18
+
19
+ /**
20
+ * Web persister storing the whole MergeableStore as ONE encrypted binary blob
21
+ * in IndexedDB (database per `databaseName`, single object store, single
22
+ * record). The plaintext JSON only ever exists in memory: serialize → encode
23
+ * (AES-GCM) → put blob. Corrupt or undecryptable data is treated as a fresh
24
+ * store — `onDecryptFailure` fires so the caller can wipe and re-bootstrap.
25
+ *
26
+ * A READ error from IndexedDB itself (as opposed to "no record yet") is a
27
+ * different failure mode (E3a): the blob may well still be intact, so it must
28
+ * NOT be treated as "fresh store" (which would let a subsequent autosave
29
+ * clobber it with empty content). `onLoadFailure` fires in that case instead
30
+ * of `onDecryptFailure`, and the underlying read error is re-thrown so
31
+ * TinyBase's own `getPersisted` error handling leaves the in-memory store
32
+ * exactly as it was (never calls `setContentOrChanges`) — callers key off
33
+ * `onLoadFailure` to additionally skip `startAutoSave()` for this session.
34
+ *
35
+ * Saves are debounced with a trailing edge (default 500ms) since TinyBase's
36
+ * autosave fires on every transaction: each write waits out the debounce
37
+ * window, and follow-up saves whose serialized content matches the last
38
+ * written snapshot are skipped, coalescing a burst of transactions into a
39
+ * single encode + IndexedDB put.
40
+ */
41
+ export const createEncryptedIndexedDbPersister = ({
42
+ store,
43
+ databaseName,
44
+ codec,
45
+ onDecryptFailure,
46
+ onLoadFailure,
47
+ onSaveFailure,
48
+ saveDebounceMs = DEFAULT_SAVE_DEBOUNCE_MS,
49
+ idbGetImpl = idbGet,
50
+ idbSetImpl = idbSet,
51
+ }: {
52
+ store: MergeableStore;
53
+ databaseName: string;
54
+ codec: PayloadCodec;
55
+ onDecryptFailure?: () => void;
56
+ onLoadFailure?: () => void;
57
+ /**
58
+ * E3(a): invoked whenever a write to IndexedDB ultimately fails (e.g. a
59
+ * quota-exceeded `DOMException`) — TinyBase's own autosave scheduler
60
+ * otherwise swallows `setPersisted` errors silently via its internal
61
+ * `onIgnoredError`, so without this hook a failing save would be invisible.
62
+ */
63
+ onSaveFailure?: (error: unknown) => void;
64
+ saveDebounceMs?: number;
65
+ /** Test-only override for the IndexedDB read (default: the real `idbGet`). */
66
+ idbGetImpl?: typeof idbGet;
67
+ /** Test-only override for the IndexedDB write (default: the real `idbSet`). */
68
+ idbSetImpl?: typeof idbSet;
69
+ }): Persister<Persists.MergeableStoreOnly> => {
70
+ let lastWrittenJson: string | undefined;
71
+ let pendingSave: PendingSave | undefined;
72
+ // E3(e): the debounce timer scheduling `flushPendingSave` — tracked so
73
+ // `destroy()` can cancel it. Without this, a pending debounced save would
74
+ // still fire (and write) after destroy(), which is exactly the kind of
75
+ // "wrote something after we thought we were done" bug destroy() must
76
+ // prevent (e.g. a wipe immediately followed by destroy()).
77
+ let pendingSaveTimer: ReturnType<typeof setTimeout> | undefined;
78
+ let destroyed = false;
79
+ // Serializes writes so a slow encode/put can never land after (and clobber)
80
+ // a newer snapshot's write.
81
+ let writeChain: Promise<void> = Promise.resolve();
82
+
83
+ const writeJson = (json: string): Promise<void> => {
84
+ const write = writeChain.then(async () => {
85
+ // E3(e): destroy() may have run while this write was already chained
86
+ // behind an earlier one — never let it land after destroy() completes.
87
+ if (destroyed) {
88
+ return;
89
+ }
90
+ const payload = await codec.encode(json);
91
+ await idbSetImpl({databaseName, key: RECORD_KEY, value: payload});
92
+ lastWrittenJson = json;
93
+ });
94
+ // Keep the chain alive after a failed write; the failure still propagates
95
+ // to the caller through `write`.
96
+ writeChain = write.catch(() => {});
97
+ return write;
98
+ };
99
+
100
+ const flushPendingSave = async (): Promise<void> => {
101
+ const pending = pendingSave;
102
+ pendingSave = undefined;
103
+ if (!pending) {
104
+ return;
105
+ }
106
+ try {
107
+ // Trailing edge: snapshot the store at flush time so a burst of
108
+ // transactions during the debounce window lands as one fresh write.
109
+ await writeJson(JSON.stringify(store.getMergeableContent()));
110
+ pending.resolve();
111
+ } catch (error) {
112
+ pending.reject(error);
113
+ }
114
+ };
115
+
116
+ const getPersisted = async (): Promise<MergeableContent | undefined> => {
117
+ let payload: unknown;
118
+ try {
119
+ payload = await idbGetImpl<unknown>({databaseName, key: RECORD_KEY});
120
+ } catch (error) {
121
+ // E3(a): the READ itself failed (IndexedDB unavailable/blocked/thrown) —
122
+ // this is NOT "no data" (undefined) and must not be treated as a fresh
123
+ // store: onDecryptFailure (whose default wipes and re-bootstraps) would
124
+ // be actively harmful here since the persisted blob may still be
125
+ // perfectly intact. Signal the distinct failure and re-throw so
126
+ // TinyBase's own error handling leaves the in-memory store untouched
127
+ // rather than defaulting it to empty.
128
+ onLoadFailure?.();
129
+ throw error;
130
+ }
131
+ if (payload === undefined) {
132
+ return undefined;
133
+ }
134
+ try {
135
+ if (!(payload instanceof Uint8Array)) {
136
+ throw new Error("Persisted record is not a binary payload");
137
+ }
138
+ return JSON.parse(await codec.decode(payload)) as MergeableContent;
139
+ } catch (_error) {
140
+ onDecryptFailure?.();
141
+ return undefined;
142
+ }
143
+ };
144
+
145
+ const setPersisted = async (getContent: () => MergeableContent): Promise<void> => {
146
+ const json = JSON.stringify(getContent());
147
+ if (saveDebounceMs <= 0) {
148
+ try {
149
+ await writeJson(json);
150
+ } catch (error) {
151
+ onSaveFailure?.(error);
152
+ throw error;
153
+ }
154
+ return;
155
+ }
156
+ // TinyBase serializes setPersisted calls, so per-transaction autosaves
157
+ // arrive one at a time; skipping saves whose content already matches the
158
+ // last written snapshot is what coalesces a rapid burst into one write.
159
+ if (json === lastWrittenJson && !pendingSave) {
160
+ return;
161
+ }
162
+ if (!pendingSave) {
163
+ let resolvePending!: () => void;
164
+ let rejectPending!: (error: unknown) => void;
165
+ const promise = new Promise<void>((res, rej) => {
166
+ resolvePending = res;
167
+ rejectPending = rej;
168
+ });
169
+ pendingSave = {promise, reject: rejectPending, resolve: resolvePending};
170
+ pendingSaveTimer = setTimeout(() => {
171
+ pendingSaveTimer = undefined;
172
+ void flushPendingSave();
173
+ }, saveDebounceMs);
174
+ }
175
+ try {
176
+ await pendingSave.promise;
177
+ } catch (error) {
178
+ onSaveFailure?.(error);
179
+ throw error;
180
+ }
181
+ };
182
+
183
+ const persister = createCustomPersister<number, Persists.MergeableStoreOnly>(
184
+ store,
185
+ getPersisted,
186
+ setPersisted,
187
+ // Nothing mutates the blob outside this persister, so no change listener;
188
+ // a token handle keeps the add/del listener lifecycle symmetric.
189
+ (): number => 1,
190
+ (_listenerHandle: number): void => {},
191
+ undefined,
192
+ Persists.MergeableStoreOnly
193
+ );
194
+
195
+ // E3(e): wrap destroy() to cancel the debounce timer and drop (without
196
+ // writing) any pending save — TinyBase's own destroy()/stopAutoPersisting()
197
+ // has no idea this persister keeps its own setTimeout-based debounce state,
198
+ // so without this override a pending write fires (and lands in IndexedDB)
199
+ // even after the caller believes destroy() fully tore everything down.
200
+ const originalDestroy = persister.destroy.bind(persister);
201
+ return {
202
+ ...persister,
203
+ destroy: (): ReturnType<typeof originalDestroy> => {
204
+ destroyed = true;
205
+ if (pendingSaveTimer !== undefined) {
206
+ clearTimeout(pendingSaveTimer);
207
+ pendingSaveTimer = undefined;
208
+ }
209
+ // A pending save's awaiters (if any) must still settle — resolve
210
+ // rather than reject, since "destroyed before its debounce elapsed" is
211
+ // an expected lifecycle event, not a failure the caller needs to
212
+ // handle specially.
213
+ pendingSave?.resolve();
214
+ pendingSave = undefined;
215
+ return originalDestroy();
216
+ },
217
+ };
218
+ };
@@ -0,0 +1,136 @@
1
+ import {describe, expect, it} from "bun:test";
2
+
3
+ import {createOutbox} from "../mutations/outbox";
4
+ import {createSyncStore, type SyncStore} from "../storage/store";
5
+ import {OUTBOX_TABLE} from "../storage/types";
6
+ import {
7
+ clearMemoryPersisterData,
8
+ createMemoryPersister,
9
+ memoryPersisterFactory,
10
+ } from "./memoryPersister";
11
+
12
+ let dbCounter = 0;
13
+ const uniqueDbName = (): string => `memory-test-${dbCounter++}`;
14
+
15
+ const makeStore = (): SyncStore => createSyncStore({collections: ["todos"]});
16
+
17
+ describe("createMemoryPersister", () => {
18
+ it("round-trips entities and outbox rows across separate store instances", async () => {
19
+ const databaseName = uniqueDbName();
20
+ const source = makeStore();
21
+ source.upsertEntity({collection: "todos", data: {title: "Buy milk"}, id: "t1", seq: 3});
22
+ source.setLastUserId({userId: "u1"});
23
+ createOutbox({store: source}).enqueue({
24
+ args: {title: "Buy milk"},
25
+ collection: "todos",
26
+ entityId: "t1",
27
+ mutationId: "m1",
28
+ operation: "create",
29
+ userId: "u1",
30
+ });
31
+ await createMemoryPersister({databaseName, store: source.raw}).save();
32
+
33
+ const target = makeStore();
34
+ await createMemoryPersister({databaseName, store: target.raw}).load();
35
+ expect(target.getEntity({collection: "todos", id: "t1"})?.data).toEqual({title: "Buy milk"});
36
+ expect(target.getEntity({collection: "todos", id: "t1"})?.seq).toBe(3);
37
+ expect(target.getLastUserId()).toBe("u1");
38
+ const outboxRow = target.raw.getRow(OUTBOX_TABLE, "m1");
39
+ expect(outboxRow.collection).toBe("todos");
40
+ expect(outboxRow.status).toBe("queued");
41
+ });
42
+
43
+ it("loads nothing when the databaseName has never been saved", async () => {
44
+ const store = makeStore();
45
+ await createMemoryPersister({databaseName: uniqueDbName(), store: store.raw}).load();
46
+ expect(store.listEntities({collection: "todos"})).toEqual([]);
47
+ });
48
+
49
+ it("isolates content between databaseNames", async () => {
50
+ const dbA = uniqueDbName();
51
+ const dbB = uniqueDbName();
52
+ const storeA = makeStore();
53
+ storeA.upsertEntity({collection: "todos", data: {title: "A"}, id: "a"});
54
+ await createMemoryPersister({databaseName: dbA, store: storeA.raw}).save();
55
+ const storeB = makeStore();
56
+ storeB.upsertEntity({collection: "todos", data: {title: "B"}, id: "b"});
57
+ await createMemoryPersister({databaseName: dbB, store: storeB.raw}).save();
58
+
59
+ const reloaded = makeStore();
60
+ await createMemoryPersister({databaseName: dbA, store: reloaded.raw}).load();
61
+ expect(reloaded.getEntity({collection: "todos", id: "a"})).toBeDefined();
62
+ expect(reloaded.getEntity({collection: "todos", id: "b"})).toBeUndefined();
63
+ });
64
+
65
+ it("persists store changes automatically under startAutoSave", async () => {
66
+ const databaseName = uniqueDbName();
67
+ const source = makeStore();
68
+ const persister = createMemoryPersister({databaseName, store: source.raw});
69
+ await persister.startAutoSave();
70
+ source.upsertEntity({collection: "todos", data: {title: "auto"}, id: "t1"});
71
+ await persister.destroy();
72
+
73
+ const target = makeStore();
74
+ await createMemoryPersister({databaseName, store: target.raw}).load();
75
+ expect(target.getEntity({collection: "todos", id: "t1"})?.data).toEqual({title: "auto"});
76
+ });
77
+
78
+ it("supports the autoLoad lifecycle (no external change source to observe)", async () => {
79
+ const databaseName = uniqueDbName();
80
+ const source = makeStore();
81
+ source.upsertEntity({collection: "todos", data: {title: "autoload"}, id: "t1"});
82
+ await createMemoryPersister({databaseName, store: source.raw}).save();
83
+
84
+ const target = makeStore();
85
+ const persister = createMemoryPersister({databaseName, store: target.raw});
86
+ await persister.startAutoLoad();
87
+ expect(target.getEntity({collection: "todos", id: "t1"})?.data).toEqual({title: "autoload"});
88
+ await persister.stopAutoLoad();
89
+ await persister.destroy();
90
+ });
91
+
92
+ it("hands loads a deep copy, not a live reference into another store", async () => {
93
+ const databaseName = uniqueDbName();
94
+ const source = makeStore();
95
+ source.upsertEntity({collection: "todos", data: {title: "original"}, id: "t1"});
96
+ await createMemoryPersister({databaseName, store: source.raw}).save();
97
+
98
+ const target = makeStore();
99
+ await createMemoryPersister({databaseName, store: target.raw}).load();
100
+ target.upsertEntity({collection: "todos", data: {title: "changed"}, id: "t1"});
101
+
102
+ const reloaded = makeStore();
103
+ await createMemoryPersister({databaseName, store: reloaded.raw}).load();
104
+ expect(reloaded.getEntity({collection: "todos", id: "t1"})?.data).toEqual({title: "original"});
105
+ });
106
+ });
107
+
108
+ describe("memoryPersisterFactory", () => {
109
+ it("builds persisters bound to the given store and databaseName", async () => {
110
+ const databaseName = uniqueDbName();
111
+ const source = makeStore();
112
+ source.upsertEntity({collection: "todos", data: {title: "via factory"}, id: "t1"});
113
+ await memoryPersisterFactory({databaseName, store: source.raw}).save();
114
+
115
+ const target = makeStore();
116
+ await memoryPersisterFactory({databaseName, store: target.raw}).load();
117
+ expect(target.getEntity({collection: "todos", id: "t1"})?.data).toEqual({
118
+ title: "via factory",
119
+ });
120
+ });
121
+ });
122
+
123
+ describe("clearMemoryPersisterData", () => {
124
+ it("drops persisted content for one databaseName", async () => {
125
+ const databaseName = uniqueDbName();
126
+ const source = makeStore();
127
+ source.upsertEntity({collection: "todos", data: {title: "gone"}, id: "t1"});
128
+ await createMemoryPersister({databaseName, store: source.raw}).save();
129
+
130
+ clearMemoryPersisterData({databaseName});
131
+
132
+ const target = makeStore();
133
+ await createMemoryPersister({databaseName, store: target.raw}).load();
134
+ expect(target.listEntities({collection: "todos"})).toEqual([]);
135
+ });
136
+ });
@@ -0,0 +1,52 @@
1
+ import type {MergeableContent, MergeableStore} from "tinybase";
2
+ import {createCustomPersister, type Persister, Persists} from "tinybase/persisters";
3
+
4
+ import type {PersisterFactory} from "./types";
5
+
6
+ /**
7
+ * Module-level backing keyed by databaseName. Two persisters created with the
8
+ * same databaseName (even against different stores) share persisted state,
9
+ * which is how tests and SSR emulate cross-session persistence. Content is
10
+ * stored as a JSON string so loads get a fresh deep copy, never a live
11
+ * reference into another store.
12
+ */
13
+ const memoryBacking = new Map<string, string>();
14
+
15
+ /**
16
+ * In-memory persister for tests and SSR/no-storage fallbacks. Persists the
17
+ * full mergeable (CRDT) content so reloading into a fresh store retains
18
+ * hybrid-logical-clock metadata, mirroring real persister behavior.
19
+ */
20
+ export const createMemoryPersister = ({
21
+ store,
22
+ databaseName,
23
+ }: {
24
+ store: MergeableStore;
25
+ databaseName: string;
26
+ }): Persister<Persists.MergeableStoreOnly> =>
27
+ createCustomPersister<number, Persists.MergeableStoreOnly>(
28
+ store,
29
+ async (): Promise<MergeableContent | undefined> => {
30
+ const json = memoryBacking.get(databaseName);
31
+ return json === undefined ? undefined : (JSON.parse(json) as MergeableContent);
32
+ },
33
+ async (getContent): Promise<void> => {
34
+ memoryBacking.set(databaseName, JSON.stringify(getContent()));
35
+ },
36
+ // The backing map never changes underneath the persister, so there is no
37
+ // external change source to listen to; a token handle keeps the
38
+ // add/del listener lifecycle symmetric.
39
+ (): number => 1,
40
+ (_listenerHandle: number): void => {},
41
+ undefined,
42
+ Persists.MergeableStoreOnly
43
+ );
44
+
45
+ /** PersisterFactory adapter for {@link createMemoryPersister}. */
46
+ export const memoryPersisterFactory: PersisterFactory = ({store, databaseName}) =>
47
+ createMemoryPersister({databaseName, store});
48
+
49
+ /** Drop the in-memory persisted content for one databaseName (wipe/tests). */
50
+ export const clearMemoryPersisterData = ({databaseName}: {databaseName: string}): void => {
51
+ memoryBacking.delete(databaseName);
52
+ };
@@ -0,0 +1,71 @@
1
+ import type {MergeableStore} from "tinybase";
2
+ import type {AnyPersister} from "tinybase/persisters";
3
+
4
+ import type {KeyProvider} from "../crypto/types";
5
+ import type {idbGet, idbSet} from "../storage/idb";
6
+
7
+ /**
8
+ * Binds a TinyBase persister to a specific store + logical database name. The
9
+ * returned persister must support MergeableStore content (TinyBase
10
+ * `Persists.MergeableStoreOnly` or `Persists.StoreOrMergeableStore`) so CRDT
11
+ * metadata survives the round trip.
12
+ *
13
+ * `hooks` carries the client's E3 failure-surfacing callbacks
14
+ * (`onDecryptFailure`/`onLoadFailure`/`onSaveFailure`) — always passed
15
+ * through regardless of whether the default or a custom factory is in use, so
16
+ * a host app supplying its own `persisterFactory` (e.g. a different storage
17
+ * backend) can still opt into the same SyncStatus surfacing by wiring these
18
+ * into its own persister. Optional to consume; a factory that ignores
19
+ * `hooks` simply forgoes that surfacing (matches pre-E3 behavior).
20
+ */
21
+ export type PersisterFactory = ({
22
+ store,
23
+ databaseName,
24
+ hooks,
25
+ }: {
26
+ store: MergeableStore;
27
+ databaseName: string;
28
+ hooks?: {
29
+ onDecryptFailure?: () => void;
30
+ onLoadFailure?: () => void;
31
+ onSaveFailure?: (error: unknown) => void;
32
+ };
33
+ }) => AnyPersister;
34
+
35
+ /**
36
+ * Options accepted by `createDefaultPersisterFactory` on every platform. Each
37
+ * platform variant consumes the subset it needs and ignores the rest, keeping
38
+ * the call site platform-agnostic.
39
+ */
40
+ export interface DefaultPersisterFactoryConfig {
41
+ /**
42
+ * Encryption key provider (web only; encryption is default-on there).
43
+ * Defaults to a device-local random key when omitted.
44
+ */
45
+ keyProvider?: KeyProvider;
46
+ /** User id the encryption key is derived/scoped for (web only). */
47
+ userId?: string;
48
+ /** Invoked when persisted data cannot be decrypted (web only). */
49
+ onDecryptFailure?: () => void;
50
+ /**
51
+ * E3(a): invoked when the underlying storage READ itself fails (distinct
52
+ * from "no data" and from a decrypt/parse failure) — a signal that the
53
+ * persisted blob might still be intact and must not be autosaved over
54
+ * (web only).
55
+ */
56
+ onLoadFailure?: () => void;
57
+ /**
58
+ * E3(a): invoked when a WRITE to storage ultimately fails (e.g. a
59
+ * quota-exceeded error) — TinyBase's autosave scheduler otherwise swallows
60
+ * this silently (web only).
61
+ */
62
+ onSaveFailure?: (error: unknown) => void;
63
+ /** Trailing save debounce in ms; 0 disables debouncing (web only). */
64
+ saveDebounceMs?: number;
65
+ /** SQLite table name holding the JSON-serialized store (native only). */
66
+ storeTableName?: string;
67
+ /** Test-only override for the IndexedDB read (web only; default: the real `idbGet`). */
68
+ idbGetImpl?: typeof idbGet;
69
+ /** Test-only override for the IndexedDB write (web only; default: the real `idbSet`). */
70
+ idbSetImpl?: typeof idbSet;
71
+ }