@optimystic/db-core 1.3.0 → 1.5.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.
@@ -125,7 +125,9 @@ export type TreeReplaceAction<TKey, TEntry> = (
125
125
  *
126
126
  * Subclasses split by WHAT was refused, because consumers map them differently: a
127
127
  * {@link TreeKeyTakenError} is a uniqueness violation (the Quereus bridge renders it as
128
- * `UNIQUE constraint failed`), while a {@link TreeEntryChangedError} is a lost update. Catch
128
+ * `UNIQUE constraint failed` and raises the engine's `ConstraintError`), while a
129
+ * {@link TreeEntryChangedError} is a lost update (the bridge raises its
130
+ * `ConcurrentModificationError`, status code BUSY, which is not a constraint error). Catch
129
131
  * this base to treat any guard refusal uniformly; catch a subclass to say which happened.
130
132
  */
131
133
  export class TreeGuardRefusedError<TKey = unknown> extends Error {
@@ -166,8 +168,9 @@ export class TreeKeyTakenError<TKey = unknown> extends TreeGuardRefusedError<TKe
166
168
  * index tree, a rival's row carrying the same unique value under a different primary
167
169
  * key. A subclass of {@link TreeKeyTakenError} on purpose: every consumer that treats a
168
170
  * key refusal as a non-retryable uniqueness failure (the sync/commit retry loops let it
169
- * escape; the Quereus bridge maps it by `collectionId` to a `UNIQUE constraint failed`
170
- * message) handles this one identically without a second arm. `collectionId` is the
171
+ * escape; the Quereus bridge maps it by `collectionId` to a `ConstraintError` carrying the
172
+ * `UNIQUE constraint failed` message) handles this one identically without a second arm.
173
+ * `collectionId` is the
171
174
  * discriminator that names WHICH constraint fired — each unique index is its own
172
175
  * collection — so the bridge needs nothing beyond it.
173
176
  */
@@ -193,9 +196,11 @@ export class TreeRangeTakenError<TKey = unknown> extends TreeKeyTakenError<TKey>
193
196
  * write read — a rival committed a different entry there, or removed it (`actual` is
194
197
  * `undefined`). A lost update, NOT a uniqueness violation, which is why this deliberately does
195
198
  * NOT subclass {@link TreeKeyTakenError}: the Quereus bridge renders every `TreeKeyTakenError`
196
- * as that collection's registered `UNIQUE constraint failed` message (`mapCommitRefusal` in
199
+ * as that collection's registered `UNIQUE constraint failed` message and raises the engine's
200
+ * `ConstraintError` for it (`mapCommitRefusal` in
197
201
  * `packages/quereus-plugin-optimystic/src/optimystic-adapter/txn-bridge.ts`), and reporting a
198
202
  * concurrent-update refusal as a uniqueness failure would mislead every client that reads it.
203
+ * The bridge raises its own `ConcurrentModificationError` (status code BUSY) for this one instead.
199
204
  * The shared contract lives on {@link TreeGuardRefusedError}.
200
205
  */
201
206
  export class TreeEntryChangedError<TKey = unknown, TEntry = unknown> extends TreeGuardRefusedError<TKey> {
@@ -1,105 +1,126 @@
1
- import type { ActionContext, ActionId, BlockId } from "../index.js";
2
-
3
- /** The lowest revision a block may be served at, and the action that set it.
4
- *
5
- * A refresh walks the log entries that landed since the collection last looked. Each entry says
6
- * "action `actionId`, committed at revision `rev`, changed these blocks", and every block an action
7
- * changes is committed at that action's revision. So once an entry has been walked, a read of a
8
- * block it names — made at a context at or above `rev` — must come back materialized at `rev` or
9
- * later; anything lower is provably not the view that was asked for. The FLOOR of a block is that
10
- * bound: the revision and action id of the newest walked entry naming it. */
11
- export type BlockFloor = {
12
- readonly rev: number;
13
- readonly actionId: ActionId;
14
- };
15
-
16
- /** A BELOW-FLOOR ANSWER: a block served at a revision under the floor that applied to the read. */
17
- export type BelowFloorAnswer = {
18
- blockId: BlockId;
19
- floor: BlockFloor;
20
- /** The revision the served content actually is (`servedRevision` of the answer). */
21
- servedRev: number;
22
- };
23
-
24
- /** What a read source needs from a collection's floors: which floor applies to a read, and whether
25
- * an answer fell under it. The narrow face of {@link BlockFloors} that `TransactorSource` holds. */
26
- export interface BlockFloorCheck {
27
- /** The floor a read of `blockId` at `context` must meet, or `undefined` when none applies.
28
- *
29
- * A floor applies only to a view that should CONTAIN the entry that set it: an unpinned read, or
30
- * one pinned at or above the floor's revision. A read pinned strictly below it legitimately asks
31
- * for an older view and is served — and remembered — exactly as if there were no floor. (The same
32
- * at-or-above test `answeredBlock` applies to `unconfirmedAheadRev`.) */
33
- applicableTo(blockId: BlockId, context: ActionContext | undefined): BlockFloor | undefined;
34
-
35
- /** Weighs a served block against the floor that applies to the read that fetched it.
36
- *
37
- * @param servedRev the revision the served content is — `servedRevision` of the answer.
38
- * @returns `true` for a below-floor answer, which the caller hands on but must not let any cache
39
- * remember (see `TransactorSource.describeServed`). */
40
- answeredBelowFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean;
41
- }
42
-
43
- /** The floors of one collection handle, shared by EVERY read source that handle builds — its own
44
- * and each pinned read view's — the way the `ReadDependencyCollector` is shared. Held on one
45
- * source only, a view created right after a refresh would fetch the changed block through a source
46
- * that knows no floor.
47
- *
48
- * Raised where log entries are consumed (`Collection.updateInternal`) and checked where answers
49
- * arrive (`TransactorSource.tryGet`). A floor, once raised, STANDS for the life of the handle: an
50
- * answer that meets it does not remove it.
51
- *
52
- * Why a met floor is not dropped. The source that judges an answer cannot know whether any cache
53
- * went on to keep it, and "an answer met the floor" is not "the cache now holds that answer": the
54
- * cache drops an answer that was overtaken while in flight (`CacheSource.stillWanted`), and evicts
55
- * kept content under pressure (128 blocks). Either way the next read of the block goes back to
56
- * storage, where nothing says the same machine answers twice — and with the floor gone, a too-old
57
- * answer to THAT read is judged against nothing and kept for good, which is the defect floors exist
58
- * to prevent. Reproduced with the floor dropped when met: a too-old answer, then a current one that
59
- * the cache dropped as overtaken (but which removed the floor), then a too-old one — kept, and
60
- * served after storage had caught up (`refresh-below-floor.spec.ts`, "a current answer the cache
61
- * dropped..."). A standing floor costs one map lookup per fetched block and is always true of a
62
- * correct answer: a block never goes back below a revision it was committed at.
63
- *
64
- * NOTE: the map is never pruned, so it holds one small entry per distinct block named by entries
65
- * this handle walked — the same ids, and so the same bound, as `CacheSource`'s never-pruned
66
- * `generations` map, which `clear(entry.blockIds)` populates beside every `raise`. If that ever
67
- * grows large enough to matter, prune the two together (oldest floors first); a dropped floor only
68
- * forfeits the check for that block, it never serves anything wrong by itself. */
69
- export class BlockFloors implements BlockFloorCheck {
70
- private readonly floors = new Map<BlockId, BlockFloor>();
71
-
72
- /** @param onBelowFloor told about every below-floor answer, from any source sharing these floors
73
- * — the collection reports them as `collection:block-below-floor`. */
74
- constructor(private readonly onBelowFloor?: (answer: BelowFloorAnswer) => void) {}
75
-
76
- /** Record that the walked entry `floor` describes changed `blockIds`. Highest revision wins, so
77
- * entries may be walked in any order and re-walked harmlessly. */
78
- raise(blockIds: readonly BlockId[], floor: BlockFloor): void {
79
- for (const blockId of blockIds) {
80
- const held = this.floors.get(blockId);
81
- if (held === undefined || floor.rev > held.rev) {
82
- this.floors.set(blockId, floor);
83
- }
84
- }
85
- }
86
-
87
- applicableTo(blockId: BlockId, context: ActionContext | undefined): BlockFloor | undefined {
88
- const floor = this.floors.get(blockId);
89
- return floor !== undefined && (context === undefined || context.rev >= floor.rev) ? floor : undefined;
90
- }
91
-
92
- answeredBelowFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean {
93
- const floor = this.applicableTo(blockId, context);
94
- if (floor === undefined || servedRev >= floor.rev) {
95
- return false;
96
- }
97
- this.onBelowFloor?.({ blockId, floor, servedRev });
98
- return true;
99
- }
100
-
101
- /** How many blocks have a floor. */
102
- get size(): number {
103
- return this.floors.size;
104
- }
105
- }
1
+ import type { ActionContext, ActionId, BlockId } from "../index.js";
2
+
3
+ /** The lowest revision a block may be served at, and the action that set it.
4
+ *
5
+ * A refresh walks the log entries that landed since the collection last looked. Each entry says
6
+ * "action `actionId`, committed at revision `rev`, changed these blocks", and every block an action
7
+ * changes is committed at that action's revision. So once an entry has been walked, a read of a
8
+ * block it names — made at a context at or above `rev` — must come back materialized at `rev` or
9
+ * later; anything lower is provably not the view that was asked for. The FLOOR of a block is that
10
+ * bound: the revision and action id of the newest walked entry naming it. */
11
+ export type BlockFloor = {
12
+ readonly rev: number;
13
+ readonly actionId: ActionId;
14
+ };
15
+
16
+ /** A BELOW-FLOOR ANSWER: a block served at a revision under the floor that applied to the read. */
17
+ export type BelowFloorAnswer = {
18
+ blockId: BlockId;
19
+ floor: BlockFloor;
20
+ /** The revision the served content actually is (`servedRevision` of the answer). */
21
+ servedRev: number;
22
+ };
23
+
24
+ /** What a read source needs from a collection's floors: which floor applies to a read, and whether
25
+ * an answer fell under it. The narrow face of {@link BlockFloors} that `TransactorSource` holds. */
26
+ export interface BlockFloorCheck {
27
+ /** The floor a read of `blockId` at `context` must meet, or `undefined` when none applies.
28
+ *
29
+ * A floor applies only to a view that should CONTAIN the entry that set it: an unpinned read, or
30
+ * one pinned at or above the floor's revision. A read pinned strictly below it legitimately asks
31
+ * for an older view and is served — and remembered — exactly as if there were no floor. (The same
32
+ * at-or-above test `answeredBlock` applies to `unconfirmedAheadRev`.) */
33
+ applicableTo(blockId: BlockId, context: ActionContext | undefined): BlockFloor | undefined;
34
+
35
+ /** Weighs a served block against the floor that applies to the read that fetched it.
36
+ *
37
+ * @param servedRev the revision the served content is — `servedRevision` of the answer.
38
+ * @returns `true` for a below-floor answer, which the caller hands on but must not let any cache
39
+ * remember (see `TransactorSource.describeServed`). */
40
+ answeredBelowFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean;
41
+
42
+ /** The same comparison {@link answeredBelowFloor} makes, without reporting it — for content that
43
+ * is not an answer being served to a reader, where the `collection:block-below-floor` line would
44
+ * misdescribe what happened. `Collection.keepWhatTheRefreshRead` weighs the header and log tail
45
+ * its refresh read around `TransactorSource` this way.
46
+ *
47
+ * @param servedRev the revision the content is.
48
+ * @returns `true` when no floor applies or the content meets the one that does. */
49
+ meetsApplicableFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean;
50
+ }
51
+
52
+ /** The floors of one collection handle, shared by EVERY read source that handle builds — its own
53
+ * and each pinned read view's — the way the `ReadDependencyCollector` is shared. Held on one
54
+ * source only, a view created right after a refresh would fetch the changed block through a source
55
+ * that knows no floor.
56
+ *
57
+ * Raised where log entries are consumed (`Collection.updateInternal`) and checked where answers
58
+ * arrive (`TransactorSource.tryGet`). A floor, once raised, STANDS for the life of the handle: an
59
+ * answer that meets it does not remove it.
60
+ *
61
+ * Why a met floor is not dropped. The source that judges an answer cannot know whether any cache
62
+ * went on to keep it, and "an answer met the floor" is not "the cache now holds that answer": the
63
+ * cache drops an answer that was overtaken while in flight (`CacheSource.stillWanted`), and evicts
64
+ * kept content under pressure (128 blocks). Either way the next read of the block goes back to
65
+ * storage, where nothing says the same machine answers twice — and with the floor gone, a too-old
66
+ * answer to THAT read is judged against nothing and kept for good, which is the defect floors exist
67
+ * to prevent. Reproduced with the floor dropped when met: a too-old answer, then a current one that
68
+ * the cache dropped as overtaken (but which removed the floor), then a too-old one — kept, and
69
+ * served after storage had caught up (`refresh-below-floor.spec.ts`, "a current answer the cache
70
+ * dropped..."). A standing floor costs one map lookup per fetched block and is always true of a
71
+ * correct answer: a block never goes back below a revision it was committed at.
72
+ *
73
+ * NOTE: the map is never pruned, so it holds one small entry per distinct block named by entries
74
+ * this handle walked — the same ids, and so the same bound, as `CacheSource`'s never-pruned
75
+ * `generations` map, which `clear(entry.blockIds)` populates beside every `raise`. If that ever
76
+ * grows large enough to matter, prune the two together (oldest floors first); a dropped floor only
77
+ * forfeits the check for that block, it never serves anything wrong by itself. */
78
+ export class BlockFloors implements BlockFloorCheck {
79
+ private readonly floors = new Map<BlockId, BlockFloor>();
80
+
81
+ /** @param onBelowFloor told about every below-floor answer, from any source sharing these floors
82
+ * — the collection reports them as `collection:block-below-floor`. */
83
+ constructor(private readonly onBelowFloor?: (answer: BelowFloorAnswer) => void) {}
84
+
85
+ /** Record that the walked entry `floor` describes changed `blockIds`. Highest revision wins, so
86
+ * entries may be walked in any order and re-walked harmlessly. */
87
+ raise(blockIds: readonly BlockId[], floor: BlockFloor): void {
88
+ for (const blockId of blockIds) {
89
+ const held = this.floors.get(blockId);
90
+ if (held === undefined || floor.rev > held.rev) {
91
+ this.floors.set(blockId, floor);
92
+ }
93
+ }
94
+ }
95
+
96
+ applicableTo(blockId: BlockId, context: ActionContext | undefined): BlockFloor | undefined {
97
+ const floor = this.floors.get(blockId);
98
+ return floor !== undefined && (context === undefined || context.rev >= floor.rev) ? floor : undefined;
99
+ }
100
+
101
+ answeredBelowFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean {
102
+ const floor = this.unmetFloor(blockId, context, servedRev);
103
+ if (floor === undefined) {
104
+ return false;
105
+ }
106
+ this.onBelowFloor?.({ blockId, floor, servedRev });
107
+ return true;
108
+ }
109
+
110
+ meetsApplicableFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean {
111
+ return this.unmetFloor(blockId, context, servedRev) === undefined;
112
+ }
113
+
114
+ /** The applicable floor that `servedRev` FAILS, or undefined when it meets it (or none applies).
115
+ * The one comparison behind both public checks, so a caller that only asks the question cannot
116
+ * drift from the one that also reports the answer. */
117
+ private unmetFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): BlockFloor | undefined {
118
+ const floor = this.applicableTo(blockId, context);
119
+ return floor !== undefined && servedRev < floor.rev ? floor : undefined;
120
+ }
121
+
122
+ /** How many blocks have a floor. */
123
+ get size(): number {
124
+ return this.floors.size;
125
+ }
126
+ }