@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,461 @@
1
+ import {DateTime} from "luxon";
2
+ import {createMergeableStore, type MergeableStore, type Row} from "tinybase";
3
+
4
+ import {buildTablesSchema, SYNC_SCHEMA_VERSION, SYNC_VALUES_SCHEMA} from "./schema";
5
+ import {
6
+ CURSORS_TABLE,
7
+ type EntityRow,
8
+ KNOWN_STREAMS_TABLE,
9
+ NEEDS_REPAIR_TABLE,
10
+ type NeedsRepairRow,
11
+ RESERVED_TABLE_PREFIX,
12
+ type SyncEntity,
13
+ } from "./types";
14
+
15
+ const defaultNow = (): string => DateTime.now().toISO();
16
+
17
+ const encodeData = (data: unknown): string => JSON.stringify(data ?? null);
18
+
19
+ const decodeData = <TData>(raw: string | undefined): TData => {
20
+ if (raw === undefined) {
21
+ return null as TData;
22
+ }
23
+ try {
24
+ return JSON.parse(raw) as TData;
25
+ } catch (error) {
26
+ // A single corrupt/legacy row must never take down a local-first list read.
27
+ console.warn("[syncdb] failed to decode entity payload; returning null", error);
28
+ return null as TData;
29
+ }
30
+ };
31
+
32
+ const rowToEntity = <TData>(id: string, row: Partial<EntityRow>): SyncEntity<TData> => ({
33
+ data: decodeData<TData>(row.data),
34
+ deleted: Boolean(row.deleted),
35
+ deletedAt: row.deletedAt ? row.deletedAt : undefined,
36
+ id,
37
+ pendingMutationId: row.pendingMutationId ? row.pendingMutationId : undefined,
38
+ seq: row.seq ?? 0,
39
+ stream: row.stream ? row.stream : undefined,
40
+ });
41
+
42
+ export interface UpsertEntityArgs {
43
+ collection: string;
44
+ id: string;
45
+ data: unknown;
46
+ /** Server seq for this entity; omitted = preserve existing (0 when new). */
47
+ seq?: number;
48
+ /** Tombstone flag; omitted = preserve existing (false when new). */
49
+ deleted?: boolean;
50
+ /** Protecting outbox mutation; omitted = preserve existing, "" = clear. */
51
+ pendingMutationId?: string;
52
+ /** C2: the stream this entity was written under; omitted = preserve existing. */
53
+ stream?: string;
54
+ }
55
+
56
+ export interface CompactTombstonesResult {
57
+ /** Number of tombstone rows removed (across all configured collections). */
58
+ removed: number;
59
+ }
60
+
61
+ export interface SyncStore {
62
+ /** Underlying TinyBase MergeableStore (CRDT-capable, persistence-ready). */
63
+ readonly raw: MergeableStore;
64
+ /** Collections this store was configured with. */
65
+ readonly collections: readonly string[];
66
+ upsertEntity: (args: UpsertEntityArgs) => SyncEntity;
67
+ getEntity: <TData = unknown>(args: {
68
+ collection: string;
69
+ id: string;
70
+ }) => SyncEntity<TData> | undefined;
71
+ listEntities: <TData = unknown>(args: {
72
+ collection: string;
73
+ includeDeleted?: boolean;
74
+ }) => SyncEntity<TData>[];
75
+ /**
76
+ * Every row across every configured collection that currently carries a
77
+ * `pendingMutationId`, tombstones included. Used by the startup sweep that
78
+ * releases pendings whose outbox row no longer exists (Task 9.11b) — such a
79
+ * row is frozen otherwise, since the delta applier skips it for pending
80
+ * protection and repair refuses to overwrite it.
81
+ */
82
+ listPendingEntities: () => Array<{
83
+ collection: string;
84
+ entityId: string;
85
+ pendingMutationId: string;
86
+ }>;
87
+ softDeleteEntity: (args: {collection: string; id: string}) => void;
88
+ clearCollection: (args: {collection: string}) => void;
89
+ getSchemaVersion: () => number;
90
+ getLastUserId: () => string | undefined;
91
+ setLastUserId: (args: {userId: string}) => void;
92
+ /**
93
+ * E5: delete local tombstone rows (`deleted: true`) whose `deletedAt` is
94
+ * older than `olderThanMs` (from `now`), across every configured
95
+ * collection, in one transaction. Tombstones with no `deletedAt` (applied
96
+ * before this cell existed) are left alone — there is no reliable age to
97
+ * compare, and it is safer to under-compact than to drop a tombstone a
98
+ * client hasn't actually converged on yet.
99
+ */
100
+ compactTombstones: (args: {olderThanMs: number; now?: () => string}) => CompactTombstonesResult;
101
+ /** C2: stream keys the client has bootstrapped (the persisted membership set). */
102
+ getKnownStreams: () => string[];
103
+ /** C2: record a stream as bootstrapped (join). */
104
+ addKnownStream: (args: {stream: string; collection: string}) => void;
105
+ /** C2: forget a bootstrapped stream (leave). */
106
+ removeKnownStream: (args: {stream: string}) => void;
107
+ /**
108
+ * C2 leave-purge: delete every local entity written under `stream` (matched on the
109
+ * entity `stream` column) across all collections, and its cursor + known-stream entry.
110
+ * Returns the number of entities purged.
111
+ */
112
+ purgeStream: (args: {stream: string}) => number;
113
+ /**
114
+ * Delete rows in `collection` that carry no stream provenance (`stream` is "")
115
+ * and have no pending outbox mutation. These are either phantoms left by a
116
+ * locally-failed create the server never accepted, or legacy rows written
117
+ * before stream stamping — a re-bootstrap restores anything the server still
118
+ * has. Rows protected by a pending mutation are always kept.
119
+ */
120
+ purgeUnknownStreamEntities: (args: {collection: string}) => number;
121
+ /** Record that server state for an entity was skipped while pending-protected. */
122
+ markNeedsRepair: (args: {
123
+ collection: string;
124
+ entityId: string;
125
+ missedSeq: number;
126
+ stream: string;
127
+ }) => void;
128
+ clearNeedsRepair: (args: {collection: string; entityId: string}) => void;
129
+ hasNeedsRepair: (args: {collection: string; entityId: string}) => boolean;
130
+ listNeedsRepair: () => Array<{
131
+ collection: string;
132
+ entityId: string;
133
+ missedSeq: number;
134
+ stream: string;
135
+ }>;
136
+ clearNeedsRepairForStream: (args: {stream: string}) => void;
137
+ }
138
+
139
+ /**
140
+ * Create a schema-bound TinyBase MergeableStore wrapped with typed,
141
+ * collection-aware entity accessors. A MergeableStore (rather than a plain
142
+ * Store) is used deliberately so the local data is CRDT-ready from day one.
143
+ * Every accessor validates its collection against the configured list so a
144
+ * typo'd collection fails loudly instead of silently writing to a stray table.
145
+ */
146
+ export const createSyncStore = ({
147
+ collections,
148
+ now = defaultNow,
149
+ }: {
150
+ collections: string[];
151
+ /** ISO clock, injectable for deterministic E5 tombstone-retention tests. */
152
+ now?: () => string;
153
+ }): SyncStore => {
154
+ for (const collection of collections) {
155
+ if (collection.startsWith(RESERVED_TABLE_PREFIX)) {
156
+ throw new Error(
157
+ `Collection names must not start with "${RESERVED_TABLE_PREFIX}" (reserved for internal tables): ${collection}`
158
+ );
159
+ }
160
+ }
161
+ const known = new Set(collections);
162
+ if (known.size !== collections.length) {
163
+ throw new Error(`Duplicate collection names: ${collections.join(", ")}`);
164
+ }
165
+
166
+ const raw = createMergeableStore();
167
+ raw.setTablesSchema(buildTablesSchema({collections}));
168
+ raw.setValuesSchema(SYNC_VALUES_SCHEMA);
169
+
170
+ const assertCollection = (collection: string): void => {
171
+ if (!known.has(collection)) {
172
+ throw new Error(`Unknown collection "${collection}" (configured: ${collections.join(", ")})`);
173
+ }
174
+ };
175
+
176
+ const upsertEntity = (args: UpsertEntityArgs): SyncEntity => {
177
+ assertCollection(args.collection);
178
+ const existing = raw.hasRow(args.collection, args.id)
179
+ ? (raw.getRow(args.collection, args.id) as Partial<EntityRow>)
180
+ : undefined;
181
+ const deleted = args.deleted ?? existing?.deleted ?? false;
182
+ const row: EntityRow = {
183
+ data: encodeData(args.data),
184
+ deleted,
185
+ // E5: stamp deletedAt the moment a row FIRST becomes a tombstone (not
186
+ // on every subsequent upsert while it stays deleted, and never on a
187
+ // resurrection back to deleted: false — clear it instead). Empty
188
+ // string (what a never-deleted row carries) must be treated the same as
189
+ // "absent" here — `??` alone does not do that.
190
+ deletedAt: deleted ? existing?.deletedAt || now() : "",
191
+ pendingMutationId: args.pendingMutationId ?? existing?.pendingMutationId ?? "",
192
+ seq: args.seq ?? existing?.seq ?? 0,
193
+ stream: args.stream ?? existing?.stream ?? "",
194
+ };
195
+ raw.setRow(args.collection, args.id, row as unknown as Row);
196
+ return rowToEntity(args.id, row);
197
+ };
198
+
199
+ const getEntity = <TData = unknown>(args: {
200
+ collection: string;
201
+ id: string;
202
+ }): SyncEntity<TData> | undefined => {
203
+ assertCollection(args.collection);
204
+ if (!raw.hasRow(args.collection, args.id)) {
205
+ return undefined;
206
+ }
207
+ return rowToEntity<TData>(args.id, raw.getRow(args.collection, args.id) as Partial<EntityRow>);
208
+ };
209
+
210
+ const listEntities = <TData = unknown>(args: {
211
+ collection: string;
212
+ includeDeleted?: boolean;
213
+ }): SyncEntity<TData>[] => {
214
+ assertCollection(args.collection);
215
+ const table = raw.getTable(args.collection);
216
+ const entities: SyncEntity<TData>[] = [];
217
+ for (const [id, row] of Object.entries(table)) {
218
+ const entity = rowToEntity<TData>(id, row as Partial<EntityRow>);
219
+ if (!args.includeDeleted && entity.deleted) {
220
+ continue;
221
+ }
222
+ entities.push(entity);
223
+ }
224
+ return entities;
225
+ };
226
+
227
+ const listPendingEntities = (): Array<{
228
+ collection: string;
229
+ entityId: string;
230
+ pendingMutationId: string;
231
+ }> => {
232
+ const pending: Array<{collection: string; entityId: string; pendingMutationId: string}> = [];
233
+ for (const collection of collections) {
234
+ for (const [id, row] of Object.entries(raw.getTable(collection))) {
235
+ const pendingMutationId = (row as Partial<EntityRow>).pendingMutationId;
236
+ if (!pendingMutationId) {
237
+ continue;
238
+ }
239
+ pending.push({collection, entityId: id, pendingMutationId});
240
+ }
241
+ }
242
+ return pending;
243
+ };
244
+
245
+ const softDeleteEntity = (args: {collection: string; id: string}): void => {
246
+ assertCollection(args.collection);
247
+ if (!raw.hasRow(args.collection, args.id)) {
248
+ return;
249
+ }
250
+ raw.transaction(() => {
251
+ raw.setCell(args.collection, args.id, "deleted", true);
252
+ // E5: stamp deletedAt only on the transition into a tombstone — a
253
+ // second softDeleteEntity call on an already-deleted row (idempotent)
254
+ // must not push the age-out clock forward.
255
+ const currentDeletedAt = raw.getCell(args.collection, args.id, "deletedAt");
256
+ if (!currentDeletedAt) {
257
+ raw.setCell(args.collection, args.id, "deletedAt", now());
258
+ }
259
+ });
260
+ };
261
+
262
+ const clearCollection = (args: {collection: string}): void => {
263
+ assertCollection(args.collection);
264
+ raw.delTable(args.collection);
265
+ };
266
+
267
+ const getSchemaVersion = (): number => {
268
+ const version = raw.getValue("schemaVersion");
269
+ return typeof version === "number" ? version : SYNC_SCHEMA_VERSION;
270
+ };
271
+
272
+ const getLastUserId = (): string | undefined => {
273
+ const userId = raw.getValue("lastUserId");
274
+ return typeof userId === "string" && userId !== "" ? userId : undefined;
275
+ };
276
+
277
+ const setLastUserId = ({userId}: {userId: string}): void => {
278
+ raw.setValue("lastUserId", userId);
279
+ };
280
+
281
+ const compactTombstones = ({
282
+ olderThanMs,
283
+ now: compactionNow = now,
284
+ }: {
285
+ olderThanMs: number;
286
+ now?: () => string;
287
+ }): CompactTombstonesResult => {
288
+ const cutoff = DateTime.fromISO(compactionNow()).minus({milliseconds: olderThanMs});
289
+ return raw.transaction(() => {
290
+ let removed = 0;
291
+ for (const collection of collections) {
292
+ const table = raw.getTable(collection);
293
+ for (const [id, row] of Object.entries(table)) {
294
+ const typedRow = row as Partial<EntityRow>;
295
+ if (!typedRow.deleted || !typedRow.deletedAt) {
296
+ continue;
297
+ }
298
+ const deletedAt = DateTime.fromISO(typedRow.deletedAt);
299
+ if (!deletedAt.isValid || deletedAt < cutoff) {
300
+ raw.delRow(collection, id);
301
+ removed += 1;
302
+ }
303
+ }
304
+ }
305
+ return {removed};
306
+ });
307
+ };
308
+
309
+ const getKnownStreams = (): string[] => Object.keys(raw.getTable(KNOWN_STREAMS_TABLE));
310
+
311
+ const addKnownStream = ({stream, collection}: {stream: string; collection: string}): void => {
312
+ raw.setRow(KNOWN_STREAMS_TABLE, stream, {
313
+ addedAt: now(),
314
+ collection,
315
+ } as unknown as Row);
316
+ };
317
+
318
+ const removeKnownStream = ({stream}: {stream: string}): void => {
319
+ raw.delRow(KNOWN_STREAMS_TABLE, stream);
320
+ };
321
+
322
+ const needsRepairKey = (collection: string, entityId: string): string =>
323
+ `${collection}:${entityId}`;
324
+
325
+ const markNeedsRepair = ({
326
+ collection,
327
+ entityId,
328
+ missedSeq,
329
+ stream,
330
+ }: {
331
+ collection: string;
332
+ entityId: string;
333
+ missedSeq: number;
334
+ stream: string;
335
+ }): void => {
336
+ const rowId = needsRepairKey(collection, entityId);
337
+ const existing = raw.getRow(NEEDS_REPAIR_TABLE, rowId) as Partial<NeedsRepairRow> | undefined;
338
+ const priorMissed = typeof existing?.missedSeq === "number" ? existing.missedSeq : 0;
339
+ raw.setRow(NEEDS_REPAIR_TABLE, rowId, {
340
+ collection,
341
+ entityId,
342
+ markedAt: now(),
343
+ missedSeq: Math.max(priorMissed, missedSeq),
344
+ stream,
345
+ } as unknown as Row);
346
+ };
347
+
348
+ const clearNeedsRepair = ({
349
+ collection,
350
+ entityId,
351
+ }: {
352
+ collection: string;
353
+ entityId: string;
354
+ }): void => {
355
+ raw.delRow(NEEDS_REPAIR_TABLE, needsRepairKey(collection, entityId));
356
+ };
357
+
358
+ const hasNeedsRepair = ({
359
+ collection,
360
+ entityId,
361
+ }: {
362
+ collection: string;
363
+ entityId: string;
364
+ }): boolean => {
365
+ return raw.hasRow(NEEDS_REPAIR_TABLE, needsRepairKey(collection, entityId));
366
+ };
367
+
368
+ const listNeedsRepair = (): Array<{
369
+ collection: string;
370
+ entityId: string;
371
+ missedSeq: number;
372
+ stream: string;
373
+ }> => {
374
+ const rows = raw.getTable(NEEDS_REPAIR_TABLE);
375
+ return Object.entries(rows).map(([rowId, row]) => {
376
+ const typed = row as Partial<NeedsRepairRow>;
377
+ const collection = typed.collection ?? rowId.split(":")[0] ?? "";
378
+ const entityId = typed.entityId ?? rowId.split(":").slice(1).join(":") ?? "";
379
+ return {
380
+ collection,
381
+ entityId,
382
+ missedSeq: typed.missedSeq ?? 0,
383
+ stream: typed.stream ?? "",
384
+ };
385
+ });
386
+ };
387
+
388
+ const clearNeedsRepairForStream = ({stream}: {stream: string}): void => {
389
+ const rows = raw.getTable(NEEDS_REPAIR_TABLE);
390
+ for (const [rowId, row] of Object.entries(rows)) {
391
+ if ((row as Partial<NeedsRepairRow>).stream === stream) {
392
+ raw.delRow(NEEDS_REPAIR_TABLE, rowId);
393
+ }
394
+ }
395
+ };
396
+
397
+ const purgeUnknownStreamEntities = ({collection}: {collection: string}): number => {
398
+ assertCollection(collection);
399
+ return raw.transaction(() => {
400
+ let purged = 0;
401
+ const table = raw.getTable(collection);
402
+ for (const [id, row] of Object.entries(table)) {
403
+ const typed = row as Partial<EntityRow>;
404
+ if (typed.stream) {
405
+ continue;
406
+ }
407
+ if (typed.pendingMutationId) {
408
+ continue;
409
+ }
410
+ raw.delRow(collection, id);
411
+ clearNeedsRepair({collection, entityId: id});
412
+ purged += 1;
413
+ }
414
+ return purged;
415
+ });
416
+ };
417
+
418
+ const purgeStream = ({stream}: {stream: string}): number => {
419
+ // C2 leave-purge deletes rows outright, so E5 deletedAt tombstone semantics
420
+ // do not apply here — a purged stream is gone locally, not soft-deleted.
421
+ let purged = 0;
422
+ for (const collection of collections) {
423
+ const table = raw.getTable(collection);
424
+ for (const [id, row] of Object.entries(table)) {
425
+ if ((row as Partial<EntityRow>).stream === stream) {
426
+ raw.delRow(collection, id);
427
+ purged += 1;
428
+ }
429
+ }
430
+ }
431
+ raw.delRow(CURSORS_TABLE, stream);
432
+ removeKnownStream({stream});
433
+ clearNeedsRepairForStream({stream});
434
+ return purged;
435
+ };
436
+
437
+ return {
438
+ addKnownStream,
439
+ clearCollection,
440
+ clearNeedsRepair,
441
+ clearNeedsRepairForStream,
442
+ collections,
443
+ compactTombstones,
444
+ getEntity,
445
+ getKnownStreams,
446
+ getLastUserId,
447
+ getSchemaVersion,
448
+ hasNeedsRepair,
449
+ listEntities,
450
+ listNeedsRepair,
451
+ listPendingEntities,
452
+ markNeedsRepair,
453
+ purgeStream,
454
+ purgeUnknownStreamEntities,
455
+ raw,
456
+ removeKnownStream,
457
+ setLastUserId,
458
+ softDeleteEntity,
459
+ upsertEntity,
460
+ };
461
+ };
@@ -0,0 +1,159 @@
1
+ /**
2
+ * Internal TinyBase table layout for the local-first store.
3
+ *
4
+ * Entity tables are named after their collection (e.g. "todos"); reserved
5
+ * infrastructure tables are prefixed with "_" so they can never collide with a
6
+ * collection name (collection names starting with "_" are rejected at store
7
+ * creation). TinyBase cells only hold primitives (string | number | boolean),
8
+ * so rich payloads are JSON-encoded into `data`/`args` cells; the `*Row`
9
+ * interfaces below describe those primitive shapes, while the decoded,
10
+ * application-facing shapes live in `../types`.
11
+ */
12
+
13
+ import type {OutboxStatus, SyncMutationOperation} from "../types";
14
+
15
+ /** Reserved table holding durable outbox mutations; rowId = mutationId. */
16
+ export const OUTBOX_TABLE = "_outbox";
17
+
18
+ /** Reserved table holding per-stream sync cursors; rowId = stream key. */
19
+ export const CURSORS_TABLE = "_cursors";
20
+
21
+ /** Reserved table holding unresolved conflicts; rowId = mutationId. */
22
+ export const CONFLICTS_TABLE = "_conflicts";
23
+
24
+ /**
25
+ * C2: reserved table recording the streams the client has bootstrapped (membership set);
26
+ * rowId = stream key. Diffed against `GET /sync/streams` to detect joins (backfill) and
27
+ * leaves (purge), the latter only on a confirmed HTTP-200 membership change (INV-2).
28
+ */
29
+ export const KNOWN_STREAMS_TABLE = "_knownStreams";
30
+
31
+ /**
32
+ * Entities whose server deltas were skipped while a pending outbox mutation
33
+ * protected optimistic state. The cursor advanced past the missed seq, so the
34
+ * entity must be re-fetched once the pending mutation resolves without a server ack.
35
+ */
36
+ export const NEEDS_REPAIR_TABLE = "_needsRepair";
37
+
38
+ /** Prefix marking reserved (non-collection) tables. */
39
+ export const RESERVED_TABLE_PREFIX = "_";
40
+
41
+ /** Primitive row shape for a `{collection}` entity table; rowId = entity id. */
42
+ export interface EntityRow {
43
+ /** JSON-encoded entity payload. */
44
+ data: string;
45
+ /** Soft-delete tombstone flag. */
46
+ deleted: boolean;
47
+ /**
48
+ * ISO-8601 timestamp stamped the moment a tombstone (`deleted: true`) is
49
+ * first applied locally (empty string when not a tombstone, or for
50
+ * tombstones applied before this cell existed). E5's client-side
51
+ * compaction ages tombstones out from this timestamp, not `updated`/
52
+ * `created`, since a tombstone's local arrival time is what determines when
53
+ * it is safe to drop (it must survive at least as long as the server's own
54
+ * retention window, C7).
55
+ */
56
+ deletedAt: string;
57
+ /** Outbox mutation currently protecting this entity's optimistic state ("" = none). */
58
+ pendingMutationId: string;
59
+ /** Highest server seq applied to this entity (0 = local-only, never synced). */
60
+ seq: number;
61
+ /**
62
+ * C2: the stream key this entity was last written under (delta/snapshot). Recorded at
63
+ * apply time so leave-purge can drop a stream's entities in O(stream) without
64
+ * recomputing scope. "" for local-only entities never synced from the server.
65
+ */
66
+ stream: string;
67
+ }
68
+
69
+ /** Primitive row shape for the `_knownStreams` table; rowId = stream key. */
70
+ export interface KnownStreamRow {
71
+ /** The collection tag the stream belongs to. */
72
+ collection: string;
73
+ /** When the stream was first bootstrapped. */
74
+ addedAt: string;
75
+ }
76
+
77
+ /** Primitive row shape for the `_outbox` table; rowId = mutationId. */
78
+ export interface OutboxRow {
79
+ /** JSON-encoded mutation args. */
80
+ args: string;
81
+ /** Diagnostic total attempt count across every send (transport + error-nack). */
82
+ attemptCount: number;
83
+ /**
84
+ * Retry budget counter incremented ONLY on server error-nacks; transport
85
+ * failures never touch this cell (they get unlimited retries). Terminality
86
+ * (`MAX_ERROR_NACK_ATTEMPTS`) is checked against this, not `attemptCount`.
87
+ */
88
+ errorNackCount: number;
89
+ /** Absent when the mutation carries no base version (e.g. creates). */
90
+ baseVersion?: number;
91
+ collection: string;
92
+ createdAt: string;
93
+ /** Monotonic insertion counter; FIFO tiebreaker when createdAt collides. */
94
+ enqueueOrder: number;
95
+ entityId: string;
96
+ operation: SyncMutationOperation;
97
+ status: OutboxStatus;
98
+ userId: string;
99
+ }
100
+
101
+ /** Primitive row shape for the `_cursors` table; rowId = stream key. */
102
+ export interface CursorRow {
103
+ /** Highest seq applied for the stream (advanced by both deltas and snapshot pages). */
104
+ seq: number;
105
+ updatedAt: string;
106
+ /**
107
+ * Highest seq paged through the snapshot endpoint — bootstrap's own resume
108
+ * point, deliberately separate from `seq`. A live delta advances `seq` to the
109
+ * stream head regardless of how far bootstrap has got, so `seq` cannot be used
110
+ * to resume an interrupted bootstrap without permanently skipping every seq in
111
+ * between (see `sync/cursor.ts`). Absent on streams that predate this cell.
112
+ */
113
+ snapshotSeq?: number;
114
+ /** True once a snapshot pass reached the stream head (`hasMore: false`). */
115
+ bootstrapped?: boolean;
116
+ }
117
+
118
+ /** Primitive row shape for the `_needsRepair` table; rowId = `${collection}:${entityId}`. */
119
+ export interface NeedsRepairRow {
120
+ collection: string;
121
+ entityId: string;
122
+ /** Highest server seq skipped while the entity was pending-protected. */
123
+ missedSeq: number;
124
+ /** Stream the skipped delta arrived on (used when applying the repair). */
125
+ stream: string;
126
+ markedAt: string;
127
+ }
128
+
129
+ /** Primitive row shape for the `_conflicts` table; rowId = mutationId. */
130
+ export interface ConflictRow {
131
+ collection: string;
132
+ dismissed: boolean;
133
+ entityId: string;
134
+ /** JSON-encoded local (optimistic) entity data. */
135
+ localData: string;
136
+ /** JSON-encoded canonical server entity data. */
137
+ serverData: string;
138
+ serverSeq: number;
139
+ /** True when the server side of the conflict is a tombstone (Task 9.12). */
140
+ serverDeleted?: boolean;
141
+ }
142
+
143
+ /** Decoded, application-facing entity record returned by store accessors. */
144
+ export interface SyncEntity<TData = unknown> {
145
+ /** Decoded entity payload. */
146
+ data: TData;
147
+ /** Soft-delete tombstone flag. */
148
+ deleted: boolean;
149
+ /** ISO-8601 timestamp the tombstone was first applied; undefined when not a tombstone. */
150
+ deletedAt?: string;
151
+ /** Entity id (the TinyBase row id). */
152
+ id: string;
153
+ /** Outbox mutation currently protecting this entity, if any. */
154
+ pendingMutationId?: string;
155
+ /** Highest server seq applied to this entity (0 = local-only). */
156
+ seq: number;
157
+ /** C2: the stream key this entity was last written under ("" for local-only). */
158
+ stream?: string;
159
+ }