Documentation / @etherfold/processor-entities / MutationContext
Type Alias: MutationContext ​
MutationContext =
object
Defined in: packages/state-store/dist/mutation-context.d.ts:24
The write surface a handler gets for ONE block.
get is read-your-writes WITHIN the block being processed: it answers from the mutations already staged for this block, and falls through to the store's current state otherwise. That matters because a handler that increments a counter must see the value an earlier event in the same block wrote, which is the behaviour the in-memory path gets for free by mutating one object. It is load-bearing rather than theoretical: on the real stratagems stream, 16,871 of 66,113 reads were served from the block's own staging area.
Blocks below the one being processed are always already flushed, because a block is applied before the next block's handlers run: one block is exactly one atomic unit. So get never has to reason about more than the current block.
Reads are uniformly async, on every backend. The alternative, typing them as T | Promise<T>, is infectious at every call site for the benefit of saving a microtask on a path whose cost is dominated by fetching logs.
Methods ​
delete() ​
delete(
entity,id):void
Defined in: packages/state-store/dist/mutation-context.d.ts:61
Close the live version without opening a new one: absent from this block on, readable before it.
Parameters ​
entity ​
string
id ​
Returns ​
void
get() ​
get<
T>(entity,id):Promise<T|undefined>
Defined in: packages/state-store/dist/mutation-context.d.ts:26
The entity as it stands, including mutations staged earlier in this block.
Type Parameters ​
T ​
T = Record<string, unknown>
Parameters ​
entity ​
string
id ​
Returns ​
Promise<T | undefined>
list() ​
list<
T>(entity,prefix,limit):Promise<Listing<T>>
Defined in: packages/state-store/dist/mutation-context.d.ts:59
The children of a key: the rows whose declared id STARTS WITH prefix, in ascending id order, at most limit of them, including this block's writes. The order is the store's own, UTF-8 byte order (compareIds, ADR-0021), so a row staged in the block is cut by the limit exactly as a stored one is.
This is how a one-to-many is read: children are their own entity keyed by their parent, and the collection is DERIVED HERE rather than stored, so appending a child costs one row and no maintenance of an array, a count or an index. {epoch: 7} under id: ['epoch', 'position', 'playerIndex'] is every placement of epoch 7.
The limit is REQUIRED and there is no predicate, no ordering and no offset: see listing.ts for why the bound is the design rather than a detail. If the answer is cut off, truncated says so, because a handler that mistakes a truncated collection for the whole of it (a cascade delete that stops early) leaves orphans behind silently.
Type Parameters ​
T ​
T = Record<string, unknown>
Parameters ​
entity ​
string
prefix ​
EntityIdPrefix
limit ​
number
Returns ​
Promise<Listing<T>>
set() ​
set(
entity,id,values):void
Defined in: packages/state-store/dist/mutation-context.d.ts:32
Write the WHOLE row. Unlisted declared fields become NULL, mirroring the store's close-then-insert: a version is a complete row, not a delta. To change one field, use update.
Parameters ​
entity ​
string
id ​
values ​
Record<string, unknown>
Returns ​
void
update() ​
update(
entity,id,values):Promise<void>
Defined in: packages/state-store/dist/mutation-context.d.ts:40
Sugar, and nothing more: get, spread, set.
It is spelled as sugar rather than as a second primitive so the storage model stays visible. A partial write still opens a complete new version; there is no such thing as writing one column of a version.
Parameters ​
entity ​
string
id ​
values ​
Record<string, unknown>
Returns ​
Promise<void>