@optimystic/db-core 1.5.0 → 1.5.1

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 (152) hide show
  1. package/README.md +336 -336
  2. package/dist/src/collection/collection.d.ts +44 -4
  3. package/dist/src/collection/collection.d.ts.map +1 -1
  4. package/dist/src/collection/collection.js +95 -14
  5. package/dist/src/collection/collection.js.map +1 -1
  6. package/dist/src/log/log.d.ts +41 -8
  7. package/dist/src/log/log.d.ts.map +1 -1
  8. package/dist/src/log/log.js +15 -10
  9. package/dist/src/log/log.js.map +1 -1
  10. package/dist/src/testing/test-transactor.d.ts +36 -0
  11. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  12. package/dist/src/testing/test-transactor.js +49 -0
  13. package/dist/src/testing/test-transactor.js.map +1 -1
  14. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  15. package/dist/src/transaction/coordinator.js +26 -9
  16. package/dist/src/transaction/coordinator.js.map +1 -1
  17. package/package.json +1 -1
  18. package/src/blocks/block-store.ts +31 -31
  19. package/src/blocks/block-types.ts +11 -11
  20. package/src/blocks/index.ts +5 -5
  21. package/src/blocks/structs.ts +17 -17
  22. package/src/btree/btree.ts +872 -872
  23. package/src/btree/independent-trunk.ts +53 -53
  24. package/src/btree/index.ts +5 -5
  25. package/src/btree/key-range.ts +15 -15
  26. package/src/btree/keyset.ts +6 -6
  27. package/src/btree/nodes.ts +25 -25
  28. package/src/btree/path.ts +37 -37
  29. package/src/btree/tree-block.ts +11 -11
  30. package/src/btree/trunk.ts +14 -14
  31. package/src/chain/chain-nodes.ts +26 -26
  32. package/src/chain/chain.ts +349 -349
  33. package/src/chain/index.ts +3 -3
  34. package/src/cluster/i-cluster.ts +6 -6
  35. package/src/cluster/index.ts +3 -3
  36. package/src/cohort-topic/addressing.ts +120 -120
  37. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  38. package/src/cohort-topic/antidos/index.ts +5 -5
  39. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  40. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  41. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  42. package/src/cohort-topic/antiflood/index.ts +2 -2
  43. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  44. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  45. package/src/cohort-topic/coldstart.ts +237 -237
  46. package/src/cohort-topic/dmax.ts +88 -88
  47. package/src/cohort-topic/gossip/bus.ts +254 -254
  48. package/src/cohort-topic/gossip/index.ts +3 -3
  49. package/src/cohort-topic/gossip/records.ts +45 -45
  50. package/src/cohort-topic/gossip/view.ts +91 -91
  51. package/src/cohort-topic/index.ts +20 -20
  52. package/src/cohort-topic/load/barometer.ts +134 -134
  53. package/src/cohort-topic/load/index.ts +1 -1
  54. package/src/cohort-topic/member-engine.ts +430 -430
  55. package/src/cohort-topic/membership/index.ts +3 -3
  56. package/src/cohort-topic/membership/publisher.ts +163 -163
  57. package/src/cohort-topic/membership/source.ts +41 -41
  58. package/src/cohort-topic/ports.ts +157 -157
  59. package/src/cohort-topic/promotion.ts +477 -477
  60. package/src/cohort-topic/registration/bytes.ts +37 -37
  61. package/src/cohort-topic/registration/handoff.ts +154 -154
  62. package/src/cohort-topic/registration/index.ts +6 -6
  63. package/src/cohort-topic/registration/renewal.ts +495 -495
  64. package/src/cohort-topic/registration/sharding.ts +61 -61
  65. package/src/cohort-topic/registration/store.ts +81 -81
  66. package/src/cohort-topic/registration/types.ts +91 -91
  67. package/src/cohort-topic/ring-hash.ts +50 -50
  68. package/src/cohort-topic/service.ts +416 -416
  69. package/src/cohort-topic/sig/index.ts +2 -2
  70. package/src/cohort-topic/sig/payloads.ts +59 -59
  71. package/src/cohort-topic/sig/threshold.ts +64 -64
  72. package/src/cohort-topic/tiers.ts +74 -74
  73. package/src/cohort-topic/traffic.ts +233 -233
  74. package/src/cohort-topic/walk.ts +326 -326
  75. package/src/cohort-topic/willingness.ts +237 -237
  76. package/src/cohort-topic/wire/index.ts +18 -18
  77. package/src/cohort-topic/wire/payloads.ts +126 -126
  78. package/src/collection/action.ts +48 -48
  79. package/src/collection/collection-type-registry.ts +37 -37
  80. package/src/collection/collection.ts +2203 -2118
  81. package/src/collection/index.ts +4 -4
  82. package/src/collections/diary/index.ts +2 -2
  83. package/src/collections/diary/struct.ts +3 -3
  84. package/src/collections/index.ts +2 -2
  85. package/src/collections/tree/collection-trunk.ts +25 -25
  86. package/src/collections/tree/index.ts +2 -2
  87. package/src/collections/tree/readme.md +55 -55
  88. package/src/log/index.ts +2 -2
  89. package/src/log/log.ts +304 -268
  90. package/src/log/struct.ts +165 -165
  91. package/src/matchmaking/capability-filter.ts +45 -45
  92. package/src/matchmaking/config.ts +98 -98
  93. package/src/matchmaking/index.ts +21 -21
  94. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  95. package/src/matchmaking/provider.ts +123 -123
  96. package/src/matchmaking/query-eval.ts +105 -105
  97. package/src/matchmaking/seeker-walk.ts +127 -127
  98. package/src/matchmaking/seeker.ts +86 -86
  99. package/src/matchmaking/topic-anchor.ts +90 -90
  100. package/src/matchmaking/voting-quorum.ts +394 -394
  101. package/src/network/i-peer-network.ts +25 -25
  102. package/src/network/repo-protocol.ts +13 -13
  103. package/src/network/types.ts +37 -37
  104. package/src/reactivity/backfill.ts +220 -220
  105. package/src/reactivity/backpressure.ts +191 -191
  106. package/src/reactivity/checkpoint.ts +308 -308
  107. package/src/reactivity/config.ts +172 -172
  108. package/src/reactivity/dedupe.ts +132 -132
  109. package/src/reactivity/forwarder.ts +87 -87
  110. package/src/reactivity/index.ts +34 -34
  111. package/src/reactivity/notification.ts +123 -123
  112. package/src/reactivity/policy.ts +79 -79
  113. package/src/reactivity/push-state.ts +310 -310
  114. package/src/reactivity/recover.ts +153 -153
  115. package/src/reactivity/replay-buffer.ts +141 -141
  116. package/src/reactivity/resume.ts +549 -549
  117. package/src/reactivity/rotation.ts +415 -415
  118. package/src/reactivity/subscriber.ts +132 -132
  119. package/src/reactivity/subscription.ts +66 -66
  120. package/src/reactivity/topic-anchor.ts +71 -71
  121. package/src/reactivity/verify.ts +73 -73
  122. package/src/reactivity/wire-validate.ts +13 -13
  123. package/src/testing/async-wait.ts +65 -65
  124. package/src/testing/index.ts +2 -2
  125. package/src/testing/test-transactor.ts +62 -0
  126. package/src/transaction/actions-engine.ts +68 -68
  127. package/src/transaction/coordinator.ts +28 -11
  128. package/src/transaction/index.ts +52 -52
  129. package/src/transaction/operations-hash.ts +196 -196
  130. package/src/transaction/read-dependency-collector.ts +78 -78
  131. package/src/transaction/session.ts +238 -238
  132. package/src/transaction/transaction.ts +442 -442
  133. package/src/transaction/validator.ts +197 -197
  134. package/src/transactor/block-floors.ts +126 -126
  135. package/src/transactor/index.ts +6 -6
  136. package/src/transactor/network-transactor.ts +1545 -1545
  137. package/src/transform/atomic-proxy.ts +92 -92
  138. package/src/transform/cache-source.ts +370 -370
  139. package/src/transform/helpers.ts +164 -164
  140. package/src/transform/index.ts +7 -7
  141. package/src/transform/struct.ts +21 -21
  142. package/src/utility/actor.ts +62 -62
  143. package/src/utility/backoff.ts +95 -95
  144. package/src/utility/batch-coordinator.ts +191 -191
  145. package/src/utility/ensured.ts +32 -32
  146. package/src/utility/groupby.ts +18 -18
  147. package/src/utility/hash-string.ts +14 -14
  148. package/src/utility/is-record-empty.ts +5 -5
  149. package/src/utility/latches.ts +42 -42
  150. package/src/utility/lru-map.ts +60 -60
  151. package/src/utility/nameof.ts +7 -7
  152. 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
+ }