@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.
- package/dist/src/collection/collection.d.ts +40 -2
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +59 -4
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/collections/tree/struct.d.ts +9 -4
- package/dist/src/collections/tree/struct.d.ts.map +1 -1
- package/dist/src/collections/tree/struct.js +9 -4
- package/dist/src/collections/tree/struct.js.map +1 -1
- package/dist/src/transactor/block-floors.d.ts +13 -0
- package/dist/src/transactor/block-floors.d.ts.map +1 -1
- package/dist/src/transactor/block-floors.js +12 -2
- package/dist/src/transactor/block-floors.js.map +1 -1
- package/dist/src/transform/cache-source.d.ts +29 -4
- package/dist/src/transform/cache-source.d.ts.map +1 -1
- package/dist/src/transform/cache-source.js +48 -7
- package/dist/src/transform/cache-source.js.map +1 -1
- package/package.json +1 -1
- package/src/collection/collection.ts +2118 -2061
- package/src/collections/tree/struct.ts +9 -4
- package/src/transactor/block-floors.ts +126 -105
- package/src/transform/cache-source.ts +370 -327
|
@@ -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`
|
|
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 `
|
|
170
|
-
* message) handles this one identically without a second arm.
|
|
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
|
|
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
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
*
|
|
67
|
-
*
|
|
68
|
-
*
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
const
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
this.
|
|
98
|
-
return
|
|
99
|
-
}
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
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
|
+
}
|