@optimystic/db-core 1.5.0 → 1.6.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 (157) hide show
  1. package/README.md +336 -336
  2. package/dist/src/cluster/structs.d.ts +37 -0
  3. package/dist/src/cluster/structs.d.ts.map +1 -1
  4. package/dist/src/cluster/structs.js +13 -0
  5. package/dist/src/cluster/structs.js.map +1 -1
  6. package/dist/src/collection/collection.d.ts +44 -4
  7. package/dist/src/collection/collection.d.ts.map +1 -1
  8. package/dist/src/collection/collection.js +95 -14
  9. package/dist/src/collection/collection.js.map +1 -1
  10. package/dist/src/log/log.d.ts +41 -8
  11. package/dist/src/log/log.d.ts.map +1 -1
  12. package/dist/src/log/log.js +15 -10
  13. package/dist/src/log/log.js.map +1 -1
  14. package/dist/src/testing/test-transactor.d.ts +36 -0
  15. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  16. package/dist/src/testing/test-transactor.js +49 -0
  17. package/dist/src/testing/test-transactor.js.map +1 -1
  18. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  19. package/dist/src/transaction/coordinator.js +26 -9
  20. package/dist/src/transaction/coordinator.js.map +1 -1
  21. package/package.json +1 -1
  22. package/src/blocks/block-store.ts +31 -31
  23. package/src/blocks/block-types.ts +11 -11
  24. package/src/blocks/index.ts +5 -5
  25. package/src/blocks/structs.ts +17 -17
  26. package/src/btree/btree.ts +872 -872
  27. package/src/btree/independent-trunk.ts +53 -53
  28. package/src/btree/index.ts +5 -5
  29. package/src/btree/key-range.ts +15 -15
  30. package/src/btree/keyset.ts +6 -6
  31. package/src/btree/nodes.ts +25 -25
  32. package/src/btree/path.ts +37 -37
  33. package/src/btree/tree-block.ts +11 -11
  34. package/src/btree/trunk.ts +14 -14
  35. package/src/chain/chain-nodes.ts +26 -26
  36. package/src/chain/chain.ts +349 -349
  37. package/src/chain/index.ts +3 -3
  38. package/src/cluster/i-cluster.ts +6 -6
  39. package/src/cluster/index.ts +3 -3
  40. package/src/cluster/structs.ts +38 -0
  41. package/src/cohort-topic/addressing.ts +120 -120
  42. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  43. package/src/cohort-topic/antidos/index.ts +5 -5
  44. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  45. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  46. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  47. package/src/cohort-topic/antiflood/index.ts +2 -2
  48. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  49. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  50. package/src/cohort-topic/coldstart.ts +237 -237
  51. package/src/cohort-topic/dmax.ts +88 -88
  52. package/src/cohort-topic/gossip/bus.ts +254 -254
  53. package/src/cohort-topic/gossip/index.ts +3 -3
  54. package/src/cohort-topic/gossip/records.ts +45 -45
  55. package/src/cohort-topic/gossip/view.ts +91 -91
  56. package/src/cohort-topic/index.ts +20 -20
  57. package/src/cohort-topic/load/barometer.ts +134 -134
  58. package/src/cohort-topic/load/index.ts +1 -1
  59. package/src/cohort-topic/member-engine.ts +430 -430
  60. package/src/cohort-topic/membership/index.ts +3 -3
  61. package/src/cohort-topic/membership/publisher.ts +163 -163
  62. package/src/cohort-topic/membership/source.ts +41 -41
  63. package/src/cohort-topic/ports.ts +157 -157
  64. package/src/cohort-topic/promotion.ts +477 -477
  65. package/src/cohort-topic/registration/bytes.ts +37 -37
  66. package/src/cohort-topic/registration/handoff.ts +154 -154
  67. package/src/cohort-topic/registration/index.ts +6 -6
  68. package/src/cohort-topic/registration/renewal.ts +495 -495
  69. package/src/cohort-topic/registration/sharding.ts +61 -61
  70. package/src/cohort-topic/registration/store.ts +81 -81
  71. package/src/cohort-topic/registration/types.ts +91 -91
  72. package/src/cohort-topic/ring-hash.ts +50 -50
  73. package/src/cohort-topic/service.ts +416 -416
  74. package/src/cohort-topic/sig/index.ts +2 -2
  75. package/src/cohort-topic/sig/payloads.ts +59 -59
  76. package/src/cohort-topic/sig/threshold.ts +64 -64
  77. package/src/cohort-topic/tiers.ts +74 -74
  78. package/src/cohort-topic/traffic.ts +233 -233
  79. package/src/cohort-topic/walk.ts +326 -326
  80. package/src/cohort-topic/willingness.ts +237 -237
  81. package/src/cohort-topic/wire/index.ts +18 -18
  82. package/src/cohort-topic/wire/payloads.ts +126 -126
  83. package/src/collection/action.ts +48 -48
  84. package/src/collection/collection-type-registry.ts +37 -37
  85. package/src/collection/collection.ts +2203 -2118
  86. package/src/collection/index.ts +4 -4
  87. package/src/collections/diary/index.ts +2 -2
  88. package/src/collections/diary/struct.ts +3 -3
  89. package/src/collections/index.ts +2 -2
  90. package/src/collections/tree/collection-trunk.ts +25 -25
  91. package/src/collections/tree/index.ts +2 -2
  92. package/src/collections/tree/readme.md +55 -55
  93. package/src/log/index.ts +2 -2
  94. package/src/log/log.ts +304 -268
  95. package/src/log/struct.ts +165 -165
  96. package/src/matchmaking/capability-filter.ts +45 -45
  97. package/src/matchmaking/config.ts +98 -98
  98. package/src/matchmaking/index.ts +21 -21
  99. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  100. package/src/matchmaking/provider.ts +123 -123
  101. package/src/matchmaking/query-eval.ts +105 -105
  102. package/src/matchmaking/seeker-walk.ts +127 -127
  103. package/src/matchmaking/seeker.ts +86 -86
  104. package/src/matchmaking/topic-anchor.ts +90 -90
  105. package/src/matchmaking/voting-quorum.ts +394 -394
  106. package/src/network/i-peer-network.ts +25 -25
  107. package/src/network/repo-protocol.ts +13 -13
  108. package/src/network/types.ts +37 -37
  109. package/src/reactivity/backfill.ts +220 -220
  110. package/src/reactivity/backpressure.ts +191 -191
  111. package/src/reactivity/checkpoint.ts +308 -308
  112. package/src/reactivity/config.ts +172 -172
  113. package/src/reactivity/dedupe.ts +132 -132
  114. package/src/reactivity/forwarder.ts +87 -87
  115. package/src/reactivity/index.ts +34 -34
  116. package/src/reactivity/notification.ts +123 -123
  117. package/src/reactivity/policy.ts +79 -79
  118. package/src/reactivity/push-state.ts +310 -310
  119. package/src/reactivity/recover.ts +153 -153
  120. package/src/reactivity/replay-buffer.ts +141 -141
  121. package/src/reactivity/resume.ts +549 -549
  122. package/src/reactivity/rotation.ts +415 -415
  123. package/src/reactivity/subscriber.ts +132 -132
  124. package/src/reactivity/subscription.ts +66 -66
  125. package/src/reactivity/topic-anchor.ts +71 -71
  126. package/src/reactivity/verify.ts +73 -73
  127. package/src/reactivity/wire-validate.ts +13 -13
  128. package/src/testing/async-wait.ts +65 -65
  129. package/src/testing/index.ts +2 -2
  130. package/src/testing/test-transactor.ts +62 -0
  131. package/src/transaction/actions-engine.ts +68 -68
  132. package/src/transaction/coordinator.ts +28 -11
  133. package/src/transaction/index.ts +52 -52
  134. package/src/transaction/operations-hash.ts +196 -196
  135. package/src/transaction/read-dependency-collector.ts +78 -78
  136. package/src/transaction/session.ts +238 -238
  137. package/src/transaction/transaction.ts +442 -442
  138. package/src/transaction/validator.ts +197 -197
  139. package/src/transactor/block-floors.ts +126 -126
  140. package/src/transactor/index.ts +6 -6
  141. package/src/transactor/network-transactor.ts +1545 -1545
  142. package/src/transform/atomic-proxy.ts +92 -92
  143. package/src/transform/cache-source.ts +370 -370
  144. package/src/transform/helpers.ts +164 -164
  145. package/src/transform/index.ts +7 -7
  146. package/src/transform/struct.ts +21 -21
  147. package/src/utility/actor.ts +62 -62
  148. package/src/utility/backoff.ts +95 -95
  149. package/src/utility/batch-coordinator.ts +191 -191
  150. package/src/utility/ensured.ts +32 -32
  151. package/src/utility/groupby.ts +18 -18
  152. package/src/utility/hash-string.ts +14 -14
  153. package/src/utility/is-record-empty.ts +5 -5
  154. package/src/utility/latches.ts +42 -42
  155. package/src/utility/lru-map.ts +60 -60
  156. package/src/utility/nameof.ts +7 -7
  157. package/src/utility/pending.ts +43 -43
@@ -1,126 +1,126 @@
1
- /**
2
- * Cohort-topic substrate — canonical participant-signature payloads.
3
- *
4
- * A participant peer-key-signs its outbound `RegisterV1` / `RenewV1` bodies (db-p2p supplies the
5
- * libp2p peer key); a cohort member recomputes the identical byte image to verify that signature
6
- * before admitting a register (anti-DoS) or honoring a crash-failover `reattach` attestation (so a
7
- * stray/MITM'd ping cannot usurp a live primary — `docs/cohort-topic.md` §TTL and renewal).
8
- *
9
- * Signer and verifier must agree byte-for-byte. Exactly like {@link import("../sig/payloads.js")}
10
- * for the threshold-signed notices, determinism comes from encoding an explicitly-ordered JSON
11
- * array (array order is stable, unlike object key order) as UTF-8 — never the `signature` envelope.
12
- * Optional fields are normalized to a fixed placeholder (`bootstrap`→`false`, `probe`→`false`,
13
- * `followOn`→`false`, `appPayload`→`null`, `bootstrapEvidence`→`null` with an empty string treated as
14
- * absent, `reattach`→`false`, `withdraw`→`false`) so an absent optional and a present-but-default
15
- * optional can never disagree across the wire round-trip.
16
- */
17
-
18
- import type { CohortGossipV1, RegisterV1, RenewV1 } from "./types.js";
19
-
20
- const utf8 = new TextEncoder();
21
-
22
- /** A `RegisterV1` minus its `signature` envelope — the bytes the participant peer-key-signs. */
23
- export type RegisterSignable = Omit<RegisterV1, "signature">;
24
-
25
- /** A `RenewV1` minus its `signature` envelope — the bytes the participant peer-key-signs. */
26
- export type RenewSignable = Omit<RenewV1, "signature">;
27
-
28
- /** Normalize the optional bootstrap-evidence slot: absent and empty-string both map to `null`. */
29
- function normalizeEvidence(bootstrapEvidence: string | undefined): string | null {
30
- return bootstrapEvidence === undefined || bootstrapEvidence === "" ? null : bootstrapEvidence;
31
- }
32
-
33
- /** Canonical signed byte image of a `RegisterV1` body (every field except `signature`). */
34
- export function registerSigningPayload(body: RegisterSignable): Uint8Array {
35
- return utf8.encode(JSON.stringify([
36
- "RegisterV1",
37
- body.v,
38
- body.topicId,
39
- body.tier,
40
- body.treeTier,
41
- body.participantCoord,
42
- body.ttl,
43
- body.bootstrap ?? false,
44
- body.appPayload ?? null,
45
- normalizeEvidence(body.bootstrapEvidence),
46
- body.timestamp,
47
- body.correlationId,
48
- // A read-only probe signs `probe: true`; a normal register signs `false`. Both sides recompute
49
- // this image identically, so a probe and a register over the same fields produce distinct signatures.
50
- body.probe ?? false,
51
- // A follow-on cold-start re-issue signs `followOn: true`, everything else `false`. Strictly appended
52
- // (sibling to `probe`/`withdraw`) so a MITM cannot strip or flip the follow-on assertion and the
53
- // signer (participant) + verifier (db-p2p cohort) agree byte-for-byte. Safe to append: no register
54
- // signatures are persisted (each is recomputed per verify), so there is no cross-version image concern.
55
- body.followOn ?? false,
56
- ]));
57
- }
58
-
59
- /** Canonical signed byte image of a `RenewV1` body (every field except `signature`). */
60
- export function renewSigningPayload(body: RenewSignable): Uint8Array {
61
- return utf8.encode(JSON.stringify([
62
- "RenewV1",
63
- body.v,
64
- body.topicId,
65
- body.participantId,
66
- body.correlationId,
67
- body.timestamp,
68
- body.reattach ?? false,
69
- // A withdraw tombstone signs `withdraw: true`, a ping/reattach signs `false`. Strictly appended
70
- // (array length 7→8) so the reattach-vs-ping distinction is preserved and a third party cannot
71
- // evict someone else's registration. Signer (participant) + verifier (db-p2p) move together; no
72
- // signatures are persisted, so there is no cross-version concern.
73
- body.withdraw ?? false,
74
- ]));
75
- }
76
-
77
- /** A `CohortGossipV1` minus its `signature` envelope — the bytes the gossiping member peer-key-signs. */
78
- export type CohortGossipSignable = Omit<CohortGossipV1, "signature">;
79
-
80
- /**
81
- * Canonical signed byte image of a `CohortGossipV1` (every field except `signature`). Intra-cohort
82
- * gossip is peer-key-signed by the originating member so a receiver can drop a frame whose `fromMember`
83
- * signature does not verify or that comes from a non-cohort member (it can never spoof willingness/load
84
- * or replicate forged records). Like the other payload helpers, determinism comes from an
85
- * explicitly-ordered array — nested records/summaries/evictions are emitted as fixed ordered tuples so
86
- * the signer and the receiver (which re-derives this image from the validated frame) agree byte-for-byte.
87
- * Absent optionals (`records`/`evicted`/`childLinks`/`childUnlinks`) normalize to `[]`, and `appState` to
88
- * `null`. `childLinks`/`childUnlinks` are covered so a MITM cannot strip or inject a child link/unlink.
89
- */
90
- export function cohortGossipSigningPayload(g: CohortGossipSignable): Uint8Array {
91
- return utf8.encode(JSON.stringify([
92
- "CohortGossipV1",
93
- g.v,
94
- g.fromMember,
95
- g.coord,
96
- g.cohortEpoch,
97
- g.treeTier,
98
- g.willingnessBits,
99
- g.loadBuckets,
100
- g.windowSeconds,
101
- g.topicSummaries.map((s) => [
102
- s.topicId,
103
- s.tier,
104
- s.directParticipants,
105
- s.arrivalsPerMin,
106
- s.queriesPerMin,
107
- s.promoted,
108
- s.childCohortCount,
109
- ]),
110
- (g.records ?? []).map((r) => [
111
- r.topicId,
112
- r.participantId,
113
- r.tier,
114
- r.primary,
115
- r.backups,
116
- r.attachedAt,
117
- r.lastPing,
118
- r.ttl,
119
- r.appState ?? null,
120
- ]),
121
- (g.evicted ?? []).map((e) => [e.topicId, e.participantId, e.lastPing]),
122
- (g.childLinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
123
- (g.childUnlinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
124
- g.timestamp,
125
- ]));
126
- }
1
+ /**
2
+ * Cohort-topic substrate — canonical participant-signature payloads.
3
+ *
4
+ * A participant peer-key-signs its outbound `RegisterV1` / `RenewV1` bodies (db-p2p supplies the
5
+ * libp2p peer key); a cohort member recomputes the identical byte image to verify that signature
6
+ * before admitting a register (anti-DoS) or honoring a crash-failover `reattach` attestation (so a
7
+ * stray/MITM'd ping cannot usurp a live primary — `docs/cohort-topic.md` §TTL and renewal).
8
+ *
9
+ * Signer and verifier must agree byte-for-byte. Exactly like {@link import("../sig/payloads.js")}
10
+ * for the threshold-signed notices, determinism comes from encoding an explicitly-ordered JSON
11
+ * array (array order is stable, unlike object key order) as UTF-8 — never the `signature` envelope.
12
+ * Optional fields are normalized to a fixed placeholder (`bootstrap`→`false`, `probe`→`false`,
13
+ * `followOn`→`false`, `appPayload`→`null`, `bootstrapEvidence`→`null` with an empty string treated as
14
+ * absent, `reattach`→`false`, `withdraw`→`false`) so an absent optional and a present-but-default
15
+ * optional can never disagree across the wire round-trip.
16
+ */
17
+
18
+ import type { CohortGossipV1, RegisterV1, RenewV1 } from "./types.js";
19
+
20
+ const utf8 = new TextEncoder();
21
+
22
+ /** A `RegisterV1` minus its `signature` envelope — the bytes the participant peer-key-signs. */
23
+ export type RegisterSignable = Omit<RegisterV1, "signature">;
24
+
25
+ /** A `RenewV1` minus its `signature` envelope — the bytes the participant peer-key-signs. */
26
+ export type RenewSignable = Omit<RenewV1, "signature">;
27
+
28
+ /** Normalize the optional bootstrap-evidence slot: absent and empty-string both map to `null`. */
29
+ function normalizeEvidence(bootstrapEvidence: string | undefined): string | null {
30
+ return bootstrapEvidence === undefined || bootstrapEvidence === "" ? null : bootstrapEvidence;
31
+ }
32
+
33
+ /** Canonical signed byte image of a `RegisterV1` body (every field except `signature`). */
34
+ export function registerSigningPayload(body: RegisterSignable): Uint8Array {
35
+ return utf8.encode(JSON.stringify([
36
+ "RegisterV1",
37
+ body.v,
38
+ body.topicId,
39
+ body.tier,
40
+ body.treeTier,
41
+ body.participantCoord,
42
+ body.ttl,
43
+ body.bootstrap ?? false,
44
+ body.appPayload ?? null,
45
+ normalizeEvidence(body.bootstrapEvidence),
46
+ body.timestamp,
47
+ body.correlationId,
48
+ // A read-only probe signs `probe: true`; a normal register signs `false`. Both sides recompute
49
+ // this image identically, so a probe and a register over the same fields produce distinct signatures.
50
+ body.probe ?? false,
51
+ // A follow-on cold-start re-issue signs `followOn: true`, everything else `false`. Strictly appended
52
+ // (sibling to `probe`/`withdraw`) so a MITM cannot strip or flip the follow-on assertion and the
53
+ // signer (participant) + verifier (db-p2p cohort) agree byte-for-byte. Safe to append: no register
54
+ // signatures are persisted (each is recomputed per verify), so there is no cross-version image concern.
55
+ body.followOn ?? false,
56
+ ]));
57
+ }
58
+
59
+ /** Canonical signed byte image of a `RenewV1` body (every field except `signature`). */
60
+ export function renewSigningPayload(body: RenewSignable): Uint8Array {
61
+ return utf8.encode(JSON.stringify([
62
+ "RenewV1",
63
+ body.v,
64
+ body.topicId,
65
+ body.participantId,
66
+ body.correlationId,
67
+ body.timestamp,
68
+ body.reattach ?? false,
69
+ // A withdraw tombstone signs `withdraw: true`, a ping/reattach signs `false`. Strictly appended
70
+ // (array length 7→8) so the reattach-vs-ping distinction is preserved and a third party cannot
71
+ // evict someone else's registration. Signer (participant) + verifier (db-p2p) move together; no
72
+ // signatures are persisted, so there is no cross-version concern.
73
+ body.withdraw ?? false,
74
+ ]));
75
+ }
76
+
77
+ /** A `CohortGossipV1` minus its `signature` envelope — the bytes the gossiping member peer-key-signs. */
78
+ export type CohortGossipSignable = Omit<CohortGossipV1, "signature">;
79
+
80
+ /**
81
+ * Canonical signed byte image of a `CohortGossipV1` (every field except `signature`). Intra-cohort
82
+ * gossip is peer-key-signed by the originating member so a receiver can drop a frame whose `fromMember`
83
+ * signature does not verify or that comes from a non-cohort member (it can never spoof willingness/load
84
+ * or replicate forged records). Like the other payload helpers, determinism comes from an
85
+ * explicitly-ordered array — nested records/summaries/evictions are emitted as fixed ordered tuples so
86
+ * the signer and the receiver (which re-derives this image from the validated frame) agree byte-for-byte.
87
+ * Absent optionals (`records`/`evicted`/`childLinks`/`childUnlinks`) normalize to `[]`, and `appState` to
88
+ * `null`. `childLinks`/`childUnlinks` are covered so a MITM cannot strip or inject a child link/unlink.
89
+ */
90
+ export function cohortGossipSigningPayload(g: CohortGossipSignable): Uint8Array {
91
+ return utf8.encode(JSON.stringify([
92
+ "CohortGossipV1",
93
+ g.v,
94
+ g.fromMember,
95
+ g.coord,
96
+ g.cohortEpoch,
97
+ g.treeTier,
98
+ g.willingnessBits,
99
+ g.loadBuckets,
100
+ g.windowSeconds,
101
+ g.topicSummaries.map((s) => [
102
+ s.topicId,
103
+ s.tier,
104
+ s.directParticipants,
105
+ s.arrivalsPerMin,
106
+ s.queriesPerMin,
107
+ s.promoted,
108
+ s.childCohortCount,
109
+ ]),
110
+ (g.records ?? []).map((r) => [
111
+ r.topicId,
112
+ r.participantId,
113
+ r.tier,
114
+ r.primary,
115
+ r.backups,
116
+ r.attachedAt,
117
+ r.lastPing,
118
+ r.ttl,
119
+ r.appState ?? null,
120
+ ]),
121
+ (g.evicted ?? []).map((e) => [e.topicId, e.participantId, e.lastPing]),
122
+ (g.childLinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
123
+ (g.childUnlinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
124
+ g.timestamp,
125
+ ]));
126
+ }
@@ -1,48 +1,48 @@
1
- import type { BlockStore } from "../index.js";
2
- import type { IBlock } from "../index.js";
3
- import type { TransactionRef } from "../transaction/index.js";
4
-
5
- export type ActionId = string;
6
-
7
- export type ActionType = string;
8
-
9
- export type Action<T> = {
10
- type: ActionType;
11
- data: T;
12
- /** Optional reference to the transaction this action came from */
13
- transaction?: TransactionRef;
14
- };
15
-
16
- export type ActionHandler<T, TResult = void> = (action: Action<T>, store: BlockStore<IBlock>) => Promise<TResult>;
17
-
18
- export type ActionRev = {
19
- actionId: ActionId;
20
- rev: number;
21
- };
22
-
23
- /** Situational awareness of the action state */
24
- export type ActionContext = {
25
- /** Actions that may not have been checkpointed */
26
- committed: ActionRev[];
27
- /** The latest known revision number */
28
- rev: number;
29
- /** Optional uncommitted pending action ID */
30
- actionId?: ActionId;
31
- };
32
-
33
- /** The id of the action that produced `rev` within `context`'s uncheckpointed committed list,
34
- * or `undefined` when the list names no action at that revision.
35
- *
36
- * `undefined` is legitimate, not an error, and has three causes: the revision's log slot belongs
37
- * to an entry that carries no action (a CHECKPOINT or an INVALIDATION entry takes a revision of
38
- * its own); `rev` predates the most recent checkpoint, which is as far back as a context read off
39
- * a log reaches (`Log.getActionContext`, `Log.getFrom`); or the context was never built from a
40
- * log at all. A caller printing this must carry a placeholder rather than invent an id.
41
- *
42
- * NOTE: linear in `committed`, which grows one entry per commit between context reads; fine now —
43
- * every caller is a `debug`-gated diagnostic, so this does not run on a normal path at all. If a
44
- * non-diagnostic caller ever appears, index the lookup or search from the end (the entry at the
45
- * context's own `rev` is normally the last one). */
46
- export function actionIdAt(context: ActionContext, rev: number): ActionId | undefined {
47
- return context.committed.find(entry => entry.rev === rev)?.actionId;
48
- }
1
+ import type { BlockStore } from "../index.js";
2
+ import type { IBlock } from "../index.js";
3
+ import type { TransactionRef } from "../transaction/index.js";
4
+
5
+ export type ActionId = string;
6
+
7
+ export type ActionType = string;
8
+
9
+ export type Action<T> = {
10
+ type: ActionType;
11
+ data: T;
12
+ /** Optional reference to the transaction this action came from */
13
+ transaction?: TransactionRef;
14
+ };
15
+
16
+ export type ActionHandler<T, TResult = void> = (action: Action<T>, store: BlockStore<IBlock>) => Promise<TResult>;
17
+
18
+ export type ActionRev = {
19
+ actionId: ActionId;
20
+ rev: number;
21
+ };
22
+
23
+ /** Situational awareness of the action state */
24
+ export type ActionContext = {
25
+ /** Actions that may not have been checkpointed */
26
+ committed: ActionRev[];
27
+ /** The latest known revision number */
28
+ rev: number;
29
+ /** Optional uncommitted pending action ID */
30
+ actionId?: ActionId;
31
+ };
32
+
33
+ /** The id of the action that produced `rev` within `context`'s uncheckpointed committed list,
34
+ * or `undefined` when the list names no action at that revision.
35
+ *
36
+ * `undefined` is legitimate, not an error, and has three causes: the revision's log slot belongs
37
+ * to an entry that carries no action (a CHECKPOINT or an INVALIDATION entry takes a revision of
38
+ * its own); `rev` predates the most recent checkpoint, which is as far back as a context read off
39
+ * a log reaches (`Log.getActionContext`, `Log.getFrom`); or the context was never built from a
40
+ * log at all. A caller printing this must carry a placeholder rather than invent an id.
41
+ *
42
+ * NOTE: linear in `committed`, which grows one entry per commit between context reads; fine now —
43
+ * every caller is a `debug`-gated diagnostic, so this does not run on a normal path at all. If a
44
+ * non-diagnostic caller ever appears, index the lookup or search from the end (the entry at the
45
+ * context's own `rev` is normally the last one). */
46
+ export function actionIdAt(context: ActionContext, rev: number): ActionId | undefined {
47
+ return context.committed.find(entry => entry.rev === rev)?.actionId;
48
+ }
@@ -1,37 +1,37 @@
1
- import type { BlockType } from "../blocks/index.js";
2
- import type { ITransactor } from "../transactor/index.js";
3
- import type { CollectionId, ICollection } from "./struct.js";
4
-
5
- export interface CollectionTypeDescriptor {
6
- /** The block type used for this collection's header block (e.g. "DIH", "TRE") */
7
- blockType: BlockType;
8
- /** Human-readable name (e.g. "Diary", "Tree") */
9
- name: string;
10
- /** Optional factory to open a collection with default settings, bringing it into existence
11
- * when nothing has ever been committed under the id (see {@link Collection.createOrOpen}).
12
- * Not all types support this (e.g. Tree requires keyFromEntry/compare). */
13
- createOrOpen?: (transactor: ITransactor, id: CollectionId) => Promise<ICollection<any>>;
14
- }
15
-
16
- const collectionTypes = new Map<BlockType, CollectionTypeDescriptor>();
17
-
18
- /** Register a collection type by its header block type. Throws if already registered. */
19
- export function registerCollectionType(descriptor: CollectionTypeDescriptor): void {
20
- if (collectionTypes.has(descriptor.blockType)) {
21
- throw new Error(
22
- `Collection type ${descriptor.blockType} (${descriptor.name}) already registered`
23
- + ` (${collectionTypes.get(descriptor.blockType)!.name})`
24
- );
25
- }
26
- collectionTypes.set(descriptor.blockType, descriptor);
27
- }
28
-
29
- /** Look up a collection type descriptor by its header block type. */
30
- export function getCollectionType(blockType: BlockType): CollectionTypeDescriptor | undefined {
31
- return collectionTypes.get(blockType);
32
- }
33
-
34
- /** Returns all registered collection type descriptors. */
35
- export function getCollectionTypes(): ReadonlyMap<BlockType, CollectionTypeDescriptor> {
36
- return collectionTypes;
37
- }
1
+ import type { BlockType } from "../blocks/index.js";
2
+ import type { ITransactor } from "../transactor/index.js";
3
+ import type { CollectionId, ICollection } from "./struct.js";
4
+
5
+ export interface CollectionTypeDescriptor {
6
+ /** The block type used for this collection's header block (e.g. "DIH", "TRE") */
7
+ blockType: BlockType;
8
+ /** Human-readable name (e.g. "Diary", "Tree") */
9
+ name: string;
10
+ /** Optional factory to open a collection with default settings, bringing it into existence
11
+ * when nothing has ever been committed under the id (see {@link Collection.createOrOpen}).
12
+ * Not all types support this (e.g. Tree requires keyFromEntry/compare). */
13
+ createOrOpen?: (transactor: ITransactor, id: CollectionId) => Promise<ICollection<any>>;
14
+ }
15
+
16
+ const collectionTypes = new Map<BlockType, CollectionTypeDescriptor>();
17
+
18
+ /** Register a collection type by its header block type. Throws if already registered. */
19
+ export function registerCollectionType(descriptor: CollectionTypeDescriptor): void {
20
+ if (collectionTypes.has(descriptor.blockType)) {
21
+ throw new Error(
22
+ `Collection type ${descriptor.blockType} (${descriptor.name}) already registered`
23
+ + ` (${collectionTypes.get(descriptor.blockType)!.name})`
24
+ );
25
+ }
26
+ collectionTypes.set(descriptor.blockType, descriptor);
27
+ }
28
+
29
+ /** Look up a collection type descriptor by its header block type. */
30
+ export function getCollectionType(blockType: BlockType): CollectionTypeDescriptor | undefined {
31
+ return collectionTypes.get(blockType);
32
+ }
33
+
34
+ /** Returns all registered collection type descriptors. */
35
+ export function getCollectionTypes(): ReadonlyMap<BlockType, CollectionTypeDescriptor> {
36
+ return collectionTypes;
37
+ }