@voidhash/mimic-effect 1.0.0-beta.10 → 1.0.0-beta.12

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 (41) hide show
  1. package/.turbo/turbo-build.log +33 -33
  2. package/dist/DocumentInstance.cjs +3 -1
  3. package/dist/DocumentInstance.d.cts +7 -1
  4. package/dist/DocumentInstance.d.cts.map +1 -1
  5. package/dist/DocumentInstance.d.mts +7 -1
  6. package/dist/DocumentInstance.d.mts.map +1 -1
  7. package/dist/DocumentInstance.mjs +3 -1
  8. package/dist/DocumentInstance.mjs.map +1 -1
  9. package/dist/HotStorage.cjs +7 -6
  10. package/dist/HotStorage.d.cts +6 -2
  11. package/dist/HotStorage.d.cts.map +1 -1
  12. package/dist/HotStorage.d.mts +6 -2
  13. package/dist/HotStorage.d.mts.map +1 -1
  14. package/dist/HotStorage.mjs +7 -6
  15. package/dist/HotStorage.mjs.map +1 -1
  16. package/dist/MimicClusterServerEngine.cjs +7 -0
  17. package/dist/MimicClusterServerEngine.d.cts.map +1 -1
  18. package/dist/MimicClusterServerEngine.d.mts.map +1 -1
  19. package/dist/MimicClusterServerEngine.mjs +7 -0
  20. package/dist/MimicClusterServerEngine.mjs.map +1 -1
  21. package/dist/MimicServerEngine.cjs +3 -0
  22. package/dist/MimicServerEngine.d.cts +8 -0
  23. package/dist/MimicServerEngine.d.cts.map +1 -1
  24. package/dist/MimicServerEngine.d.mts +8 -0
  25. package/dist/MimicServerEngine.d.mts.map +1 -1
  26. package/dist/MimicServerEngine.mjs +3 -0
  27. package/dist/MimicServerEngine.mjs.map +1 -1
  28. package/dist/testing/HotStorageTestSuite.cjs +38 -0
  29. package/dist/testing/HotStorageTestSuite.d.cts.map +1 -1
  30. package/dist/testing/HotStorageTestSuite.d.mts.map +1 -1
  31. package/dist/testing/HotStorageTestSuite.mjs +38 -0
  32. package/dist/testing/HotStorageTestSuite.mjs.map +1 -1
  33. package/dist/testing/types.d.cts +3 -3
  34. package/dist/testing/types.d.mts +3 -3
  35. package/package.json +3 -3
  36. package/src/DocumentInstance.ts +13 -2
  37. package/src/HotStorage.ts +24 -9
  38. package/src/MimicClusterServerEngine.ts +16 -1
  39. package/src/MimicServerEngine.ts +17 -0
  40. package/src/testing/HotStorageTestSuite.ts +56 -0
  41. package/tests/MimicServerEngine.test.ts +29 -3
package/.turbo/turbo-build.log CHANGED
@@ -1,5 +1,5 @@
1
1
 
2
- > @voidhash/mimic-effect@1.0.0-beta.10 build /home/runner/work/mimic/mimic/packages/mimic-effect
2
+ > @voidhash/mimic-effect@1.0.0-beta.12 build /home/runner/work/mimic/mimic/packages/mimic-effect
3
3
  > tsdown
4
4
 
5
5
  ℹ tsdown v0.18.2 powered by rolldown v1.0.0-beta.55
@@ -10,16 +10,16 @@
10
10
  ℹ Build start
11
11
  ℹ [CJS] dist/index.cjs  2.28 kB │ gzip: 0.49 kB
12
12
  ℹ [CJS] dist/testing/index.cjs  0.95 kB │ gzip: 0.22 kB
13
- ℹ [CJS] dist/testing/HotStorageTestSuite.cjs 38.03 kB │ gzip: 5.13 kB
13
+ ℹ [CJS] dist/testing/HotStorageTestSuite.cjs 40.13 kB │ gzip: 5.31 kB
14
14
  ℹ [CJS] dist/testing/StorageIntegrationTestSuite.cjs 20.68 kB │ gzip: 3.67 kB
15
15
  ℹ [CJS] dist/testing/ColdStorageTestSuite.cjs 18.14 kB │ gzip: 3.22 kB
16
- ℹ [CJS] dist/MimicClusterServerEngine.cjs 15.02 kB │ gzip: 3.53 kB
17
- ℹ [CJS] dist/DocumentInstance.cjs 10.46 kB │ gzip: 2.74 kB
16
+ ℹ [CJS] dist/MimicClusterServerEngine.cjs 15.39 kB │ gzip: 3.56 kB
17
+ ℹ [CJS] dist/DocumentInstance.cjs 10.59 kB │ gzip: 2.75 kB
18
18
  ℹ [CJS] dist/MimicServer.cjs 10.37 kB │ gzip: 2.84 kB
19
- ℹ [CJS] dist/MimicServerEngine.cjs  8.30 kB │ gzip: 2.21 kB
19
+ ℹ [CJS] dist/MimicServerEngine.cjs  8.45 kB │ gzip: 2.21 kB
20
20
  ℹ [CJS] dist/testing/FailingStorage.cjs  6.91 kB │ gzip: 1.53 kB
21
21
  ℹ [CJS] dist/Metrics.cjs  4.47 kB │ gzip: 1.08 kB
22
- ℹ [CJS] dist/HotStorage.cjs  3.86 kB │ gzip: 1.27 kB
22
+ ℹ [CJS] dist/HotStorage.cjs  4.06 kB │ gzip: 1.31 kB
23
23
  ℹ [CJS] dist/PresenceManager.cjs  3.81 kB │ gzip: 1.03 kB
24
24
  ℹ [CJS] dist/Protocol.cjs  3.78 kB │ gzip: 1.14 kB
25
25
  ℹ [CJS] dist/testing/assertions.cjs  3.74 kB │ gzip: 1.16 kB
@@ -33,15 +33,15 @@
33
33
  ℹ [CJS] dist/_virtual/_@oxc-project_runtime@0.103.0/helpers/toPropertyKey.cjs  0.37 kB │ gzip: 0.23 kB
34
34
  ℹ [CJS] dist/_virtual/rolldown_runtime.cjs  0.36 kB │ gzip: 0.25 kB
35
35
  ℹ [CJS] dist/testing/types.cjs  0.34 kB │ gzip: 0.23 kB
36
- ℹ [CJS] 25 files, total: 160.61 kB
36
+ ℹ [CJS] 25 files, total: 163.55 kB
37
37
  ℹ [CJS] dist/Protocol.d.cts.map 1.57 kB │ gzip: 0.70 kB
38
38
  ℹ [CJS] dist/Types.d.cts.map 1.44 kB │ gzip: 0.66 kB
39
- ℹ [CJS] dist/DocumentInstance.d.cts.map 1.26 kB │ gzip: 0.57 kB
40
- ℹ [CJS] dist/MimicServerEngine.d.cts.map 0.97 kB │ gzip: 0.49 kB
39
+ ℹ [CJS] dist/DocumentInstance.d.cts.map 1.32 kB │ gzip: 0.59 kB
40
+ ℹ [CJS] dist/MimicServerEngine.d.cts.map 0.93 kB │ gzip: 0.46 kB
41
41
  ℹ [CJS] dist/ColdStorage.d.cts.map 0.70 kB │ gzip: 0.37 kB
42
- ℹ [CJS] dist/HotStorage.d.cts.map 0.67 kB │ gzip: 0.35 kB
43
42
  ℹ [CJS] dist/MimicAuthService.d.cts.map 0.61 kB │ gzip: 0.35 kB
44
43
  ℹ [CJS] dist/Errors.d.cts.map 0.60 kB │ gzip: 0.32 kB
44
+ ℹ [CJS] dist/HotStorage.d.cts.map 0.55 kB │ gzip: 0.32 kB
45
45
  ℹ [CJS] dist/testing/HotStorageTestSuite.d.cts.map 0.48 kB │ gzip: 0.29 kB
46
46
  ℹ [CJS] dist/PresenceManager.d.cts.map 0.45 kB │ gzip: 0.27 kB
47
47
  ℹ [CJS] dist/testing/types.d.cts.map 0.38 kB │ gzip: 0.23 kB
@@ -56,10 +56,10 @@
56
56
  ℹ [CJS] dist/Protocol.d.cts 5.84 kB │ gzip: 1.34 kB
57
57
  ℹ [CJS] dist/Types.d.cts 5.72 kB │ gzip: 1.61 kB
58
58
  ℹ [CJS] dist/Errors.d.cts 4.86 kB │ gzip: 1.02 kB
59
- ℹ [CJS] dist/MimicServerEngine.d.cts 3.60 kB │ gzip: 1.09 kB
60
- ℹ [CJS] dist/DocumentInstance.d.cts 3.07 kB │ gzip: 1.00 kB
59
+ ℹ [CJS] dist/MimicServerEngine.d.cts 4.03 kB │ gzip: 1.20 kB
60
+ ℹ [CJS] dist/DocumentInstance.d.cts 3.34 kB │ gzip: 1.10 kB
61
+ ℹ [CJS] dist/HotStorage.d.cts 3.11 kB │ gzip: 1.23 kB
61
62
  ℹ [CJS] dist/testing/types.d.cts 2.76 kB │ gzip: 1.15 kB
62
- ℹ [CJS] dist/HotStorage.d.cts 2.72 kB │ gzip: 1.08 kB
63
63
  ℹ [CJS] dist/MimicAuthService.d.cts 2.70 kB │ gzip: 1.04 kB
64
64
  ℹ [CJS] dist/testing/HotStorageTestSuite.d.cts 1.93 kB │ gzip: 0.57 kB
65
65
  ℹ [CJS] dist/ColdStorage.d.cts 1.74 kB │ gzip: 0.70 kB
@@ -70,36 +70,36 @@
70
70
  ℹ [CJS] dist/testing/StorageIntegrationTestSuite.d.cts 1.43 kB │ gzip: 0.57 kB
71
71
  ℹ [CJS] dist/MimicClusterServerEngine.d.cts 0.82 kB │ gzip: 0.33 kB
72
72
  ℹ [CJS] dist/MimicServer.d.cts 0.74 kB │ gzip: 0.31 kB
73
- ℹ [CJS] 36 files, total: 57.85 kB
74
- ✔ Build complete in 5947ms
73
+ ℹ [CJS] 36 files, total: 58.86 kB
74
+ ✔ Build complete in 6809ms
75
75
  ℹ [ESM] dist/index.mjs  1.29 kB │ gzip: 0.34 kB
76
76
  ℹ [ESM] dist/testing/index.mjs  0.60 kB │ gzip: 0.19 kB
77
- ℹ [ESM] dist/testing/HotStorageTestSuite.mjs.map 63.42 kB │ gzip: 8.61 kB
77
+ ℹ [ESM] dist/testing/HotStorageTestSuite.mjs.map 67.12 kB │ gzip: 9.05 kB
78
+ ℹ [ESM] dist/testing/HotStorageTestSuite.mjs 36.09 kB │ gzip: 5.26 kB
78
79
  ℹ [ESM] dist/testing/StorageIntegrationTestSuite.mjs.map 35.60 kB │ gzip: 6.44 kB
79
- ℹ [ESM] dist/testing/HotStorageTestSuite.mjs 34.21 kB │ gzip: 5.06 kB
80
80
  ℹ [ESM] dist/testing/ColdStorageTestSuite.mjs.map 31.92 kB │ gzip: 5.21 kB
81
- ℹ [ESM] dist/MimicClusterServerEngine.mjs.map 28.95 kB │ gzip: 6.88 kB
82
- ℹ [ESM] dist/DocumentInstance.mjs.map 23.70 kB │ gzip: 6.13 kB
81
+ ℹ [ESM] dist/MimicClusterServerEngine.mjs.map 29.67 kB │ gzip: 6.99 kB
82
+ ℹ [ESM] dist/DocumentInstance.mjs.map 24.33 kB │ gzip: 6.31 kB
83
83
  ℹ [ESM] dist/MimicServer.mjs.map 21.35 kB │ gzip: 5.64 kB
84
- ℹ [ESM] dist/MimicServerEngine.mjs.map 19.25 kB │ gzip: 4.87 kB
84
+ ℹ [ESM] dist/MimicServerEngine.mjs.map 20.00 kB │ gzip: 5.01 kB
85
85
  ℹ [ESM] dist/testing/StorageIntegrationTestSuite.mjs 18.49 kB │ gzip: 3.63 kB
86
86
  ℹ [ESM] dist/testing/ColdStorageTestSuite.mjs 16.50 kB │ gzip: 3.21 kB
87
87
  ℹ [ESM] dist/testing/FailingStorage.mjs.map 15.60 kB │ gzip: 3.07 kB
88
- ℹ [ESM] dist/MimicClusterServerEngine.mjs 13.93 kB │ gzip: 3.55 kB
89
- ℹ [ESM] dist/HotStorage.mjs.map 10.81 kB │ gzip: 3.04 kB
90
- ℹ [ESM] dist/DocumentInstance.mjs 10.06 kB │ gzip: 2.75 kB
88
+ ℹ [ESM] dist/MimicClusterServerEngine.mjs 14.26 kB │ gzip: 3.58 kB
89
+ ℹ [ESM] dist/HotStorage.mjs.map 11.89 kB │ gzip: 3.36 kB
90
+ ℹ [ESM] dist/DocumentInstance.mjs 10.19 kB │ gzip: 2.77 kB
91
91
  ℹ [ESM] dist/MimicServer.mjs  9.90 kB │ gzip: 2.88 kB
92
92
  ℹ [ESM] dist/PresenceManager.mjs.map  9.38 kB │ gzip: 2.38 kB
93
93
  ℹ [ESM] dist/Protocol.mjs.map  9.18 kB │ gzip: 2.15 kB
94
- ℹ [ESM] dist/MimicServerEngine.mjs  7.82 kB │ gzip: 2.23 kB
94
+ ℹ [ESM] dist/MimicServerEngine.mjs  7.95 kB │ gzip: 2.23 kB
95
95
  ℹ [ESM] dist/testing/assertions.mjs.map  7.31 kB │ gzip: 2.01 kB
96
96
  ℹ [ESM] dist/testing/FailingStorage.mjs  6.49 kB │ gzip: 1.52 kB
97
97
  ℹ [ESM] dist/Metrics.mjs.map  6.35 kB │ gzip: 1.48 kB
98
98
  ℹ [ESM] dist/MimicAuthService.mjs.map  6.09 kB │ gzip: 1.85 kB
99
99
  ℹ [ESM] dist/ColdStorage.mjs.map  5.35 kB │ gzip: 1.64 kB
100
100
  ℹ [ESM] dist/Errors.mjs.map  4.00 kB │ gzip: 1.05 kB
101
+ ℹ [ESM] dist/HotStorage.mjs  3.92 kB │ gzip: 1.32 kB
101
102
  ℹ [ESM] dist/Metrics.mjs  3.81 kB │ gzip: 1.05 kB
102
- ℹ [ESM] dist/HotStorage.mjs  3.73 kB │ gzip: 1.27 kB
103
103
  ℹ [ESM] dist/PresenceManager.mjs  3.48 kB │ gzip: 1.04 kB
104
104
  ℹ [ESM] dist/testing/assertions.mjs  3.46 kB │ gzip: 1.15 kB
105
105
  ℹ [ESM] dist/Protocol.mjs  3.35 kB │ gzip: 1.06 kB
@@ -109,13 +109,13 @@
109
109
  ℹ [ESM] dist/Errors.mjs  1.73 kB │ gzip: 0.61 kB
110
110
  ℹ [ESM] dist/Protocol.d.mts.map  1.57 kB │ gzip: 0.70 kB
111
111
  ℹ [ESM] dist/Types.d.mts.map  1.44 kB │ gzip: 0.66 kB
112
- ℹ [ESM] dist/DocumentInstance.d.mts.map  1.26 kB │ gzip: 0.57 kB
113
- ℹ [ESM] dist/MimicServerEngine.d.mts.map  0.97 kB │ gzip: 0.49 kB
112
+ ℹ [ESM] dist/DocumentInstance.d.mts.map  1.32 kB │ gzip: 0.59 kB
113
+ ℹ [ESM] dist/MimicServerEngine.d.mts.map  0.93 kB │ gzip: 0.46 kB
114
114
  ℹ [ESM] dist/_virtual/_@oxc-project_runtime@0.103.0/helpers/objectSpread2.mjs  0.90 kB │ gzip: 0.42 kB
115
115
  ℹ [ESM] dist/ColdStorage.d.mts.map  0.70 kB │ gzip: 0.37 kB
116
- ℹ [ESM] dist/HotStorage.d.mts.map  0.67 kB │ gzip: 0.35 kB
117
116
  ℹ [ESM] dist/MimicAuthService.d.mts.map  0.61 kB │ gzip: 0.35 kB
118
117
  ℹ [ESM] dist/Errors.d.mts.map  0.60 kB │ gzip: 0.32 kB
118
+ ℹ [ESM] dist/HotStorage.d.mts.map  0.55 kB │ gzip: 0.32 kB
119
119
  ℹ [ESM] dist/testing/HotStorageTestSuite.d.mts.map  0.48 kB │ gzip: 0.29 kB
120
120
  ℹ [ESM] dist/_virtual/rolldown_runtime.mjs  0.47 kB │ gzip: 0.30 kB
121
121
  ℹ [ESM] dist/_virtual/_@oxc-project_runtime@0.103.0/helpers/toPrimitive.mjs  0.47 kB │ gzip: 0.30 kB
@@ -136,10 +136,10 @@
136
136
  ℹ [ESM] dist/Protocol.d.mts  5.84 kB │ gzip: 1.34 kB
137
137
  ℹ [ESM] dist/Types.d.mts  5.72 kB │ gzip: 1.61 kB
138
138
  ℹ [ESM] dist/Errors.d.mts  4.86 kB │ gzip: 1.02 kB
139
- ℹ [ESM] dist/MimicServerEngine.d.mts  3.60 kB │ gzip: 1.09 kB
140
- ℹ [ESM] dist/DocumentInstance.d.mts  3.07 kB │ gzip: 1.00 kB
139
+ ℹ [ESM] dist/MimicServerEngine.d.mts  4.03 kB │ gzip: 1.20 kB
140
+ ℹ [ESM] dist/DocumentInstance.d.mts  3.34 kB │ gzip: 1.10 kB
141
+ ℹ [ESM] dist/HotStorage.d.mts  3.11 kB │ gzip: 1.23 kB
141
142
  ℹ [ESM] dist/testing/types.d.mts  2.76 kB │ gzip: 1.15 kB
142
- ℹ [ESM] dist/HotStorage.d.mts  2.72 kB │ gzip: 1.08 kB
143
143
  ℹ [ESM] dist/MimicAuthService.d.mts  2.70 kB │ gzip: 1.04 kB
144
144
  ℹ [ESM] dist/testing/HotStorageTestSuite.d.mts  1.93 kB │ gzip: 0.57 kB
145
145
  ℹ [ESM] dist/ColdStorage.d.mts  1.74 kB │ gzip: 0.70 kB
@@ -150,5 +150,5 @@
150
150
  ℹ [ESM] dist/testing/StorageIntegrationTestSuite.d.mts  1.43 kB │ gzip: 0.57 kB
151
151
  ℹ [ESM] dist/MimicClusterServerEngine.d.mts  0.82 kB │ gzip: 0.33 kB
152
152
  ℹ [ESM] dist/MimicServer.d.mts  0.74 kB │ gzip: 0.31 kB
153
- ℹ [ESM] 78 files, total: 505.69 kB
154
- ✔ Build complete in 5966ms
153
+ ℹ [ESM] 78 files, total: 516.25 kB
154
+ ✔ Build complete in 6825ms
package/dist/DocumentInstance.cjs CHANGED
@@ -126,7 +126,8 @@ const make = (documentId, config, coldStorage, hotStorage) => effect.Effect.gen(
126
126
  version: validation.nextVersion,
127
127
  timestamp: Date.now()
128
128
  };
129
- const appendResult = yield* effect.Effect.either(hotStorage.appendWithCheck(documentId, walEntry, validation.nextVersion));
129
+ const snapshotVersion = yield* effect.Ref.get(lastSnapshotVersionRef);
130
+ const appendResult = yield* effect.Effect.either(hotStorage.appendWithCheck(documentId, walEntry, validation.nextVersion, snapshotVersion));
130
131
  if (appendResult._tag === "Left") {
131
132
  yield* effect.Effect.logError("WAL append failed", {
132
133
  documentId,
@@ -168,6 +169,7 @@ const make = (documentId, config, coldStorage, hotStorage) => effect.Effect.gen(
168
169
  touch,
169
170
  getVersion: () => document.getVersion(),
170
171
  getSnapshot: () => document.getSnapshot(),
172
+ toSnapshot: () => document.toSnapshot(),
171
173
  needsSnapshot,
172
174
  getLastActivityTime
173
175
  };
package/dist/DocumentInstance.d.cts CHANGED
@@ -60,11 +60,17 @@ interface DocumentInstance<TSchema extends Primitive.AnyPrimitive> {
60
60
  readonly touch: () => Effect.Effect<void>;
61
61
  /** Get current document version */
62
62
  readonly getVersion: () => number;
63
- /** Get document snapshot */
63
+ /** Get document snapshot (flat state format) */
64
64
  readonly getSnapshot: () => {
65
65
  state: unknown;
66
66
  version: number;
67
67
  };
68
+ /**
69
+ * Get tree-like snapshot for rendering.
70
+ * The snapshot is a type-safe, readonly structure where trees
71
+ * are converted from flat state to nested/hierarchical structure.
72
+ */
73
+ readonly toSnapshot: () => Primitive.InferSnapshot<TSchema>;
68
74
  /** Check if document has unsnapshot transactions that need persisting */
69
75
  readonly needsSnapshot: () => Effect.Effect<boolean>;
70
76
  /** Get the last activity timestamp for idle detection */
package/dist/DocumentInstance.d.cts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"DocumentInstance.d.cts","names":[],"sources":["../src/DocumentInstance.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AAkDA;AASiB,KA/BL,YAAA,GA+BqB;EAAiB,SAAU,OAAA,EAAA,IAAA;EAET,SAAA,OAAA,EAAA,MAAA;CAA9B,GAAA;EAEY,SAAA,OAAA,EAAA,KAAA;EAAd,SAAO,MAAA,EAAA,MAAA;CAEoB;;;;AAE2C,UAhCxE,sBAgCwE,CAAA,gBAhCjC,SAAA,CAAU,YAgCuB,CAAA,CAAA;EAAmB,SAAA,MAAA,EA/BzF,OA+ByF;EAA/C,SAAO,OAAA,CAAA,EA7B9D,SAAA,CAAU,aA6BoD,CA7BtC,OA6BsC,CAAA,GAAA,CAAA,CAAA,GAAA,EAAA;IAEjB,UAAA,EAAA,MAAA;EAAmB,CAAA,EAAA,GA9B9B,MAAA,CAAO,MA8BuB,CA9BhB,SAAA,CAAU,aA8BM,CA9BQ,OA8BR,CAAA,CAAA,CAAA;EAAvC,SAAO,qBAAA,EAAA,MAAA;EAEsB,SAAA,QAAA,EAAA;IAAmB,SAAA,QAAA,EA7BxD,QAAA,CAAS,QA6B+C;IAAhC,SAAA,oBAAA,EAAA,MAAA;EAEvB,CAAA;;;;AAmcxB;AA1aqC,UAhDpB,gBAAA,CAgD8B;EAEd,SAAA,mBAAA,EAAA,MAAA;EAAvB,SAAA,gBAAA,EAAA,MAAA;EACK,SAAA,yBAAA,EAAA,MAAA;;;;;AAEgD,UA5C9C,gBA4C8C,CAAA,gBA5Cb,SAAA,CAAU,YA4CG,CAAA,CAAA;EAA5D;EAAa,SAAA,QAAA,EA1CK,cAAA,CAAe,cA0CpB,CA1CmC,OA0CnC,CAAA;;mBAxCG,MAAA,CAAO,OAAO;;gCAED,MAAA,CAAO,OAAO;;iCAEb,WAAA,CAAY,gBAAgB,MAAA,CAAO,OAAO,cAAc,mBAAmB;;+BAE7E,MAAA,CAAO,aAAa,mBAAmB;;wCAE9B,MAAA,CAAO,aAAa,mBAAmB;;wBAEvD,MAAA,CAAO;;;;;;;;;gCAMC,MAAA,CAAO;;sCAED,MAAA,CAAO;;cA2bhC;yBA1awB,SAAA,CAAU,0CAErC,uBAAuB,uBAClB,yBACD,eACX,MAAA,CAAO,OAAO,iBAAiB,UAAU,mBAAmB"}
1
+ {"version":3,"file":"DocumentInstance.d.cts","names":[],"sources":["../src/DocumentInstance.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AAkDA;AASiB,KA/BL,YAAA,GA+BqB;EAAiB,SAAU,OAAA,EAAA,IAAA;EAET,SAAA,OAAA,EAAA,MAAA;CAA9B,GAAA;EAEY,SAAA,OAAA,EAAA,KAAA;EAAd,SAAO,MAAA,EAAA,MAAA;CAEoB;;;;AAE2C,UAhCxE,sBAgCwE,CAAA,gBAhCjC,SAAA,CAAU,YAgCuB,CAAA,CAAA;EAAmB,SAAA,MAAA,EA/BzF,OA+ByF;EAA/C,SAAO,OAAA,CAAA,EA7B9D,SAAA,CAAU,aA6BoD,CA7BtC,OA6BsC,CAAA,GAAA,CAAA,CAAA,GAAA,EAAA;IAEjB,UAAA,EAAA,MAAA;EAAmB,CAAA,EAAA,GA9B9B,MAAA,CAAO,MA8BuB,CA9BhB,SAAA,CAAU,aA8BM,CA9BQ,OA8BR,CAAA,CAAA,CAAA;EAAvC,SAAO,qBAAA,EAAA,MAAA;EAEsB,SAAA,QAAA,EAAA;IAAmB,SAAA,QAAA,EA7BxD,QAAA,CAAS,QA6B+C;IAAhC,SAAA,oBAAA,EAAA,MAAA;EAEvB,CAAA;;;;;AAc2B,UArClC,gBAAA,CAqCkC;EAgctC,SAAA,mBAEZ,EAAA,MAAA;EAjboC,SAAU,gBAAA,EAAA,MAAA;EAEd,SAAA,yBAAA,EAAA,MAAA;;;;;AAGhB,UAlDA,gBAkDA,CAAA,gBAlDiC,SAAA,CAAU,YAkD3C,CAAA,CAAA;EAA2B;EAAmB,SAAA,QAAA,EAhD1C,cAAA,CAAe,cAgD2B,CAhDZ,OAgDY,CAAA;EAA5D;EAAa,SAAA,MAAA,EA9CG,MAAA,CAAO,MA8CV,CA9CiB,eA8CjB,CAAA;;gCA5CgB,MAAA,CAAO,OAAO;;iCAEb,WAAA,CAAY,gBAAgB,MAAA,CAAO,OAAO,cAAc,mBAAmB;;+BAE7E,MAAA,CAAO,aAAa,mBAAmB;;wCAE9B,MAAA,CAAO,aAAa,mBAAmB;;wBAEvD,MAAA,CAAO;;;;;;;;;;;;;6BAUF,SAAA,CAAU,cAAc;;gCAErB,MAAA,CAAO;;sCAED,MAAA,CAAO;;cAgchC;yBA/awB,SAAA,CAAU,0CAErC,uBAAuB,uBAClB,yBACD,eACX,MAAA,CAAO,OAAO,iBAAiB,UAAU,mBAAmB"}
package/dist/DocumentInstance.d.mts CHANGED
@@ -60,11 +60,17 @@ interface DocumentInstance<TSchema extends Primitive.AnyPrimitive> {
60
60
  readonly touch: () => Effect.Effect<void>;
61
61
  /** Get current document version */
62
62
  readonly getVersion: () => number;
63
- /** Get document snapshot */
63
+ /** Get document snapshot (flat state format) */
64
64
  readonly getSnapshot: () => {
65
65
  state: unknown;
66
66
  version: number;
67
67
  };
68
+ /**
69
+ * Get tree-like snapshot for rendering.
70
+ * The snapshot is a type-safe, readonly structure where trees
71
+ * are converted from flat state to nested/hierarchical structure.
72
+ */
73
+ readonly toSnapshot: () => Primitive.InferSnapshot<TSchema>;
68
74
  /** Check if document has unsnapshot transactions that need persisting */
69
75
  readonly needsSnapshot: () => Effect.Effect<boolean>;
70
76
  /** Get the last activity timestamp for idle detection */
package/dist/DocumentInstance.d.mts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"DocumentInstance.d.mts","names":[],"sources":["../src/DocumentInstance.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AAkDA;AASiB,KA/BL,YAAA,GA+BqB;EAAiB,SAAU,OAAA,EAAA,IAAA;EAET,SAAA,OAAA,EAAA,MAAA;CAA9B,GAAA;EAEY,SAAA,OAAA,EAAA,KAAA;EAAd,SAAO,MAAA,EAAA,MAAA;CAEoB;;;;AAE2C,UAhCxE,sBAgCwE,CAAA,gBAhCjC,SAAA,CAAU,YAgCuB,CAAA,CAAA;EAAmB,SAAA,MAAA,EA/BzF,OA+ByF;EAA/C,SAAO,OAAA,CAAA,EA7B9D,SAAA,CAAU,aA6BoD,CA7BtC,OA6BsC,CAAA,GAAA,CAAA,CAAA,GAAA,EAAA;IAEjB,UAAA,EAAA,MAAA;EAAmB,CAAA,EAAA,GA9B9B,MAAA,CAAO,MA8BuB,CA9BhB,SAAA,CAAU,aA8BM,CA9BQ,OA8BR,CAAA,CAAA,CAAA;EAAvC,SAAO,qBAAA,EAAA,MAAA;EAEsB,SAAA,QAAA,EAAA;IAAmB,SAAA,QAAA,EA7BxD,QAAA,CAAS,QA6B+C;IAAhC,SAAA,oBAAA,EAAA,MAAA;EAEvB,CAAA;;;;AAmcxB;AA1aqC,UAhDpB,gBAAA,CAgD8B;EAEd,SAAA,mBAAA,EAAA,MAAA;EAAvB,SAAA,gBAAA,EAAA,MAAA;EACK,SAAA,yBAAA,EAAA,MAAA;;;;;AAEgD,UA5C9C,gBA4C8C,CAAA,gBA5Cb,SAAA,CAAU,YA4CG,CAAA,CAAA;EAA5D;EAAa,SAAA,QAAA,EA1CK,cAAA,CAAe,cA0CpB,CA1CmC,OA0CnC,CAAA;;mBAxCG,MAAA,CAAO,OAAO;;gCAED,MAAA,CAAO,OAAO;;iCAEb,WAAA,CAAY,gBAAgB,MAAA,CAAO,OAAO,cAAc,mBAAmB;;+BAE7E,MAAA,CAAO,aAAa,mBAAmB;;wCAE9B,MAAA,CAAO,aAAa,mBAAmB;;wBAEvD,MAAA,CAAO;;;;;;;;;gCAMC,MAAA,CAAO;;sCAED,MAAA,CAAO;;cA2bhC;yBA1awB,SAAA,CAAU,0CAErC,uBAAuB,uBAClB,yBACD,eACX,MAAA,CAAO,OAAO,iBAAiB,UAAU,mBAAmB"}
1
+ {"version":3,"file":"DocumentInstance.d.mts","names":[],"sources":["../src/DocumentInstance.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AAkDA;AASiB,KA/BL,YAAA,GA+BqB;EAAiB,SAAU,OAAA,EAAA,IAAA;EAET,SAAA,OAAA,EAAA,MAAA;CAA9B,GAAA;EAEY,SAAA,OAAA,EAAA,KAAA;EAAd,SAAO,MAAA,EAAA,MAAA;CAEoB;;;;AAE2C,UAhCxE,sBAgCwE,CAAA,gBAhCjC,SAAA,CAAU,YAgCuB,CAAA,CAAA;EAAmB,SAAA,MAAA,EA/BzF,OA+ByF;EAA/C,SAAO,OAAA,CAAA,EA7B9D,SAAA,CAAU,aA6BoD,CA7BtC,OA6BsC,CAAA,GAAA,CAAA,CAAA,GAAA,EAAA;IAEjB,UAAA,EAAA,MAAA;EAAmB,CAAA,EAAA,GA9B9B,MAAA,CAAO,MA8BuB,CA9BhB,SAAA,CAAU,aA8BM,CA9BQ,OA8BR,CAAA,CAAA,CAAA;EAAvC,SAAO,qBAAA,EAAA,MAAA;EAEsB,SAAA,QAAA,EAAA;IAAmB,SAAA,QAAA,EA7BxD,QAAA,CAAS,QA6B+C;IAAhC,SAAA,oBAAA,EAAA,MAAA;EAEvB,CAAA;;;;;AAc2B,UArClC,gBAAA,CAqCkC;EAgctC,SAAA,mBAEZ,EAAA,MAAA;EAjboC,SAAU,gBAAA,EAAA,MAAA;EAEd,SAAA,yBAAA,EAAA,MAAA;;;;;AAGhB,UAlDA,gBAkDA,CAAA,gBAlDiC,SAAA,CAAU,YAkD3C,CAAA,CAAA;EAA2B;EAAmB,SAAA,QAAA,EAhD1C,cAAA,CAAe,cAgD2B,CAhDZ,OAgDY,CAAA;EAA5D;EAAa,SAAA,MAAA,EA9CG,MAAA,CAAO,MA8CV,CA9CiB,eA8CjB,CAAA;;gCA5CgB,MAAA,CAAO,OAAO;;iCAEb,WAAA,CAAY,gBAAgB,MAAA,CAAO,OAAO,cAAc,mBAAmB;;+BAE7E,MAAA,CAAO,aAAa,mBAAmB;;wCAE9B,MAAA,CAAO,aAAa,mBAAmB;;wBAEvD,MAAA,CAAO;;;;;;;;;;;;;6BAUF,SAAA,CAAU,cAAc;;gCAErB,MAAA,CAAO;;sCAED,MAAA,CAAO;;cAgchC;yBA/awB,SAAA,CAAU,0CAErC,uBAAuB,uBAClB,yBACD,eACX,MAAA,CAAO,OAAO,iBAAiB,UAAU,mBAAmB"}
package/dist/DocumentInstance.mjs CHANGED
@@ -126,7 +126,8 @@ const make = (documentId, config, coldStorage, hotStorage) => Effect.gen(functio
126
126
  version: validation.nextVersion,
127
127
  timestamp: Date.now()
128
128
  };
129
- const appendResult = yield* Effect.either(hotStorage.appendWithCheck(documentId, walEntry, validation.nextVersion));
129
+ const snapshotVersion = yield* Ref.get(lastSnapshotVersionRef);
130
+ const appendResult = yield* Effect.either(hotStorage.appendWithCheck(documentId, walEntry, validation.nextVersion, snapshotVersion));
130
131
  if (appendResult._tag === "Left") {
131
132
  yield* Effect.logError("WAL append failed", {
132
133
  documentId,
@@ -168,6 +169,7 @@ const make = (documentId, config, coldStorage, hotStorage) => Effect.gen(functio
168
169
  touch,
169
170
  getVersion: () => document.getVersion(),
170
171
  getSnapshot: () => document.getSnapshot(),
172
+ toSnapshot: () => document.toSnapshot(),
171
173
  needsSnapshot,
172
174
  getLastActivityTime
173
175
  };
package/dist/DocumentInstance.mjs.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"DocumentInstance.mjs","names":["initialState: Primitive.InferState<TSchema> | undefined","initial: Primitive.InferSetInput<TSchema> | undefined","Metrics.documentsRestored","Metrics.documentsCreated","Metrics.documentsActive","walEntries","storedDoc","Metrics.storageSnapshots","Metrics.storageSnapshotLatency","Metrics.transactionsRejected","latency","Metrics.transactionsLatency","walEntry: WalEntry","Metrics.walAppendFailures","Metrics.transactionsProcessed","Metrics.storageWalAppends","Metrics.storageVersionGaps","snapshotState: Primitive.InferState<TSchema> | undefined"],"sources":["../src/DocumentInstance.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - DocumentInstance\n *\n * Manages the lifecycle of a single document including:\n * - Restoration from storage (cold storage + WAL replay)\n * - Transaction submission with WAL persistence\n * - Snapshot saving and trigger checking\n *\n * Used by both MimicServerEngine (single-node) and MimicClusterServerEngine (clustered).\n */\nimport { Duration, Effect, Metric, PubSub, Ref } from \"effect\";\nimport { Document, type Primitive, type Transaction } from \"@voidhash/mimic\";\nimport { ServerDocument } from \"@voidhash/mimic/server\";\nimport type { StoredDocument, WalEntry } from \"./Types\";\nimport type { ServerBroadcast } from \"./Protocol\";\nimport type { ColdStorage } from \"./ColdStorage\";\nimport type { HotStorage } from \"./HotStorage\";\nimport type { ColdStorageError } from \"./Errors\";\nimport type { HotStorageError } from \"./Errors\";\nimport * as Metrics from \"./Metrics\";\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/**\n * Result of submitting a transaction\n */\nexport type SubmitResult =\n | { readonly success: true; readonly version: number }\n | { readonly success: false; readonly reason: string };\n\n/**\n * Configuration for a DocumentInstance\n */\nexport interface DocumentInstanceConfig<TSchema extends Primitive.AnyPrimitive> {\n readonly schema: TSchema;\n readonly initial?:\n | Primitive.InferSetInput<TSchema>\n | ((ctx: { documentId: string }) => Effect.Effect<Primitive.InferSetInput<TSchema>>);\n readonly maxTransactionHistory: number;\n readonly snapshot: {\n readonly interval: Duration.Duration;\n readonly transactionThreshold: number;\n };\n}\n\n/**\n * Snapshot tracking state\n */\nexport interface SnapshotTracking {\n readonly lastSnapshotVersion: number;\n readonly lastSnapshotTime: number;\n readonly transactionsSinceSnapshot: number;\n}\n\n/**\n * A DocumentInstance manages a single document's lifecycle\n */\nexport interface DocumentInstance<TSchema extends Primitive.AnyPrimitive> {\n /** The underlying ServerDocument */\n readonly document: ServerDocument.ServerDocument<TSchema>;\n /** PubSub for broadcasting messages to subscribers */\n readonly pubsub: PubSub.PubSub<ServerBroadcast>;\n /** Current snapshot tracking state */\n readonly getSnapshotTracking: Effect.Effect<SnapshotTracking>;\n /** Submit a transaction */\n readonly submit: (transaction: Transaction.Transaction) => Effect.Effect<SubmitResult, ColdStorageError | HotStorageError>;\n /** Save a snapshot to cold storage */\n readonly saveSnapshot: () => Effect.Effect<void, ColdStorageError | HotStorageError>;\n /** Check if snapshot should be triggered and save if needed */\n readonly checkSnapshotTriggers: () => Effect.Effect<void, ColdStorageError | HotStorageError>;\n /** Update last activity time (for external tracking) */\n readonly touch: () => Effect.Effect<void>;\n /** Get current document version */\n readonly getVersion: () => number;\n /** Get document snapshot */\n readonly getSnapshot: () => { state: unknown; version: number };\n /** Check if document has unsnapshot transactions that need persisting */\n readonly needsSnapshot: () => Effect.Effect<boolean>;\n /** Get the last activity timestamp for idle detection */\n readonly getLastActivityTime: () => Effect.Effect<number>;\n}\n\n// =============================================================================\n// Factory\n// =============================================================================\n\n/**\n * Create a DocumentInstance for a single document.\n *\n * This handles:\n * - Loading from cold storage or computing initial state\n * - Persisting initial state immediately (crash safety)\n * - Replaying WAL entries\n * - Transaction submission with WAL persistence\n * - Snapshot saving\n */\nexport const make = <TSchema extends Primitive.AnyPrimitive>(\n documentId: string,\n config: DocumentInstanceConfig<TSchema>,\n coldStorage: ColdStorage,\n hotStorage: HotStorage\n): Effect.Effect<DocumentInstance<TSchema>, ColdStorageError | HotStorageError> =>\n Effect.gen(function* () {\n // Current schema version (hard-coded to 1 for now)\n const SCHEMA_VERSION = 1;\n\n // 1. Load snapshot from ColdStorage\n const storedDoc = yield* coldStorage.load(documentId);\n\n // Track initial values - only one will be set:\n // - initialState: raw state from storage (already in internal format)\n // - initial: computed from config (needs conversion to state format)\n let initialState: Primitive.InferState<TSchema> | undefined;\n let initial: Primitive.InferSetInput<TSchema> | undefined;\n let initialVersion = 0;\n\n if (storedDoc) {\n // Loading from storage - state is already in internal format\n initialState = storedDoc.state as Primitive.InferState<TSchema>;\n initialVersion = storedDoc.version;\n } else {\n // New document - compute initial value (set input format)\n initial = yield* computeInitialState(config, documentId);\n }\n\n // 2. Create PubSub for broadcasting\n const pubsub = yield* PubSub.unbounded<ServerBroadcast>();\n\n // 3. Create refs for tracking\n const lastSnapshotVersionRef = yield* Ref.make(initialVersion);\n const lastSnapshotTimeRef = yield* Ref.make(Date.now());\n const transactionsSinceSnapshotRef = yield* Ref.make(0);\n const lastActivityTimeRef = yield* Ref.make(Date.now());\n\n // 4. Create ServerDocument with callbacks\n const document = ServerDocument.make({\n schema: config.schema,\n initial,\n initialState,\n initialVersion,\n maxTransactionHistory: config.maxTransactionHistory,\n onBroadcast: (message: ServerDocument.TransactionMessage) => {\n Effect.runSync(\n PubSub.publish(pubsub, {\n type: \"transaction\",\n transaction: message.transaction,\n version: message.version,\n })\n );\n },\n onRejection: (transactionId: string, reason: string) => {\n Effect.runSync(\n PubSub.publish(pubsub, {\n type: \"error\",\n transactionId,\n reason,\n })\n );\n },\n });\n\n // 5. If this is a new document, immediately save to cold storage\n // This ensures the initial state is durable before any transactions are accepted.\n if (!storedDoc) {\n const initialStoredDoc = createStoredDocument(document.get(), 0, SCHEMA_VERSION);\n yield* coldStorage.save(documentId, initialStoredDoc);\n yield* Effect.logDebug(\"Initial state persisted to cold storage\", { documentId });\n }\n\n // 6. Load WAL entries\n const walEntries = yield* hotStorage.getEntries(documentId, initialVersion);\n\n // 7. Verify WAL continuity (warning only, non-blocking)\n yield* verifyWalContinuity(documentId, walEntries, initialVersion);\n\n // 8. Replay WAL entries\n yield* replayWalEntries(documentId, document, walEntries);\n\n // Track metrics\n if (storedDoc) {\n yield* Metric.increment(Metrics.documentsRestored);\n } else {\n yield* Metric.increment(Metrics.documentsCreated);\n }\n yield* Metric.incrementBy(Metrics.documentsActive, 1);\n\n // ==========================================================================\n // Instance Methods\n // ==========================================================================\n\n const getSnapshotTracking = Effect.gen(function* () {\n return {\n lastSnapshotVersion: yield* Ref.get(lastSnapshotVersionRef),\n lastSnapshotTime: yield* Ref.get(lastSnapshotTimeRef),\n transactionsSinceSnapshot: yield* Ref.get(transactionsSinceSnapshotRef),\n };\n });\n\n const saveSnapshot = Effect.fn(\"document.snapshot.save\")(function* () {\n const targetVersion = document.getVersion();\n const lastSnapshotVersion = yield* Ref.get(lastSnapshotVersionRef);\n\n // Idempotency check: skip if already snapshotted at this version\n if (targetVersion <= lastSnapshotVersion) {\n return;\n }\n\n const snapshotStartTime = Date.now();\n\n // Load base snapshot from cold storage\n const baseSnapshot = yield* coldStorage.load(documentId);\n const baseVersion = baseSnapshot?.version ?? 0;\n const baseState = baseSnapshot?.state as Primitive.InferState<TSchema> | undefined;\n\n // Load WAL entries from base to target\n const walEntries = yield* hotStorage.getEntries(documentId, baseVersion);\n\n // Compute snapshot state by replaying WAL on base\n const snapshotResult = computeSnapshotState(\n config.schema,\n baseState,\n walEntries,\n targetVersion\n );\n\n if (!snapshotResult) {\n return;\n }\n\n // Re-check before saving (in case another snapshot completed while we were working)\n const currentLastSnapshot = yield* Ref.get(lastSnapshotVersionRef);\n if (snapshotResult.version <= currentLastSnapshot) {\n return;\n }\n\n const storedDoc = createStoredDocument(\n snapshotResult.state,\n snapshotResult.version,\n SCHEMA_VERSION\n );\n\n // Save to ColdStorage\n yield* coldStorage.save(documentId, storedDoc);\n\n // Track snapshot metrics\n const snapshotDuration = Date.now() - snapshotStartTime;\n yield* Metric.increment(Metrics.storageSnapshots);\n yield* Metric.update(Metrics.storageSnapshotLatency, snapshotDuration);\n\n // Update tracking BEFORE truncate (for idempotency on retry)\n yield* Ref.set(lastSnapshotVersionRef, snapshotResult.version);\n yield* Ref.set(lastSnapshotTimeRef, Date.now());\n yield* Ref.set(transactionsSinceSnapshotRef, 0);\n\n // Truncate WAL - non-fatal, will be retried on next snapshot\n yield* Effect.catchAll(hotStorage.truncate(documentId, snapshotResult.version), (e) =>\n Effect.logWarning(\"WAL truncate failed - will retry on next snapshot\", {\n documentId,\n version: snapshotResult.version,\n error: e,\n })\n );\n });\n\n const checkSnapshotTriggers = Effect.fn(\"document.snapshot.check-triggers\")(function* () {\n const txCount = yield* Ref.get(transactionsSinceSnapshotRef);\n const lastTime = yield* Ref.get(lastSnapshotTimeRef);\n\n if (shouldTriggerSnapshot(txCount, lastTime, config.snapshot)) {\n yield* saveSnapshot();\n }\n });\n\n const submit = Effect.fn(\"document.transaction.submit\")(function* (\n transaction: Transaction.Transaction\n ) {\n const submitStartTime = Date.now();\n\n // Update activity time\n yield* Ref.set(lastActivityTimeRef, Date.now());\n\n // Phase 1: Validate (no side effects)\n const validation = document.validate(transaction);\n\n if (!validation.valid) {\n yield* Metric.increment(Metrics.transactionsRejected);\n const latency = Date.now() - submitStartTime;\n yield* Metric.update(Metrics.transactionsLatency, latency);\n\n return {\n success: false as const,\n reason: validation.reason,\n };\n }\n\n // Phase 2: Append to WAL with gap check (BEFORE state mutation)\n const walEntry: WalEntry = {\n transaction,\n version: validation.nextVersion,\n timestamp: Date.now(),\n };\n\n const appendResult = yield* Effect.either(\n hotStorage.appendWithCheck(documentId, walEntry, validation.nextVersion)\n );\n\n if (appendResult._tag === \"Left\") {\n yield* Effect.logError(\"WAL append failed\", {\n documentId,\n version: validation.nextVersion,\n error: appendResult.left,\n });\n yield* Metric.increment(Metrics.walAppendFailures);\n\n const latency = Date.now() - submitStartTime;\n yield* Metric.update(Metrics.transactionsLatency, latency);\n\n return {\n success: false as const,\n reason: \"Storage unavailable. Please retry.\",\n };\n }\n\n // Phase 3: Apply (state mutation + broadcast)\n document.apply(transaction);\n\n // Track metrics\n const latency = Date.now() - submitStartTime;\n yield* Metric.update(Metrics.transactionsLatency, latency);\n yield* Metric.increment(Metrics.transactionsProcessed);\n yield* Metric.increment(Metrics.storageWalAppends);\n\n // Increment transaction count\n yield* Ref.update(transactionsSinceSnapshotRef, (n) => n + 1);\n\n // Check snapshot triggers\n yield* checkSnapshotTriggers();\n\n return {\n success: true as const,\n version: validation.nextVersion,\n };\n });\n\n const touch = Effect.fn(\"document.touch\")(function* () {\n yield* Ref.set(lastActivityTimeRef, Date.now());\n });\n\n const needsSnapshot = () =>\n Effect.map(Ref.get(transactionsSinceSnapshotRef), (n) => n > 0);\n\n const getLastActivityTime = () => Ref.get(lastActivityTimeRef);\n\n return {\n document,\n pubsub,\n getSnapshotTracking,\n submit,\n saveSnapshot,\n checkSnapshotTriggers,\n touch,\n getVersion: () => document.getVersion(),\n getSnapshot: () => document.getSnapshot(),\n needsSnapshot,\n getLastActivityTime,\n };\n });\n\n// =============================================================================\n// Helper Functions\n// =============================================================================\n\n/**\n * Compute initial state for a new document.\n */\nconst computeInitialState = <TSchema extends Primitive.AnyPrimitive>(\n config: DocumentInstanceConfig<TSchema>,\n documentId: string\n): Effect.Effect<Primitive.InferSetInput<TSchema> | undefined> => {\n if (config.initial === undefined) {\n return Effect.succeed(undefined);\n }\n\n if (typeof config.initial === \"function\") {\n return (config.initial as (ctx: { documentId: string }) => Effect.Effect<Primitive.InferSetInput<TSchema>>)({\n documentId,\n });\n }\n\n return Effect.succeed(config.initial as Primitive.InferSetInput<TSchema>);\n};\n\n/**\n * Verify WAL continuity and log warnings for any gaps.\n */\nconst verifyWalContinuity = Effect.fn(\"document.wal.verify\")(function* (\n documentId: string,\n walEntries: readonly WalEntry[],\n baseVersion: number\n) {\n if (walEntries.length === 0) {\n return;\n }\n\n const firstWalVersion = walEntries[0]!.version;\n const expectedFirst = baseVersion + 1;\n\n if (firstWalVersion !== expectedFirst) {\n yield* Effect.logWarning(\"WAL version gap detected\", {\n documentId,\n snapshotVersion: baseVersion,\n firstWalVersion,\n expectedFirst,\n });\n yield* Metric.increment(Metrics.storageVersionGaps);\n }\n\n for (let i = 1; i < walEntries.length; i++) {\n const prev = walEntries[i - 1]!.version;\n const curr = walEntries[i]!.version;\n if (curr !== prev + 1) {\n yield* Effect.logWarning(\"WAL internal gap detected\", {\n documentId,\n previousVersion: prev,\n currentVersion: curr,\n });\n }\n }\n});\n\n/**\n * Replay WAL entries onto a ServerDocument.\n */\nconst replayWalEntries = Effect.fn(\"document.wal.replay\")(function* (\n documentId: string,\n document: ServerDocument.ServerDocument<Primitive.AnyPrimitive>,\n walEntries: readonly WalEntry[]\n) {\n for (const entry of walEntries) {\n const result = document.submit(entry.transaction);\n if (!result.success) {\n yield* Effect.logWarning(\"Skipping corrupted WAL entry\", {\n documentId,\n version: entry.version,\n reason: result.reason,\n });\n }\n }\n});\n\n/**\n * Compute snapshot state by replaying WAL entries on a base state.\n */\nconst computeSnapshotState = <TSchema extends Primitive.AnyPrimitive>(\n schema: TSchema,\n baseState: Primitive.InferState<TSchema> | undefined,\n walEntries: readonly WalEntry[],\n targetVersion: number\n): { state: Primitive.InferState<TSchema>; version: number } | undefined => {\n const relevantEntries = walEntries.filter((e) => e.version <= targetVersion);\n\n if (relevantEntries.length === 0 && baseState === undefined) {\n return undefined;\n }\n\n let snapshotState: Primitive.InferState<TSchema> | undefined = baseState;\n for (const entry of relevantEntries) {\n const tempDoc = Document.make(schema, { initialState: snapshotState });\n tempDoc.apply(entry.transaction.ops);\n snapshotState = tempDoc.get();\n }\n\n if (snapshotState === undefined) {\n return undefined;\n }\n\n const snapshotVersion =\n relevantEntries.length > 0 ? relevantEntries[relevantEntries.length - 1]!.version : 0;\n\n return { state: snapshotState, version: snapshotVersion };\n};\n\n/**\n * Check if a snapshot should be triggered.\n */\nconst shouldTriggerSnapshot = (\n transactionsSinceSnapshot: number,\n lastSnapshotTime: number,\n config: { interval: Duration.Duration; transactionThreshold: number }\n): boolean => {\n const now = Date.now();\n const intervalMs = Duration.toMillis(config.interval);\n\n if (transactionsSinceSnapshot >= config.transactionThreshold) {\n return true;\n }\n\n if (now - lastSnapshotTime >= intervalMs) {\n return true;\n }\n\n return false;\n};\n\n/**\n * Create a StoredDocument for persistence.\n */\nconst createStoredDocument = (\n state: unknown,\n version: number,\n schemaVersion: number\n): StoredDocument => ({\n state,\n version,\n schemaVersion,\n savedAt: Date.now(),\n});\n\n// =============================================================================\n// Re-export namespace\n// =============================================================================\n\nexport const DocumentInstance = {\n make,\n};\n"],"mappings":"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"}
1
+ {"version":3,"file":"DocumentInstance.mjs","names":["initialState: Primitive.InferState<TSchema> | undefined","initial: Primitive.InferSetInput<TSchema> | undefined","Metrics.documentsRestored","Metrics.documentsCreated","Metrics.documentsActive","walEntries","storedDoc","Metrics.storageSnapshots","Metrics.storageSnapshotLatency","Metrics.transactionsRejected","latency","Metrics.transactionsLatency","walEntry: WalEntry","Metrics.walAppendFailures","Metrics.transactionsProcessed","Metrics.storageWalAppends","Metrics.storageVersionGaps","snapshotState: Primitive.InferState<TSchema> | undefined"],"sources":["../src/DocumentInstance.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - DocumentInstance\n *\n * Manages the lifecycle of a single document including:\n * - Restoration from storage (cold storage + WAL replay)\n * - Transaction submission with WAL persistence\n * - Snapshot saving and trigger checking\n *\n * Used by both MimicServerEngine (single-node) and MimicClusterServerEngine (clustered).\n */\nimport { Duration, Effect, Metric, PubSub, Ref } from \"effect\";\nimport { Document, type Primitive, type Transaction } from \"@voidhash/mimic\";\nimport { ServerDocument } from \"@voidhash/mimic/server\";\nimport type { StoredDocument, WalEntry } from \"./Types\";\nimport type { ServerBroadcast } from \"./Protocol\";\nimport type { ColdStorage } from \"./ColdStorage\";\nimport type { HotStorage } from \"./HotStorage\";\nimport type { ColdStorageError } from \"./Errors\";\nimport type { HotStorageError } from \"./Errors\";\nimport * as Metrics from \"./Metrics\";\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/**\n * Result of submitting a transaction\n */\nexport type SubmitResult =\n | { readonly success: true; readonly version: number }\n | { readonly success: false; readonly reason: string };\n\n/**\n * Configuration for a DocumentInstance\n */\nexport interface DocumentInstanceConfig<TSchema extends Primitive.AnyPrimitive> {\n readonly schema: TSchema;\n readonly initial?:\n | Primitive.InferSetInput<TSchema>\n | ((ctx: { documentId: string }) => Effect.Effect<Primitive.InferSetInput<TSchema>>);\n readonly maxTransactionHistory: number;\n readonly snapshot: {\n readonly interval: Duration.Duration;\n readonly transactionThreshold: number;\n };\n}\n\n/**\n * Snapshot tracking state\n */\nexport interface SnapshotTracking {\n readonly lastSnapshotVersion: number;\n readonly lastSnapshotTime: number;\n readonly transactionsSinceSnapshot: number;\n}\n\n/**\n * A DocumentInstance manages a single document's lifecycle\n */\nexport interface DocumentInstance<TSchema extends Primitive.AnyPrimitive> {\n /** The underlying ServerDocument */\n readonly document: ServerDocument.ServerDocument<TSchema>;\n /** PubSub for broadcasting messages to subscribers */\n readonly pubsub: PubSub.PubSub<ServerBroadcast>;\n /** Current snapshot tracking state */\n readonly getSnapshotTracking: Effect.Effect<SnapshotTracking>;\n /** Submit a transaction */\n readonly submit: (transaction: Transaction.Transaction) => Effect.Effect<SubmitResult, ColdStorageError | HotStorageError>;\n /** Save a snapshot to cold storage */\n readonly saveSnapshot: () => Effect.Effect<void, ColdStorageError | HotStorageError>;\n /** Check if snapshot should be triggered and save if needed */\n readonly checkSnapshotTriggers: () => Effect.Effect<void, ColdStorageError | HotStorageError>;\n /** Update last activity time (for external tracking) */\n readonly touch: () => Effect.Effect<void>;\n /** Get current document version */\n readonly getVersion: () => number;\n /** Get document snapshot (flat state format) */\n readonly getSnapshot: () => { state: unknown; version: number };\n /**\n * Get tree-like snapshot for rendering.\n * The snapshot is a type-safe, readonly structure where trees\n * are converted from flat state to nested/hierarchical structure.\n */\n readonly toSnapshot: () => Primitive.InferSnapshot<TSchema>;\n /** Check if document has unsnapshot transactions that need persisting */\n readonly needsSnapshot: () => Effect.Effect<boolean>;\n /** Get the last activity timestamp for idle detection */\n readonly getLastActivityTime: () => Effect.Effect<number>;\n}\n\n// =============================================================================\n// Factory\n// =============================================================================\n\n/**\n * Create a DocumentInstance for a single document.\n *\n * This handles:\n * - Loading from cold storage or computing initial state\n * - Persisting initial state immediately (crash safety)\n * - Replaying WAL entries\n * - Transaction submission with WAL persistence\n * - Snapshot saving\n */\nexport const make = <TSchema extends Primitive.AnyPrimitive>(\n documentId: string,\n config: DocumentInstanceConfig<TSchema>,\n coldStorage: ColdStorage,\n hotStorage: HotStorage\n): Effect.Effect<DocumentInstance<TSchema>, ColdStorageError | HotStorageError> =>\n Effect.gen(function* () {\n // Current schema version (hard-coded to 1 for now)\n const SCHEMA_VERSION = 1;\n\n // 1. Load snapshot from ColdStorage\n const storedDoc = yield* coldStorage.load(documentId);\n\n // Track initial values - only one will be set:\n // - initialState: raw state from storage (already in internal format)\n // - initial: computed from config (needs conversion to state format)\n let initialState: Primitive.InferState<TSchema> | undefined;\n let initial: Primitive.InferSetInput<TSchema> | undefined;\n let initialVersion = 0;\n\n if (storedDoc) {\n // Loading from storage - state is already in internal format\n initialState = storedDoc.state as Primitive.InferState<TSchema>;\n initialVersion = storedDoc.version;\n } else {\n // New document - compute initial value (set input format)\n initial = yield* computeInitialState(config, documentId);\n }\n\n // 2. Create PubSub for broadcasting\n const pubsub = yield* PubSub.unbounded<ServerBroadcast>();\n\n // 3. Create refs for tracking\n const lastSnapshotVersionRef = yield* Ref.make(initialVersion);\n const lastSnapshotTimeRef = yield* Ref.make(Date.now());\n const transactionsSinceSnapshotRef = yield* Ref.make(0);\n const lastActivityTimeRef = yield* Ref.make(Date.now());\n\n // 4. Create ServerDocument with callbacks\n const document = ServerDocument.make({\n schema: config.schema,\n initial,\n initialState,\n initialVersion,\n maxTransactionHistory: config.maxTransactionHistory,\n onBroadcast: (message: ServerDocument.TransactionMessage) => {\n Effect.runSync(\n PubSub.publish(pubsub, {\n type: \"transaction\",\n transaction: message.transaction,\n version: message.version,\n })\n );\n },\n onRejection: (transactionId: string, reason: string) => {\n Effect.runSync(\n PubSub.publish(pubsub, {\n type: \"error\",\n transactionId,\n reason,\n })\n );\n },\n });\n\n // 5. If this is a new document, immediately save to cold storage\n // This ensures the initial state is durable before any transactions are accepted.\n if (!storedDoc) {\n const initialStoredDoc = createStoredDocument(document.get(), 0, SCHEMA_VERSION);\n yield* coldStorage.save(documentId, initialStoredDoc);\n yield* Effect.logDebug(\"Initial state persisted to cold storage\", { documentId });\n }\n\n // 6. Load WAL entries\n const walEntries = yield* hotStorage.getEntries(documentId, initialVersion);\n\n // 7. Verify WAL continuity (warning only, non-blocking)\n yield* verifyWalContinuity(documentId, walEntries, initialVersion);\n\n // 8. Replay WAL entries\n yield* replayWalEntries(documentId, document, walEntries);\n\n // Track metrics\n if (storedDoc) {\n yield* Metric.increment(Metrics.documentsRestored);\n } else {\n yield* Metric.increment(Metrics.documentsCreated);\n }\n yield* Metric.incrementBy(Metrics.documentsActive, 1);\n\n // ==========================================================================\n // Instance Methods\n // ==========================================================================\n\n const getSnapshotTracking = Effect.gen(function* () {\n return {\n lastSnapshotVersion: yield* Ref.get(lastSnapshotVersionRef),\n lastSnapshotTime: yield* Ref.get(lastSnapshotTimeRef),\n transactionsSinceSnapshot: yield* Ref.get(transactionsSinceSnapshotRef),\n };\n });\n\n const saveSnapshot = Effect.fn(\"document.snapshot.save\")(function* () {\n const targetVersion = document.getVersion();\n const lastSnapshotVersion = yield* Ref.get(lastSnapshotVersionRef);\n\n // Idempotency check: skip if already snapshotted at this version\n if (targetVersion <= lastSnapshotVersion) {\n return;\n }\n\n const snapshotStartTime = Date.now();\n\n // Load base snapshot from cold storage\n const baseSnapshot = yield* coldStorage.load(documentId);\n const baseVersion = baseSnapshot?.version ?? 0;\n const baseState = baseSnapshot?.state as Primitive.InferState<TSchema> | undefined;\n\n // Load WAL entries from base to target\n const walEntries = yield* hotStorage.getEntries(documentId, baseVersion);\n\n // Compute snapshot state by replaying WAL on base\n const snapshotResult = computeSnapshotState(\n config.schema,\n baseState,\n walEntries,\n targetVersion\n );\n\n if (!snapshotResult) {\n return;\n }\n\n // Re-check before saving (in case another snapshot completed while we were working)\n const currentLastSnapshot = yield* Ref.get(lastSnapshotVersionRef);\n if (snapshotResult.version <= currentLastSnapshot) {\n return;\n }\n\n const storedDoc = createStoredDocument(\n snapshotResult.state,\n snapshotResult.version,\n SCHEMA_VERSION\n );\n\n // Save to ColdStorage\n yield* coldStorage.save(documentId, storedDoc);\n\n // Track snapshot metrics\n const snapshotDuration = Date.now() - snapshotStartTime;\n yield* Metric.increment(Metrics.storageSnapshots);\n yield* Metric.update(Metrics.storageSnapshotLatency, snapshotDuration);\n\n // Update tracking BEFORE truncate (for idempotency on retry)\n yield* Ref.set(lastSnapshotVersionRef, snapshotResult.version);\n yield* Ref.set(lastSnapshotTimeRef, Date.now());\n yield* Ref.set(transactionsSinceSnapshotRef, 0);\n\n // Truncate WAL - non-fatal, will be retried on next snapshot\n yield* Effect.catchAll(hotStorage.truncate(documentId, snapshotResult.version), (e) =>\n Effect.logWarning(\"WAL truncate failed - will retry on next snapshot\", {\n documentId,\n version: snapshotResult.version,\n error: e,\n })\n );\n });\n\n const checkSnapshotTriggers = Effect.fn(\"document.snapshot.check-triggers\")(function* () {\n const txCount = yield* Ref.get(transactionsSinceSnapshotRef);\n const lastTime = yield* Ref.get(lastSnapshotTimeRef);\n\n if (shouldTriggerSnapshot(txCount, lastTime, config.snapshot)) {\n yield* saveSnapshot();\n }\n });\n\n const submit = Effect.fn(\"document.transaction.submit\")(function* (\n transaction: Transaction.Transaction\n ) {\n const submitStartTime = Date.now();\n\n // Update activity time\n yield* Ref.set(lastActivityTimeRef, Date.now());\n\n // Phase 1: Validate (no side effects)\n const validation = document.validate(transaction);\n\n if (!validation.valid) {\n yield* Metric.increment(Metrics.transactionsRejected);\n const latency = Date.now() - submitStartTime;\n yield* Metric.update(Metrics.transactionsLatency, latency);\n\n return {\n success: false as const,\n reason: validation.reason,\n };\n }\n\n // Phase 2: Append to WAL with gap check (BEFORE state mutation)\n const walEntry: WalEntry = {\n transaction,\n version: validation.nextVersion,\n timestamp: Date.now(),\n };\n\n // Get the current snapshot version to pass as baseVersion for gap checking\n // This ensures correct validation after truncation or restart\n const snapshotVersion = yield* Ref.get(lastSnapshotVersionRef);\n\n const appendResult = yield* Effect.either(\n hotStorage.appendWithCheck(documentId, walEntry, validation.nextVersion, snapshotVersion)\n );\n\n if (appendResult._tag === \"Left\") {\n yield* Effect.logError(\"WAL append failed\", {\n documentId,\n version: validation.nextVersion,\n error: appendResult.left,\n });\n yield* Metric.increment(Metrics.walAppendFailures);\n\n const latency = Date.now() - submitStartTime;\n yield* Metric.update(Metrics.transactionsLatency, latency);\n\n return {\n success: false as const,\n reason: \"Storage unavailable. Please retry.\",\n };\n }\n\n // Phase 3: Apply (state mutation + broadcast)\n document.apply(transaction);\n\n // Track metrics\n const latency = Date.now() - submitStartTime;\n yield* Metric.update(Metrics.transactionsLatency, latency);\n yield* Metric.increment(Metrics.transactionsProcessed);\n yield* Metric.increment(Metrics.storageWalAppends);\n\n // Increment transaction count\n yield* Ref.update(transactionsSinceSnapshotRef, (n) => n + 1);\n\n // Check snapshot triggers\n yield* checkSnapshotTriggers();\n\n return {\n success: true as const,\n version: validation.nextVersion,\n };\n });\n\n const touch = Effect.fn(\"document.touch\")(function* () {\n yield* Ref.set(lastActivityTimeRef, Date.now());\n });\n\n const needsSnapshot = () =>\n Effect.map(Ref.get(transactionsSinceSnapshotRef), (n) => n > 0);\n\n const getLastActivityTime = () => Ref.get(lastActivityTimeRef);\n\n return {\n document,\n pubsub,\n getSnapshotTracking,\n submit,\n saveSnapshot,\n checkSnapshotTriggers,\n touch,\n getVersion: () => document.getVersion(),\n getSnapshot: () => document.getSnapshot(),\n toSnapshot: () => document.toSnapshot(),\n needsSnapshot,\n getLastActivityTime,\n };\n });\n\n// =============================================================================\n// Helper Functions\n// =============================================================================\n\n/**\n * Compute initial state for a new document.\n */\nconst computeInitialState = <TSchema extends Primitive.AnyPrimitive>(\n config: DocumentInstanceConfig<TSchema>,\n documentId: string\n): Effect.Effect<Primitive.InferSetInput<TSchema> | undefined> => {\n if (config.initial === undefined) {\n return Effect.succeed(undefined);\n }\n\n if (typeof config.initial === \"function\") {\n return (config.initial as (ctx: { documentId: string }) => Effect.Effect<Primitive.InferSetInput<TSchema>>)({\n documentId,\n });\n }\n\n return Effect.succeed(config.initial as Primitive.InferSetInput<TSchema>);\n};\n\n/**\n * Verify WAL continuity and log warnings for any gaps.\n */\nconst verifyWalContinuity = Effect.fn(\"document.wal.verify\")(function* (\n documentId: string,\n walEntries: readonly WalEntry[],\n baseVersion: number\n) {\n if (walEntries.length === 0) {\n return;\n }\n\n const firstWalVersion = walEntries[0]!.version;\n const expectedFirst = baseVersion + 1;\n\n if (firstWalVersion !== expectedFirst) {\n yield* Effect.logWarning(\"WAL version gap detected\", {\n documentId,\n snapshotVersion: baseVersion,\n firstWalVersion,\n expectedFirst,\n });\n yield* Metric.increment(Metrics.storageVersionGaps);\n }\n\n for (let i = 1; i < walEntries.length; i++) {\n const prev = walEntries[i - 1]!.version;\n const curr = walEntries[i]!.version;\n if (curr !== prev + 1) {\n yield* Effect.logWarning(\"WAL internal gap detected\", {\n documentId,\n previousVersion: prev,\n currentVersion: curr,\n });\n }\n }\n});\n\n/**\n * Replay WAL entries onto a ServerDocument.\n */\nconst replayWalEntries = Effect.fn(\"document.wal.replay\")(function* (\n documentId: string,\n document: ServerDocument.ServerDocument<Primitive.AnyPrimitive>,\n walEntries: readonly WalEntry[]\n) {\n for (const entry of walEntries) {\n const result = document.submit(entry.transaction);\n if (!result.success) {\n yield* Effect.logWarning(\"Skipping corrupted WAL entry\", {\n documentId,\n version: entry.version,\n reason: result.reason,\n });\n }\n }\n});\n\n/**\n * Compute snapshot state by replaying WAL entries on a base state.\n */\nconst computeSnapshotState = <TSchema extends Primitive.AnyPrimitive>(\n schema: TSchema,\n baseState: Primitive.InferState<TSchema> | undefined,\n walEntries: readonly WalEntry[],\n targetVersion: number\n): { state: Primitive.InferState<TSchema>; version: number } | undefined => {\n const relevantEntries = walEntries.filter((e) => e.version <= targetVersion);\n\n if (relevantEntries.length === 0 && baseState === undefined) {\n return undefined;\n }\n\n let snapshotState: Primitive.InferState<TSchema> | undefined = baseState;\n for (const entry of relevantEntries) {\n const tempDoc = Document.make(schema, { initialState: snapshotState });\n tempDoc.apply(entry.transaction.ops);\n snapshotState = tempDoc.get();\n }\n\n if (snapshotState === undefined) {\n return undefined;\n }\n\n const snapshotVersion =\n relevantEntries.length > 0 ? relevantEntries[relevantEntries.length - 1]!.version : 0;\n\n return { state: snapshotState, version: snapshotVersion };\n};\n\n/**\n * Check if a snapshot should be triggered.\n */\nconst shouldTriggerSnapshot = (\n transactionsSinceSnapshot: number,\n lastSnapshotTime: number,\n config: { interval: Duration.Duration; transactionThreshold: number }\n): boolean => {\n const now = Date.now();\n const intervalMs = Duration.toMillis(config.interval);\n\n if (transactionsSinceSnapshot >= config.transactionThreshold) {\n return true;\n }\n\n if (now - lastSnapshotTime >= intervalMs) {\n return true;\n }\n\n return false;\n};\n\n/**\n * Create a StoredDocument for persistence.\n */\nconst createStoredDocument = (\n state: unknown,\n version: number,\n schemaVersion: number\n): StoredDocument => ({\n state,\n version,\n schemaVersion,\n savedAt: Date.now(),\n});\n\n// =============================================================================\n// Re-export namespace\n// =============================================================================\n\nexport const DocumentInstance = {\n make,\n};\n"],"mappings":"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"}
package/dist/HotStorage.cjs CHANGED
@@ -55,19 +55,20 @@ let InMemory;
55
55
  return effect.HashMap.set(map, documentId, [...entries, entry]);
56
56
  });
57
57
  }),
58
- appendWithCheck: effect.Effect.fn("hot-storage.append-with-check")(function* (documentId, entry, expectedVersion) {
58
+ appendWithCheck: effect.Effect.fn("hot-storage.append-with-check")(function* (documentId, entry, expectedVersion, baseVersion) {
59
59
  const result = yield* effect.Ref.modify(store, (map) => {
60
60
  const existing = effect.HashMap.get(map, documentId);
61
61
  const entries = existing._tag === "Some" ? existing.value : [];
62
- const lastVersion = entries.length > 0 ? Math.max(...entries.map((e) => e.version)) : 0;
62
+ const lastEntryVersion = entries.length > 0 ? Math.max(...entries.map((e) => e.version)) : 0;
63
+ const effectiveLastVersion = baseVersion !== void 0 ? Math.max(lastEntryVersion, baseVersion) : lastEntryVersion;
63
64
  if (expectedVersion === 1) {
64
- if (lastVersion >= 1) return [{
65
+ if (effectiveLastVersion >= 1) return [{
65
66
  type: "gap",
66
- lastVersion
67
+ lastVersion: effectiveLastVersion
67
68
  }, map];
68
- } else if (lastVersion !== expectedVersion - 1) return [{
69
+ } else if (effectiveLastVersion !== expectedVersion - 1) return [{
69
70
  type: "gap",
70
- lastVersion: lastVersion > 0 ? lastVersion : void 0
71
+ lastVersion: effectiveLastVersion > 0 ? effectiveLastVersion : void 0
71
72
  }, map];
72
73
  return [{ type: "ok" }, effect.HashMap.set(map, documentId, [...entries, entry])];
73
74
  });
package/dist/HotStorage.d.cts CHANGED
@@ -21,7 +21,7 @@ interface HotStorage {
21
21
  *
22
22
  * This is an atomic operation that:
23
23
  * 1. Verifies the previous entry has version = expectedVersion - 1
24
- * (or this is the first entry if expectedVersion === 1)
24
+ * (or this is the first entry if expectedVersion === 1, accounting for baseVersion)
25
25
  * 2. Appends the entry if check passes
26
26
  *
27
27
  * Use this for two-phase commit to guarantee WAL ordering at write time.
@@ -29,9 +29,13 @@ interface HotStorage {
29
29
  * @param documentId - Document ID
30
30
  * @param entry - WAL entry to append
31
31
  * @param expectedVersion - The version this entry should have (entry.version)
32
+ * @param baseVersion - Optional known snapshot version. When provided, an empty WAL
33
+ * is treated as "at this version" rather than "new document at version 0".
34
+ * This is necessary after truncation or restart to correctly validate
35
+ * that the next entry is baseVersion + 1.
32
36
  * @returns Effect that fails with WalVersionGapError if gap detected
33
37
  */
34
- readonly appendWithCheck: (documentId: string, entry: WalEntry, expectedVersion: number) => Effect.Effect<void, HotStorageError | WalVersionGapError>;
38
+ readonly appendWithCheck: (documentId: string, entry: WalEntry, expectedVersion: number, baseVersion?: number) => Effect.Effect<void, HotStorageError | WalVersionGapError>;
35
39
  /**
36
40
  * Get all WAL entries for a document since a given version.
37
41
  * Returns entries with version > sinceVersion, ordered by version.
package/dist/HotStorage.d.cts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"HotStorage.d.cts","names":[],"sources":["../src/HotStorage.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAyDO,UArCU,UAAA,CAqCH;EASa;;;EAC1B,SAAA,MAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,KAAA,EAzCU,QAyCV,EAAA,GAxCM,MAAA,CAAO,MAwCb,CAAA,IAAA,EAxC0B,eAwC1B,CAAA;;;;;AASD;AAuDA;AAwHA;;;;;;;;;EArIG,SAAM,eAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,KAAA,EAxEE,QAwEF,EAAA,eAAA,EAAA,MAAA,EAAA,GAtEF,MAAA,CAAO,MAsEL,CAAA,IAAA,EAtEkB,eAsElB,GAtEoC,kBAsEpC,CAAA;;;;;qEA7DF,MAAA,CAAO,OAAO,YAAY;;;;;kEAS1B,MAAA,CAAO,aAAa;;cAC1B;;;;cASY,aAAA,SAAsB,kBAAA;;;;;;;kBAuDlB,QAAA;;;;oBAIS,KAAA,CAAM,MAAM;;cAoHzB;;uBAtIH,MAAA,CAAO,OAAO,YAAY,GAAG,OACpC,KAAA,CAAM,MAAM,eAAe,GAAG"}
1
+ {"version":3,"file":"HotStorage.d.cts","names":[],"sources":["../src/HotStorage.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AA8DO,UA1CU,UAAA,CA0CH;EASa;;;EAC1B,SAAA,MAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,KAAA,EA9CU,QA8CV,EAAA,GA7CM,MAAA,CAAO,MA6Cb,CAAA,IAAA,EA7C0B,eA6C1B,CAAA;;;;;AASD;AAuDA;AAkIA;;;;;;;;;;;;;wDAxNW,4DAGJ,MAAA,CAAO,aAAa,kBAAkB;;;;;qEAStC,MAAA,CAAO,OAAO,YAAY;;;;;kEAS1B,MAAA,CAAO,aAAa;;cAC1B;;;;cASY,aAAA,SAAsB,kBAAA;;;;;;;kBAuDlB,QAAA;;;;oBAIS,KAAA,CAAM,MAAM;;cA8HzB;;uBAhJH,MAAA,CAAO,OAAO,YAAY,GAAG,OACpC,KAAA,CAAM,MAAM,eAAe,GAAG"}
package/dist/HotStorage.d.mts CHANGED
@@ -21,7 +21,7 @@ interface HotStorage {
21
21
  *
22
22
  * This is an atomic operation that:
23
23
  * 1. Verifies the previous entry has version = expectedVersion - 1
24
- * (or this is the first entry if expectedVersion === 1)
24
+ * (or this is the first entry if expectedVersion === 1, accounting for baseVersion)
25
25
  * 2. Appends the entry if check passes
26
26
  *
27
27
  * Use this for two-phase commit to guarantee WAL ordering at write time.
@@ -29,9 +29,13 @@ interface HotStorage {
29
29
  * @param documentId - Document ID
30
30
  * @param entry - WAL entry to append
31
31
  * @param expectedVersion - The version this entry should have (entry.version)
32
+ * @param baseVersion - Optional known snapshot version. When provided, an empty WAL
33
+ * is treated as "at this version" rather than "new document at version 0".
34
+ * This is necessary after truncation or restart to correctly validate
35
+ * that the next entry is baseVersion + 1.
32
36
  * @returns Effect that fails with WalVersionGapError if gap detected
33
37
  */
34
- readonly appendWithCheck: (documentId: string, entry: WalEntry, expectedVersion: number) => Effect.Effect<void, HotStorageError | WalVersionGapError>;
38
+ readonly appendWithCheck: (documentId: string, entry: WalEntry, expectedVersion: number, baseVersion?: number) => Effect.Effect<void, HotStorageError | WalVersionGapError>;
35
39
  /**
36
40
  * Get all WAL entries for a document since a given version.
37
41
  * Returns entries with version > sinceVersion, ordered by version.
package/dist/HotStorage.d.mts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"HotStorage.d.mts","names":[],"sources":["../src/HotStorage.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAyDO,UArCU,UAAA,CAqCH;EASa;;;EAC1B,SAAA,MAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,KAAA,EAzCU,QAyCV,EAAA,GAxCM,MAAA,CAAO,MAwCb,CAAA,IAAA,EAxC0B,eAwC1B,CAAA;;;;;AASD;AAuDA;AAwHA;;;;;;;;;EArIG,SAAM,eAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,KAAA,EAxEE,QAwEF,EAAA,eAAA,EAAA,MAAA,EAAA,GAtEF,MAAA,CAAO,MAsEL,CAAA,IAAA,EAtEkB,eAsElB,GAtEoC,kBAsEpC,CAAA;;;;;qEA7DF,MAAA,CAAO,OAAO,YAAY;;;;;kEAS1B,MAAA,CAAO,aAAa;;cAC1B;;;;cASY,aAAA,SAAsB,kBAAA;;;;;;;kBAuDlB,QAAA;;;;oBAIS,KAAA,CAAM,MAAM;;cAoHzB;;uBAtIH,MAAA,CAAO,OAAO,YAAY,GAAG,OACpC,KAAA,CAAM,MAAM,eAAe,GAAG"}
1
+ {"version":3,"file":"HotStorage.d.mts","names":[],"sources":["../src/HotStorage.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AA8DO,UA1CU,UAAA,CA0CH;EASa;;;EAC1B,SAAA,MAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,KAAA,EA9CU,QA8CV,EAAA,GA7CM,MAAA,CAAO,MA6Cb,CAAA,IAAA,EA7C0B,eA6C1B,CAAA;;;;;AASD;AAuDA;AAkIA;;;;;;;;;;;;;wDAxNW,4DAGJ,MAAA,CAAO,aAAa,kBAAkB;;;;;qEAStC,MAAA,CAAO,OAAO,YAAY;;;;;kEAS1B,MAAA,CAAO,aAAa;;cAC1B;;;;cASY,aAAA,SAAsB,kBAAA;;;;;;;kBAuDlB,QAAA;;;;oBAIS,KAAA,CAAM,MAAM;;cA8HzB;;uBAhJH,MAAA,CAAO,OAAO,YAAY,GAAG,OACpC,KAAA,CAAM,MAAM,eAAe,GAAG"}
package/dist/HotStorage.mjs CHANGED
@@ -55,19 +55,20 @@ let InMemory;
55
55
  return HashMap.set(map, documentId, [...entries, entry]);
56
56
  });
57
57
  }),
58
- appendWithCheck: Effect.fn("hot-storage.append-with-check")(function* (documentId, entry, expectedVersion) {
58
+ appendWithCheck: Effect.fn("hot-storage.append-with-check")(function* (documentId, entry, expectedVersion, baseVersion) {
59
59
  const result = yield* Ref.modify(store, (map) => {
60
60
  const existing = HashMap.get(map, documentId);
61
61
  const entries = existing._tag === "Some" ? existing.value : [];
62
- const lastVersion = entries.length > 0 ? Math.max(...entries.map((e) => e.version)) : 0;
62
+ const lastEntryVersion = entries.length > 0 ? Math.max(...entries.map((e) => e.version)) : 0;
63
+ const effectiveLastVersion = baseVersion !== void 0 ? Math.max(lastEntryVersion, baseVersion) : lastEntryVersion;
63
64
  if (expectedVersion === 1) {
64
- if (lastVersion >= 1) return [{
65
+ if (effectiveLastVersion >= 1) return [{
65
66
  type: "gap",
66
- lastVersion
67
+ lastVersion: effectiveLastVersion
67
68
  }, map];
68
- } else if (lastVersion !== expectedVersion - 1) return [{
69
+ } else if (effectiveLastVersion !== expectedVersion - 1) return [{
69
70
  type: "gap",
70
- lastVersion: lastVersion > 0 ? lastVersion : void 0
71
+ lastVersion: effectiveLastVersion > 0 ? effectiveLastVersion : void 0
71
72
  }, map];
72
73
  return [{ type: "ok" }, HashMap.set(map, documentId, [...entries, entry])];
73
74
  });
package/dist/HotStorage.mjs.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"HotStorage.mjs","names":["result: CheckResult"],"sources":["../src/HotStorage.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - HotStorage\n *\n * Interface and implementations for Write-Ahead Log (WAL) storage.\n */\nimport { Context, Effect, HashMap, Layer, Ref } from \"effect\";\nimport type { WalEntry } from \"./Types\";\nimport { HotStorageError, WalVersionGapError } from \"./Errors\";\n\n// =============================================================================\n// HotStorage Interface\n// =============================================================================\n\n/**\n * HotStorage interface for storing Write-Ahead Log entries.\n *\n * This is the \"hot\" tier of the two-tier storage system.\n * It stores every transaction as a WAL entry for durability between snapshots.\n * WAL entries are small (just the transaction) and writes are append-only.\n */\nexport interface HotStorage {\n /**\n * Append a WAL entry for a document.\n */\n readonly append: (\n documentId: string,\n entry: WalEntry\n ) => Effect.Effect<void, HotStorageError>;\n\n /**\n * Append a WAL entry with version gap checking.\n *\n * This is an atomic operation that:\n * 1. Verifies the previous entry has version = expectedVersion - 1\n * (or this is the first entry if expectedVersion === 1)\n * 2. Appends the entry if check passes\n *\n * Use this for two-phase commit to guarantee WAL ordering at write time.\n *\n * @param documentId - Document ID\n * @param entry - WAL entry to append\n * @param expectedVersion - The version this entry should have (entry.version)\n * @returns Effect that fails with WalVersionGapError if gap detected\n */\n readonly appendWithCheck: (\n documentId: string,\n entry: WalEntry,\n expectedVersion: number\n ) => Effect.Effect<void, HotStorageError | WalVersionGapError>;\n\n /**\n * Get all WAL entries for a document since a given version.\n * Returns entries with version > sinceVersion, ordered by version.\n */\n readonly getEntries: (\n documentId: string,\n sinceVersion: number\n ) => Effect.Effect<WalEntry[], HotStorageError>;\n\n /**\n * Truncate WAL entries up to (and including) a given version.\n * Called after a snapshot is saved to remove entries that are now in the snapshot.\n */\n readonly truncate: (\n documentId: string,\n upToVersion: number\n ) => Effect.Effect<void, HotStorageError>;\n}\n\n// =============================================================================\n// Context Tag\n// =============================================================================\n\n/**\n * Context tag for HotStorage service\n */\nexport class HotStorageTag extends Context.Tag(\"@voidhash/mimic-effect/HotStorage\")<\n HotStorageTag,\n HotStorage\n>() {}\n\n// =============================================================================\n// Factory\n// =============================================================================\n\n/**\n * Create a HotStorage layer from an Effect that produces a HotStorage service.\n *\n * This allows you to access other Effect services when implementing custom storage.\n *\n * @example\n * ```typescript\n * const Hot = HotStorage.make(\n * Effect.gen(function*() {\n * const redis = yield* RedisService\n *\n * return {\n * append: (documentId, entry) =>\n * redis.rpush(`wal:${documentId}`, JSON.stringify(entry)),\n * getEntries: (documentId, sinceVersion) =>\n * redis.lrange(`wal:${documentId}`, 0, -1).pipe(\n * Effect.map(entries =>\n * entries\n * .map(e => JSON.parse(e))\n * .filter(e => e.version > sinceVersion)\n * .sort((a, b) => a.version - b.version)\n * )\n * ),\n * truncate: (documentId, upToVersion) =>\n * // Implementation depends on Redis data structure\n * Effect.void,\n * }\n * })\n * )\n * ```\n */\nexport const make = <E, R>(\n effect: Effect.Effect<HotStorage, E, R>\n): Layer.Layer<HotStorageTag, E, R> =>\n Layer.effect(HotStorageTag, effect);\n\n// =============================================================================\n// InMemory Implementation\n// =============================================================================\n\n/**\n * In-memory HotStorage implementation.\n *\n * Useful for testing and development. Not suitable for production\n * as data is lost when the process restarts.\n */\nexport namespace InMemory {\n /**\n * Create an in-memory HotStorage layer.\n */\n export const make = (): Layer.Layer<HotStorageTag> =>\n Layer.effect(\n HotStorageTag,\n Effect.fn(\"hot-storage.in-memory.create\")(function* () {\n const store = yield* Ref.make(HashMap.empty<string, WalEntry[]>());\n\n return {\n append: Effect.fn(\"hot-storage.append\")(\n function* (documentId: string, entry: WalEntry) {\n yield* Ref.update(store, (map) => {\n const existing = HashMap.get(map, documentId);\n const entries =\n existing._tag === \"Some\" ? existing.value : [];\n return HashMap.set(map, documentId, [...entries, entry]);\n });\n }\n ),\n\n appendWithCheck: Effect.fn(\"hot-storage.append-with-check\")(\n function* (\n documentId: string,\n entry: WalEntry,\n expectedVersion: number\n ) {\n type CheckResult =\n | { type: \"ok\" }\n | { type: \"gap\"; lastVersion: number | undefined };\n\n // Use Ref.modify for atomic check + update\n const result: CheckResult = yield* Ref.modify(\n store,\n (map): [CheckResult, HashMap.HashMap<string, WalEntry[]>] => {\n const existing = HashMap.get(map, documentId);\n const entries =\n existing._tag === \"Some\" ? existing.value : [];\n\n // Find the highest version in existing entries\n const lastVersion =\n entries.length > 0\n ? Math.max(...entries.map((e) => e.version))\n : 0;\n\n // Gap check\n if (expectedVersion === 1) {\n // First entry: should have no entries with version >= 1\n if (lastVersion >= 1) {\n return [{ type: \"gap\", lastVersion }, map];\n }\n } else {\n // Not first: last entry should have version = expectedVersion - 1\n if (lastVersion !== expectedVersion - 1) {\n return [\n {\n type: \"gap\",\n lastVersion: lastVersion > 0 ? lastVersion : undefined,\n },\n map,\n ];\n }\n }\n\n // No gap: append and return success\n return [\n { type: \"ok\" },\n HashMap.set(map, documentId, [...entries, entry]),\n ];\n }\n );\n\n if (result.type === \"gap\") {\n return yield* Effect.fail(\n new WalVersionGapError({\n documentId,\n expectedVersion,\n actualPreviousVersion: result.lastVersion,\n })\n );\n }\n }\n ),\n\n getEntries: Effect.fn(\"hot-storage.get-entries\")(\n function* (documentId: string, sinceVersion: number) {\n const current = yield* Ref.get(store);\n const existing = HashMap.get(current, documentId);\n const entries =\n existing._tag === \"Some\" ? existing.value : [];\n return entries\n .filter((e) => e.version > sinceVersion)\n .sort((a, b) => a.version - b.version);\n }\n ),\n\n truncate: Effect.fn(\"hot-storage.truncate\")(\n function* (documentId: string, upToVersion: number) {\n yield* Ref.update(store, (map) => {\n const existing = HashMap.get(map, documentId);\n if (existing._tag === \"None\") {\n return map;\n }\n const filtered = existing.value.filter(\n (e) => e.version > upToVersion\n );\n return HashMap.set(map, documentId, filtered);\n });\n }\n ),\n };\n })()\n );\n}\n\n// =============================================================================\n// Re-export namespace\n// =============================================================================\n\nexport const HotStorage = {\n Tag: HotStorageTag,\n make,\n InMemory,\n};\n"],"mappings":";;;;;;;;;;;;AA4EA,IAAa,gBAAb,cAAmC,QAAQ,IAAI,oCAAoC,EAGhF,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCJ,MAAa,QACX,WAEA,MAAM,OAAO,eAAe,OAAO;;;wBAiBjC,MAAM,OACJ,eACA,OAAO,GAAG,+BAA+B,CAAC,aAAa;EACrD,MAAM,QAAQ,OAAO,IAAI,KAAK,QAAQ,OAA2B,CAAC;AAElE,SAAO;GACL,QAAQ,OAAO,GAAG,qBAAqB,CACrC,WAAW,YAAoB,OAAiB;AAC9C,WAAO,IAAI,OAAO,QAAQ,QAAQ;KAChC,MAAM,WAAW,QAAQ,IAAI,KAAK,WAAW;KAC7C,MAAM,UACJ,SAAS,SAAS,SAAS,SAAS,QAAQ,EAAE;AAChD,YAAO,QAAQ,IAAI,KAAK,YAAY,CAAC,GAAG,SAAS,MAAM,CAAC;MACxD;KAEL;GAED,iBAAiB,OAAO,GAAG,gCAAgC,CACzD,WACE,YACA,OACA,iBACA;IAMA,MAAMA,SAAsB,OAAO,IAAI,OACrC,QACC,QAA4D;KAC3D,MAAM,WAAW,QAAQ,IAAI,KAAK,WAAW;KAC7C,MAAM,UACJ,SAAS,SAAS,SAAS,SAAS,QAAQ,EAAE;KAGhD,MAAM,cACJ,QAAQ,SAAS,IACb,KAAK,IAAI,GAAG,QAAQ,KAAK,MAAM,EAAE,QAAQ,CAAC,GAC1C;AAGN,SAAI,oBAAoB,GAEtB;UAAI,eAAe,EACjB,QAAO,CAAC;OAAE,MAAM;OAAO;OAAa,EAAE,IAAI;gBAIxC,gBAAgB,kBAAkB,EACpC,QAAO,CACL;MACE,MAAM;MACN,aAAa,cAAc,IAAI,cAAc;MAC9C,EACD,IACD;AAKL,YAAO,CACL,EAAE,MAAM,MAAM,EACd,QAAQ,IAAI,KAAK,YAAY,CAAC,GAAG,SAAS,MAAM,CAAC,CAClD;MAEJ;AAED,QAAI,OAAO,SAAS,MAClB,QAAO,OAAO,OAAO,KACnB,IAAI,mBAAmB;KACrB;KACA;KACA,uBAAuB,OAAO;KAC/B,CAAC,CACH;KAGN;GAED,YAAY,OAAO,GAAG,0BAA0B,CAC9C,WAAW,YAAoB,cAAsB;IACnD,MAAM,UAAU,OAAO,IAAI,IAAI,MAAM;IACrC,MAAM,WAAW,QAAQ,IAAI,SAAS,WAAW;AAGjD,YADE,SAAS,SAAS,SAAS,SAAS,QAAQ,EAAE,EAE7C,QAAQ,MAAM,EAAE,UAAU,aAAa,CACvC,MAAM,GAAG,MAAM,EAAE,UAAU,EAAE,QAAQ;KAE3C;GAED,UAAU,OAAO,GAAG,uBAAuB,CACzC,WAAW,YAAoB,aAAqB;AAClD,WAAO,IAAI,OAAO,QAAQ,QAAQ;KAChC,MAAM,WAAW,QAAQ,IAAI,KAAK,WAAW;AAC7C,SAAI,SAAS,SAAS,OACpB,QAAO;KAET,MAAM,WAAW,SAAS,MAAM,QAC7B,MAAM,EAAE,UAAU,YACpB;AACD,YAAO,QAAQ,IAAI,KAAK,YAAY,SAAS;MAC7C;KAEL;GACF;GACD,EAAE,CACL;;AAOL,MAAa,aAAa;CACxB,KAAK;CACL;CACA;CACD"}
1
+ {"version":3,"file":"HotStorage.mjs","names":["result: CheckResult"],"sources":["../src/HotStorage.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - HotStorage\n *\n * Interface and implementations for Write-Ahead Log (WAL) storage.\n */\nimport { Context, Effect, HashMap, Layer, Ref } from \"effect\";\nimport type { WalEntry } from \"./Types\";\nimport { HotStorageError, WalVersionGapError } from \"./Errors\";\n\n// =============================================================================\n// HotStorage Interface\n// =============================================================================\n\n/**\n * HotStorage interface for storing Write-Ahead Log entries.\n *\n * This is the \"hot\" tier of the two-tier storage system.\n * It stores every transaction as a WAL entry for durability between snapshots.\n * WAL entries are small (just the transaction) and writes are append-only.\n */\nexport interface HotStorage {\n /**\n * Append a WAL entry for a document.\n */\n readonly append: (\n documentId: string,\n entry: WalEntry\n ) => Effect.Effect<void, HotStorageError>;\n\n /**\n * Append a WAL entry with version gap checking.\n *\n * This is an atomic operation that:\n * 1. Verifies the previous entry has version = expectedVersion - 1\n * (or this is the first entry if expectedVersion === 1, accounting for baseVersion)\n * 2. Appends the entry if check passes\n *\n * Use this for two-phase commit to guarantee WAL ordering at write time.\n *\n * @param documentId - Document ID\n * @param entry - WAL entry to append\n * @param expectedVersion - The version this entry should have (entry.version)\n * @param baseVersion - Optional known snapshot version. When provided, an empty WAL\n * is treated as \"at this version\" rather than \"new document at version 0\".\n * This is necessary after truncation or restart to correctly validate\n * that the next entry is baseVersion + 1.\n * @returns Effect that fails with WalVersionGapError if gap detected\n */\n readonly appendWithCheck: (\n documentId: string,\n entry: WalEntry,\n expectedVersion: number,\n baseVersion?: number\n ) => Effect.Effect<void, HotStorageError | WalVersionGapError>;\n\n /**\n * Get all WAL entries for a document since a given version.\n * Returns entries with version > sinceVersion, ordered by version.\n */\n readonly getEntries: (\n documentId: string,\n sinceVersion: number\n ) => Effect.Effect<WalEntry[], HotStorageError>;\n\n /**\n * Truncate WAL entries up to (and including) a given version.\n * Called after a snapshot is saved to remove entries that are now in the snapshot.\n */\n readonly truncate: (\n documentId: string,\n upToVersion: number\n ) => Effect.Effect<void, HotStorageError>;\n}\n\n// =============================================================================\n// Context Tag\n// =============================================================================\n\n/**\n * Context tag for HotStorage service\n */\nexport class HotStorageTag extends Context.Tag(\"@voidhash/mimic-effect/HotStorage\")<\n HotStorageTag,\n HotStorage\n>() {}\n\n// =============================================================================\n// Factory\n// =============================================================================\n\n/**\n * Create a HotStorage layer from an Effect that produces a HotStorage service.\n *\n * This allows you to access other Effect services when implementing custom storage.\n *\n * @example\n * ```typescript\n * const Hot = HotStorage.make(\n * Effect.gen(function*() {\n * const redis = yield* RedisService\n *\n * return {\n * append: (documentId, entry) =>\n * redis.rpush(`wal:${documentId}`, JSON.stringify(entry)),\n * getEntries: (documentId, sinceVersion) =>\n * redis.lrange(`wal:${documentId}`, 0, -1).pipe(\n * Effect.map(entries =>\n * entries\n * .map(e => JSON.parse(e))\n * .filter(e => e.version > sinceVersion)\n * .sort((a, b) => a.version - b.version)\n * )\n * ),\n * truncate: (documentId, upToVersion) =>\n * // Implementation depends on Redis data structure\n * Effect.void,\n * }\n * })\n * )\n * ```\n */\nexport const make = <E, R>(\n effect: Effect.Effect<HotStorage, E, R>\n): Layer.Layer<HotStorageTag, E, R> =>\n Layer.effect(HotStorageTag, effect);\n\n// =============================================================================\n// InMemory Implementation\n// =============================================================================\n\n/**\n * In-memory HotStorage implementation.\n *\n * Useful for testing and development. Not suitable for production\n * as data is lost when the process restarts.\n */\nexport namespace InMemory {\n /**\n * Create an in-memory HotStorage layer.\n */\n export const make = (): Layer.Layer<HotStorageTag> =>\n Layer.effect(\n HotStorageTag,\n Effect.fn(\"hot-storage.in-memory.create\")(function* () {\n const store = yield* Ref.make(HashMap.empty<string, WalEntry[]>());\n\n return {\n append: Effect.fn(\"hot-storage.append\")(\n function* (documentId: string, entry: WalEntry) {\n yield* Ref.update(store, (map) => {\n const existing = HashMap.get(map, documentId);\n const entries =\n existing._tag === \"Some\" ? existing.value : [];\n return HashMap.set(map, documentId, [...entries, entry]);\n });\n }\n ),\n\n appendWithCheck: Effect.fn(\"hot-storage.append-with-check\")(\n function* (\n documentId: string,\n entry: WalEntry,\n expectedVersion: number,\n baseVersion?: number\n ) {\n type CheckResult =\n | { type: \"ok\" }\n | { type: \"gap\"; lastVersion: number | undefined };\n\n // Use Ref.modify for atomic check + update\n const result: CheckResult = yield* Ref.modify(\n store,\n (map): [CheckResult, HashMap.HashMap<string, WalEntry[]>] => {\n const existing = HashMap.get(map, documentId);\n const entries =\n existing._tag === \"Some\" ? existing.value : [];\n\n // Find the highest version in existing entries\n const lastEntryVersion =\n entries.length > 0\n ? Math.max(...entries.map((e) => e.version))\n : 0;\n\n // Effective \"last version\" is max of entries and baseVersion\n // This handles the case after truncation or restart where\n // WAL is empty but we know the snapshot version\n const effectiveLastVersion =\n baseVersion !== undefined\n ? Math.max(lastEntryVersion, baseVersion)\n : lastEntryVersion;\n\n // Gap check\n if (expectedVersion === 1) {\n // First entry: should have no entries with version >= 1\n // and baseVersion should be 0 or undefined\n if (effectiveLastVersion >= 1) {\n return [{ type: \"gap\", lastVersion: effectiveLastVersion }, map];\n }\n } else {\n // Not first: effective last version should be expectedVersion - 1\n if (effectiveLastVersion !== expectedVersion - 1) {\n return [\n {\n type: \"gap\",\n lastVersion: effectiveLastVersion > 0 ? effectiveLastVersion : undefined,\n },\n map,\n ];\n }\n }\n\n // No gap: append and return success\n return [\n { type: \"ok\" },\n HashMap.set(map, documentId, [...entries, entry]),\n ];\n }\n );\n\n if (result.type === \"gap\") {\n return yield* Effect.fail(\n new WalVersionGapError({\n documentId,\n expectedVersion,\n actualPreviousVersion: result.lastVersion,\n })\n );\n }\n }\n ),\n\n getEntries: Effect.fn(\"hot-storage.get-entries\")(\n function* (documentId: string, sinceVersion: number) {\n const current = yield* Ref.get(store);\n const existing = HashMap.get(current, documentId);\n const entries =\n existing._tag === \"Some\" ? existing.value : [];\n return entries\n .filter((e) => e.version > sinceVersion)\n .sort((a, b) => a.version - b.version);\n }\n ),\n\n truncate: Effect.fn(\"hot-storage.truncate\")(\n function* (documentId: string, upToVersion: number) {\n yield* Ref.update(store, (map) => {\n const existing = HashMap.get(map, documentId);\n if (existing._tag === \"None\") {\n return map;\n }\n const filtered = existing.value.filter(\n (e) => e.version > upToVersion\n );\n return HashMap.set(map, documentId, filtered);\n });\n }\n ),\n };\n })()\n );\n}\n\n// =============================================================================\n// Re-export namespace\n// =============================================================================\n\nexport const HotStorage = {\n Tag: HotStorageTag,\n make,\n InMemory,\n};\n"],"mappings":";;;;;;;;;;;;AAiFA,IAAa,gBAAb,cAAmC,QAAQ,IAAI,oCAAoC,EAGhF,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCJ,MAAa,QACX,WAEA,MAAM,OAAO,eAAe,OAAO;;;wBAiBjC,MAAM,OACJ,eACA,OAAO,GAAG,+BAA+B,CAAC,aAAa;EACrD,MAAM,QAAQ,OAAO,IAAI,KAAK,QAAQ,OAA2B,CAAC;AAElE,SAAO;GACL,QAAQ,OAAO,GAAG,qBAAqB,CACrC,WAAW,YAAoB,OAAiB;AAC9C,WAAO,IAAI,OAAO,QAAQ,QAAQ;KAChC,MAAM,WAAW,QAAQ,IAAI,KAAK,WAAW;KAC7C,MAAM,UACJ,SAAS,SAAS,SAAS,SAAS,QAAQ,EAAE;AAChD,YAAO,QAAQ,IAAI,KAAK,YAAY,CAAC,GAAG,SAAS,MAAM,CAAC;MACxD;KAEL;GAED,iBAAiB,OAAO,GAAG,gCAAgC,CACzD,WACE,YACA,OACA,iBACA,aACA;IAMA,MAAMA,SAAsB,OAAO,IAAI,OACrC,QACC,QAA4D;KAC3D,MAAM,WAAW,QAAQ,IAAI,KAAK,WAAW;KAC7C,MAAM,UACJ,SAAS,SAAS,SAAS,SAAS,QAAQ,EAAE;KAGhD,MAAM,mBACJ,QAAQ,SAAS,IACb,KAAK,IAAI,GAAG,QAAQ,KAAK,MAAM,EAAE,QAAQ,CAAC,GAC1C;KAKN,MAAM,uBACJ,gBAAgB,SACZ,KAAK,IAAI,kBAAkB,YAAY,GACvC;AAGN,SAAI,oBAAoB,GAGtB;UAAI,wBAAwB,EAC1B,QAAO,CAAC;OAAE,MAAM;OAAO,aAAa;OAAsB,EAAE,IAAI;gBAI9D,yBAAyB,kBAAkB,EAC7C,QAAO,CACL;MACE,MAAM;MACN,aAAa,uBAAuB,IAAI,uBAAuB;MAChE,EACD,IACD;AAKL,YAAO,CACL,EAAE,MAAM,MAAM,EACd,QAAQ,IAAI,KAAK,YAAY,CAAC,GAAG,SAAS,MAAM,CAAC,CAClD;MAEJ;AAED,QAAI,OAAO,SAAS,MAClB,QAAO,OAAO,OAAO,KACnB,IAAI,mBAAmB;KACrB;KACA;KACA,uBAAuB,OAAO;KAC/B,CAAC,CACH;KAGN;GAED,YAAY,OAAO,GAAG,0BAA0B,CAC9C,WAAW,YAAoB,cAAsB;IACnD,MAAM,UAAU,OAAO,IAAI,IAAI,MAAM;IACrC,MAAM,WAAW,QAAQ,IAAI,SAAS,WAAW;AAGjD,YADE,SAAS,SAAS,SAAS,SAAS,QAAQ,EAAE,EAE7C,QAAQ,MAAM,EAAE,UAAU,aAAa,CACvC,MAAM,GAAG,MAAM,EAAE,UAAU,EAAE,QAAQ;KAE3C;GAED,UAAU,OAAO,GAAG,uBAAuB,CACzC,WAAW,YAAoB,aAAqB;AAClD,WAAO,IAAI,OAAO,QAAQ,QAAQ;KAChC,MAAM,WAAW,QAAQ,IAAI,KAAK,WAAW;AAC7C,SAAI,SAAS,SAAS,OACpB,QAAO;KAET,MAAM,WAAW,SAAS,MAAM,QAC7B,MAAM,EAAE,UAAU,YACpB;AACD,YAAO,QAAQ,IAAI,KAAK,YAAY,SAAS;MAC7C;KAEL;GACF;GACD,EAAE,CACL;;AAOL,MAAa,aAAa;CACxB,KAAK;CACL;CACA;CACD"}
package/dist/MimicClusterServerEngine.cjs CHANGED
@@ -81,6 +81,7 @@ const MimicDocumentEntity = _effect_cluster.Entity.make("MimicDocument", [
81
81
  success: SubmitResultSchema
82
82
  }),
83
83
  _effect_rpc.Rpc.make("GetSnapshot", { success: SnapshotResponseSchema }),
84
+ _effect_rpc.Rpc.make("GetTreeSnapshot", { success: effect.Schema.Unknown }),
84
85
  _effect_rpc.Rpc.make("Touch", { success: effect.Schema.Void }),
85
86
  _effect_rpc.Rpc.make("SetPresence", {
86
87
  payload: {
@@ -175,6 +176,9 @@ const createEntityHandler = (config, coldStorage, hotStorage) => effect.Effect.f
175
176
  GetSnapshot: effect.Effect.fn("cluster.document.snapshot.get")(function* () {
176
177
  return instance.getSnapshot();
177
178
  }),
179
+ GetTreeSnapshot: effect.Effect.fn("cluster.document.tree-snapshot.get")(function* () {
180
+ return instance.toSnapshot();
181
+ }),
178
182
  Touch: effect.Effect.fn("cluster.document.touch")(function* () {
179
183
  yield* instance.touch();
180
184
  }),
@@ -302,6 +306,9 @@ const make = (config) => {
302
306
  getSnapshot: (documentId) => effect.Effect.gen(function* () {
303
307
  return yield* makeClient(documentId).GetSnapshot(void 0).pipe(effect.Effect.orDie);
304
308
  }),
309
+ getTreeSnapshot: (documentId) => effect.Effect.gen(function* () {
310
+ return yield* makeClient(documentId).GetTreeSnapshot(void 0).pipe(effect.Effect.orDie);
311
+ }),
305
312
  subscribe: (documentId) => effect.Effect.gen(function* () {
306
313
  const pubsub = yield* subscriptionStore.getOrCreatePubSub(documentId);
307
314
  return effect.Stream.fromPubSub(pubsub);
package/dist/MimicClusterServerEngine.d.cts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"MimicClusterServerEngine.d.cts","names":[],"sources":["../src/MimicClusterServerEngine.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;cA0pBa;yBA3JwB,SAAA,CAAU,sBACrC,+BAA+B,aACtC,KAAA,CAAM,MACP,6BAEA,iBAAiB,gBAAgB,sBAAsB,QAAA,CAAS"}
1
+ {"version":3,"file":"MimicClusterServerEngine.d.cts","names":[],"sources":["../src/MimicClusterServerEngine.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;cAyqBa;yBAjKwB,SAAA,CAAU,sBACrC,+BAA+B,aACtC,KAAA,CAAM,MACP,6BAEA,iBAAiB,gBAAgB,sBAAsB,QAAA,CAAS"}