Skip to main content
Version: v10.0.0

MutationEngine

Sends writes. Each write shows at once as an optimistic layer. Writes to one row go out one at a time, and a failure drops the writes queued after it on that row. With offline , every write goes through a persisted outbox that is replayed in order across the whole db by one tab.


Import
import { MutationEngine } from "@hyper-fetch/db"

Parameters​

class MutationEngine {
constructor(db: DbRuntime, offline: undefined | boolean | DbOfflineOptions, transactions: Record<string, TransactionConfig>) {};
usesOutbox: void;
outbox: TransactionRecord[];
applyOutcome(outcome: { error?: unknown; id: string; key?: RowKey; success: boolean }) => void;
clear() => void;
destroy() => void;
mergeOutbox(records: TransactionRecord[]) => void;
pump() => Promise<void>;
reject(error: unknown, id: string) => Transaction;
resendToLeader() => void;
restore(records: TransactionRecord[]) => void;
settled(collection: string) => Promise<void>;
submit(__namedParameters: { collection: CollectionRuntime; dependsOn: string[]; id: string; key: RowKey; op: MutationOperation; temporaryKey?: boolean; values: Row }) => Transaction;
submitTransaction(__namedParameters: { id: string; name: undefined | string; writes: PreparedWrite[] }) => Transaction;
}
Parameters
NameTypeDescription
db
DbRuntime
offline
undefined | boolean | DbOfflineOptions
transactions
Record<string, TransactionConfig>

Properties​

outbox​

The outbox, in replay order

Type
TransactionRecord[]

usesOutbox​

Type
void

Methods​

applyOutcome()​

The replaying tab reports a write's outcome

Preview
applyOutcome(outcome: { error?: unknown; id: string; key?: RowKey; success: boolean })
Parameters
Parameters
NameTypeDescription
outcome
{ error?: unknown; id: string; key?: RowKey; success: boolean }
Returns
void

clear()​

Drops every pending write, for example on sign-out. Writes in flight resolve as failed now, and their responses, which carry the previous user's data, are never written.

Preview
clear()
Returns
void

destroy()​

Stops the retry timer, for destroy

Preview
destroy()
Returns
void

mergeOutbox()​

Writes another tab made: a follower sent them to this tab, the leader, or this tab became the leader and adopts the outbox the previous leader persisted. They are persisted together with this tab's own writes and replayed.

Preview
mergeOutbox(records: TransactionRecord[])
Parameters
Parameters
NameTypeDescription
records
TransactionRecord[]
Returns
void

pump()​

Replays the outbox when this tab is the one that replays it, one write at a time and in order

Preview
pump()
Returns
Promise<void>

reject()​

A write rejected before it was sent, for example by validation

Preview
reject(error: unknown, id: string)
Parameters
Parameters
NameTypeDescription
error
unknown
id
string
Returns
reject
NameTypeDescription
id
string

resendToLeader()​

A new leader asks for the writes followers still wait for

Preview
resendToLeader()
Returns
void

restore()​

Rebuilds the optimistic layers of a restored outbox and replays it

Preview
restore(records: TransactionRecord[])
Parameters
Parameters
NameTypeDescription
records
TransactionRecord[]
Returns
void

settled()​

Resolves once no write of the collection is in flight

Preview
settled(collection: string)
Parameters
Parameters
NameTypeDescription
collection
string
Returns
Promise<void>

submit()​

Applies a write optimistically and sends it

Preview
submit(__namedParameters: { collection: CollectionRuntime; dependsOn: string[]; id: string; key: RowKey; op: MutationOperation; temporaryKey?: boolean; values: Row })
Parameters
Parameters
NameTypeDescription
__namedParameters
{ collection: CollectionRuntime; dependsOn: string[]; id: string; key: RowKey; op: MutationOperation; temporaryKey?: boolean; values: Row }
Returns
submit
NameTypeDescription
id
string

submitTransaction()​

Applies several writes as one transaction. A named transaction sends them through its mutationFn as one request. Without a name, each write goes through its collection's mutate , in order, and a failure drops the writes after it and refetches the subsets holding the rows already written.

Preview
submitTransaction(__namedParameters: { id: string; name: undefined | string; writes: PreparedWrite[] })
Parameters
Parameters
NameTypeDescription
__namedParameters
{ id: string; name: undefined | string; writes: PreparedWrite[] }
Returns
submitTransaction
NameTypeDescription
id
string