@optimystic/db-core 1.21.0 → 1.23.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 (181) hide show
  1. package/README.md +8 -4
  2. package/dist/src/btree/btree.d.ts +36 -4
  3. package/dist/src/btree/btree.d.ts.map +1 -1
  4. package/dist/src/btree/btree.js +86 -18
  5. package/dist/src/btree/btree.js.map +1 -1
  6. package/dist/src/collection/action.d.ts +7 -4
  7. package/dist/src/collection/action.d.ts.map +1 -1
  8. package/dist/src/collection/action.js +13 -5
  9. package/dist/src/collection/action.js.map +1 -1
  10. package/dist/src/collection/collection.d.ts +177 -51
  11. package/dist/src/collection/collection.d.ts.map +1 -1
  12. package/dist/src/collection/collection.js +265 -81
  13. package/dist/src/collection/collection.js.map +1 -1
  14. package/dist/src/collection/struct.d.ts +44 -8
  15. package/dist/src/collection/struct.d.ts.map +1 -1
  16. package/dist/src/collection/struct.js.map +1 -1
  17. package/dist/src/collection/write-attempts.d.ts +138 -34
  18. package/dist/src/collection/write-attempts.d.ts.map +1 -1
  19. package/dist/src/collection/write-attempts.js +168 -101
  20. package/dist/src/collection/write-attempts.js.map +1 -1
  21. package/dist/src/collections/diary/diary.d.ts.map +1 -1
  22. package/dist/src/collections/diary/diary.js +5 -1
  23. package/dist/src/collections/diary/diary.js.map +1 -1
  24. package/dist/src/collections/tree/tree.d.ts +18 -10
  25. package/dist/src/collections/tree/tree.d.ts.map +1 -1
  26. package/dist/src/collections/tree/tree.js +17 -9
  27. package/dist/src/collections/tree/tree.js.map +1 -1
  28. package/dist/src/hlc/clock-store.d.ts +63 -0
  29. package/dist/src/hlc/clock-store.d.ts.map +1 -0
  30. package/dist/src/hlc/clock-store.js +49 -0
  31. package/dist/src/hlc/clock-store.js.map +1 -0
  32. package/dist/src/hlc/clock.d.ts +64 -0
  33. package/dist/src/hlc/clock.d.ts.map +1 -0
  34. package/dist/src/hlc/clock.js +171 -0
  35. package/dist/src/hlc/clock.js.map +1 -0
  36. package/dist/src/hlc/hlc.d.ts +38 -0
  37. package/dist/src/hlc/hlc.d.ts.map +1 -0
  38. package/dist/src/hlc/hlc.js +41 -0
  39. package/dist/src/hlc/hlc.js.map +1 -0
  40. package/dist/src/hlc/index.d.ts +5 -0
  41. package/dist/src/hlc/index.d.ts.map +1 -0
  42. package/dist/src/hlc/index.js +5 -0
  43. package/dist/src/hlc/index.js.map +1 -0
  44. package/dist/src/hlc/skew.d.ts +35 -0
  45. package/dist/src/hlc/skew.d.ts.map +1 -0
  46. package/dist/src/hlc/skew.js +35 -0
  47. package/dist/src/hlc/skew.js.map +1 -0
  48. package/dist/src/index.d.ts +2 -0
  49. package/dist/src/index.d.ts.map +1 -1
  50. package/dist/src/index.js +2 -0
  51. package/dist/src/index.js.map +1 -1
  52. package/dist/src/lane/index.d.ts +2 -0
  53. package/dist/src/lane/index.d.ts.map +1 -0
  54. package/dist/src/lane/index.js +2 -0
  55. package/dist/src/lane/index.js.map +1 -0
  56. package/dist/src/lane/lane.d.ts +46 -0
  57. package/dist/src/lane/lane.d.ts.map +1 -0
  58. package/dist/src/lane/lane.js +26 -0
  59. package/dist/src/lane/lane.js.map +1 -0
  60. package/dist/src/log/log.d.ts +50 -22
  61. package/dist/src/log/log.d.ts.map +1 -1
  62. package/dist/src/log/log.js +21 -13
  63. package/dist/src/log/log.js.map +1 -1
  64. package/dist/src/log/struct.d.ts +61 -1
  65. package/dist/src/log/struct.d.ts.map +1 -1
  66. package/dist/src/log/struct.js +24 -0
  67. package/dist/src/log/struct.js.map +1 -1
  68. package/dist/src/network/i-repo.d.ts +10 -0
  69. package/dist/src/network/i-repo.d.ts.map +1 -1
  70. package/dist/src/network/stale-failure.d.ts +20 -7
  71. package/dist/src/network/stale-failure.d.ts.map +1 -1
  72. package/dist/src/network/stale-failure.js +29 -7
  73. package/dist/src/network/stale-failure.js.map +1 -1
  74. package/dist/src/network/struct.d.ts +50 -0
  75. package/dist/src/network/struct.d.ts.map +1 -1
  76. package/dist/src/network/struct.js.map +1 -1
  77. package/dist/src/offline/entry.d.ts +14 -0
  78. package/dist/src/offline/entry.d.ts.map +1 -1
  79. package/dist/src/offline/entry.js +2 -0
  80. package/dist/src/offline/entry.js.map +1 -1
  81. package/dist/src/offline/journal.d.ts +10 -0
  82. package/dist/src/offline/journal.d.ts.map +1 -1
  83. package/dist/src/offline/queue.d.ts +10 -0
  84. package/dist/src/offline/queue.d.ts.map +1 -1
  85. package/dist/src/offline/queue.js +29 -3
  86. package/dist/src/offline/queue.js.map +1 -1
  87. package/dist/src/offline/status.d.ts +7 -0
  88. package/dist/src/offline/status.d.ts.map +1 -1
  89. package/dist/src/offline/status.js.map +1 -1
  90. package/dist/src/testing/test-transactor.d.ts +9 -1
  91. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  92. package/dist/src/testing/test-transactor.js +12 -3
  93. package/dist/src/testing/test-transactor.js.map +1 -1
  94. package/dist/src/transaction/actions-engine.d.ts +3 -0
  95. package/dist/src/transaction/actions-engine.d.ts.map +1 -1
  96. package/dist/src/transaction/actions-engine.js +3 -0
  97. package/dist/src/transaction/actions-engine.js.map +1 -1
  98. package/dist/src/transaction/coordinator.d.ts +16 -5
  99. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  100. package/dist/src/transaction/coordinator.js +203 -48
  101. package/dist/src/transaction/coordinator.js.map +1 -1
  102. package/dist/src/transaction/entry-commit.d.ts +45 -10
  103. package/dist/src/transaction/entry-commit.d.ts.map +1 -1
  104. package/dist/src/transaction/entry-commit.js +20 -7
  105. package/dist/src/transaction/entry-commit.js.map +1 -1
  106. package/dist/src/transaction/errors.d.ts +69 -1
  107. package/dist/src/transaction/errors.d.ts.map +1 -1
  108. package/dist/src/transaction/errors.js +70 -1
  109. package/dist/src/transaction/errors.js.map +1 -1
  110. package/dist/src/transaction/index.d.ts +1 -1
  111. package/dist/src/transaction/index.d.ts.map +1 -1
  112. package/dist/src/transaction/index.js +1 -1
  113. package/dist/src/transaction/index.js.map +1 -1
  114. package/dist/src/transaction/session.d.ts.map +1 -1
  115. package/dist/src/transaction/session.js +18 -5
  116. package/dist/src/transaction/session.js.map +1 -1
  117. package/dist/src/transaction/transaction.d.ts +74 -15
  118. package/dist/src/transaction/transaction.d.ts.map +1 -1
  119. package/dist/src/transaction/transaction.js +35 -15
  120. package/dist/src/transaction/transaction.js.map +1 -1
  121. package/dist/src/transaction/validator.d.ts +25 -4
  122. package/dist/src/transaction/validator.d.ts.map +1 -1
  123. package/dist/src/transaction/validator.js +45 -5
  124. package/dist/src/transaction/validator.js.map +1 -1
  125. package/dist/src/transactor/block-floors.d.ts +12 -1
  126. package/dist/src/transactor/block-floors.d.ts.map +1 -1
  127. package/dist/src/transactor/block-floors.js +14 -1
  128. package/dist/src/transactor/block-floors.js.map +1 -1
  129. package/dist/src/transactor/network-transactor.d.ts +8 -0
  130. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  131. package/dist/src/transactor/network-transactor.js +9 -4
  132. package/dist/src/transactor/network-transactor.js.map +1 -1
  133. package/dist/src/transactor/transactor-source.d.ts +11 -0
  134. package/dist/src/transactor/transactor-source.d.ts.map +1 -1
  135. package/dist/src/transactor/transactor-source.js +5 -1
  136. package/dist/src/transactor/transactor-source.js.map +1 -1
  137. package/dist/src/transactor/transactor.d.ts +8 -0
  138. package/dist/src/transactor/transactor.d.ts.map +1 -1
  139. package/dist/src/transform/cache-source.d.ts +7 -0
  140. package/dist/src/transform/cache-source.d.ts.map +1 -1
  141. package/dist/src/transform/cache-source.js +14 -18
  142. package/dist/src/transform/cache-source.js.map +1 -1
  143. package/package.json +1 -1
  144. package/src/btree/btree.ts +92 -18
  145. package/src/collection/action.ts +13 -5
  146. package/src/collection/collection.ts +3272 -3039
  147. package/src/collection/struct.ts +493 -456
  148. package/src/collection/write-attempts.ts +213 -109
  149. package/src/collections/diary/diary.ts +5 -1
  150. package/src/collections/tree/tree.ts +33 -18
  151. package/src/hlc/clock-store.ts +68 -0
  152. package/src/hlc/clock.ts +196 -0
  153. package/src/hlc/hlc.ts +56 -0
  154. package/src/hlc/index.ts +4 -0
  155. package/src/hlc/skew.ts +55 -0
  156. package/src/index.ts +2 -0
  157. package/src/lane/index.ts +1 -0
  158. package/src/lane/lane.ts +54 -0
  159. package/src/log/log.ts +341 -310
  160. package/src/log/struct.ts +62 -1
  161. package/src/network/i-repo.ts +11 -1
  162. package/src/network/stale-failure.ts +31 -7
  163. package/src/network/struct.ts +50 -0
  164. package/src/offline/entry.ts +16 -0
  165. package/src/offline/journal.ts +10 -0
  166. package/src/offline/queue.ts +38 -4
  167. package/src/offline/status.ts +7 -0
  168. package/src/testing/test-transactor.ts +1065 -1050
  169. package/src/transaction/actions-engine.ts +3 -0
  170. package/src/transaction/coordinator.ts +235 -54
  171. package/src/transaction/entry-commit.ts +56 -14
  172. package/src/transaction/errors.ts +60 -0
  173. package/src/transaction/index.ts +1 -1
  174. package/src/transaction/session.ts +18 -5
  175. package/src/transaction/transaction.ts +90 -17
  176. package/src/transaction/validator.ts +46 -5
  177. package/src/transactor/block-floors.ts +15 -1
  178. package/src/transactor/network-transactor.ts +1908 -1896
  179. package/src/transactor/transactor-source.ts +15 -1
  180. package/src/transactor/transactor.ts +9 -0
  181. package/src/transform/cache-source.ts +15 -17
@@ -4,6 +4,8 @@ import type { IBlock, BlockId, BlockHeader, ITransactor, ActionId, CommitResult,
4
4
  import { BlockUnavailableError, BlockPossiblyStaleError } from "../network/struct.js";
5
5
  import { withBlockRevs } from "../network/durability.js";
6
6
  import type { ReadDependency } from "../transaction/transaction.js";
7
+ import type { Hlc } from "../hlc/hlc.js";
8
+ import { laneField, type Lane } from "../lane/lane.js";
7
9
  import { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
8
10
  import { blockDigestsField, baseRevsField } from "../transform/digest.js";
9
11
  import { refuseSoloField } from "../network/refuse-solo.js";
@@ -30,6 +32,15 @@ export type TransactOptions = {
30
32
  /** Refuse to be committed by a lone coordinator that knows it is not alone
31
33
  * (`SyncOptions.refuseSoloCommit`): set on both the pend and the commit as `refuseSolo`. */
32
34
  readonly refuseSolo?: boolean;
35
+ /** The write's HLC (`WriteIdentity.hlc`), put on the pend (`PendRequest.hlc`) so a storage node
36
+ * observes it without parsing the log entry out of the transforms. Left off when the caller has
37
+ * none at hand — the re-send of a retained attempt, whose entry carries it inside the transforms. */
38
+ readonly hlc?: Hlc;
39
+ /** The write's lane (`WriteIdentity.lane`), put on the pend and the commit (`PendRequest.lane`,
40
+ * `CommitRequest.lane`) so a storage node reads it off either request. Every send of this build
41
+ * sets it, the re-send of a retained attempt included (`InFlightCycle.lane`); left off only by a
42
+ * caller that genuinely has none. */
43
+ readonly lane?: Lane;
33
44
  };
34
45
 
35
46
  /** The block `entry` answers for `id`, for a read at `context` (`undefined` for an unpinned "give me
@@ -250,10 +261,12 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
250
261
  * by comparing `quorum` (see {@link WriteDurability}).
251
262
  */
252
263
  async transact(transform: Transforms, actionId: ActionId, rev: number, headerId: BlockId, tailId: BlockId, options: TransactOptions = {}): Promise<CommitResult> {
253
- const { priority = 0, blockDigests, baseRevs, refuseSolo } = options;
264
+ const { priority = 0, blockDigests, baseRevs, refuseSolo, hlc, lane } = options;
254
265
  const pendResult = await this.transactor.pend({
255
266
  transforms: transform, actionId, rev, policy: 'r',
256
267
  ...(priority > 0 ? { priority } : {}),
268
+ ...(hlc === undefined ? {} : { hlc }),
269
+ ...laneField(lane),
257
270
  ...baseRevsField(baseRevs),
258
271
  // One collection, pended whole and then committed: the shape `PendRequest.soleReservation` names.
259
272
  soleReservation: true,
@@ -271,6 +284,7 @@ export class TransactorSource<TBlock extends IBlock> implements BlockSource<TBlo
271
284
  actionId,
272
285
  rev,
273
286
  ...blockDigestsField(blockDigests),
287
+ ...laneField(lane),
274
288
  ...refuseSoloField(refuseSolo)
275
289
  });
276
290
  if (!commitResult.success) {
@@ -1,5 +1,6 @@
1
1
  import type { GetBlockResults, ActionBlocks, ActionLineage, BlockActionStatus, PendResult, CommitResult, PendRequest, CommitRequest, BlockGets, BlockId } from "../index.js";
2
2
  import type { PeerId } from "../network/types.js";
3
+ import type { HlcClock } from "../hlc/clock.js";
3
4
 
4
5
  export type ClusterNomineesResult = {
5
6
  /** Peer IDs of the cluster members who can participate in consensus */
@@ -7,6 +8,14 @@ export type ClusterNomineesResult = {
7
8
  };
8
9
 
9
10
  export type ITransactor = {
11
+ /** The clock of the node this transactor runs on, which every write through it mints its HLC from.
12
+ - The transactor is the one node-scoped object every collection, coordinator and queue already
13
+ holds, so it carries the clock rather than an option threaded through each of them.
14
+ - Optional: a transactor that declares none gets the process-wide fallback, so a writer reads
15
+ it through `clockOf` rather than directly.
16
+ */
17
+ readonly clock?: HlcClock;
18
+
10
19
  /** Get blocks by their IDs and versions or a specific action
11
20
  - Does not update the version of the block, but the action is available for explicit reading, and for committing
12
21
  - If the action targets the correct version, the call succeeds, unless failIfPending and there are any pending actions - the caller may choose to wait for pending actions to clear rather than risk racing with them
@@ -301,27 +301,25 @@ export class CacheSource<T extends IBlock> implements BlockSource<T> {
301
301
  return this.source.createBlockHeader(type, newId);
302
302
  }
303
303
 
304
+ /** Forget `blockIds` — or, with none given, every id this cache holds or describes, an LRU-evicted
305
+ * id's lingering {@link revisions} entry included. Each forgotten id's generation moves, so a read
306
+ * of it already in flight is not kept when it lands ({@link stillWanted}), and a base pin or a
307
+ * materialized memo built on what was forgotten is re-judged. */
304
308
  clear(blockIds: BlockId[] | undefined = undefined) {
305
- if (blockIds) {
306
- for (const id of blockIds) {
307
- this.cache.delete(id);
308
- this.revisions.delete(id);
309
- this.unkept.delete(id);
310
- this.bump(id);
311
- }
312
- } else {
313
- for (const [id] of this.cache) {
314
- this.bump(id);
315
- }
316
- for (const id of this.unkept.keys()) {
317
- this.bump(id);
318
- }
319
- this.cache.clear();
320
- this.revisions.clear();
321
- this.unkept.clear();
309
+ for (const id of blockIds ?? this.describedIds()) {
310
+ this.cache.delete(id);
311
+ this.revisions.delete(id);
312
+ this.unkept.delete(id);
313
+ this.bump(id);
322
314
  }
323
315
  }
324
316
 
317
+ /** Every id this cache can say anything about: cached, evicted with its revision kept, or handed
318
+ * through unkept. */
319
+ private describedIds(): Set<BlockId> {
320
+ return new Set([...[...this.cache].map(([id]) => id), ...this.revisions.keys(), ...this.unkept.keys()]);
321
+ }
322
+
325
323
  /** A cloned copy of the current cache contents with each id's committed revision, in LRU
326
324
  * order (oldest first, so replaying into another LruMap preserves eviction order). For
327
325
  * building a pinned read view ONLY (see {@link Collection.createReadTracker}): pass the