API reference › @evolu/common › local‑first/Schema › MutationOptions
Defined in: packages/common/src/local-first/Schema.ts:543
Options accepted by every Mutation.
Properties
onError?
readonly onError?: (error: UnknownError) => void;
Defined in: packages/common/src/local-first/Schema.ts:589
Called instead of MutationOptions.onSuccess when the mutation could
not be stored, with none of its batch, or when the database is refused,
such as when another context holds its files.
EvoluErrorDep.evoluError reports the error too, a refusal once per
tab and again for each instance the tab creates later, so an app shows it
there and passes onError only where it must know that the mutation ended,
such as to release a lock or settle a promise.
A replay after leader replacement can fail although the earlier leader
stored the mutation and only its answer was lost, and a mutation in flight
when the database was refused may have been stored by the worker that
refused it, so onError can run for a stored mutation.
onSuccess?
readonly onSuccess?: () => void;
Defined in: packages/common/src/local-first/Schema.ts:573
Called after the mutation's changes are stored and subscribed queries reflect them. Useful for follow-up work (e.g., notifications, navigation) after insert, update, or upsert. When the mutation could not be stored, or the database is refused, MutationOptions.onError runs instead. Neither runs when the instance is disposed before it receives the mutation's result. It still runs when SQLite fails a subscribed query, which then keeps its previous rows; see Evolu.loadQuery.
An Evolu instance stores its mutations in batches, each in one transaction. A batch holds the mutations made before Evolu sends it in a microtask, usually one synchronous block. Evolu.requestSync, an uncached Evolu.loadQuery, Evolu.deleteDatabase, and Evolu.deleteOwner send it early. When one mutation cannot be stored, none of its batch is.
Other devices receive a batch as separate changes, one per mutation, possibly over several syncs, so their queries can show part of a batch until the rest arrives. The values of one mutation always arrive together.
Stored does not always mean visible. A change quarantined for
QuarantineReason.TimestampDrift is stored in
evolu_message_quarantine without changing application rows. onSuccess
still fires after storage commits; no drift error is reported. Applications
can subscribe to the quarantine table; those query results reflect the
change before onSuccess runs. See the
Timestamp module for drift
and release behavior.
owner?
readonly owner?: MutationOwner;
Defined in: packages/common/src/local-first/Schema.ts:665
The Owner of the mutated row. If omitted, the AppOwner. An AppOwner's data lives only in its own database, which its deletion deletes, so a mutation owned by another AppOwner throws. An instance of createEvoluApp recognizes another AppOwner by the IDs the app lists; one of createEvolu only by its type, so it misses an owner with another AppOwner's ID but another type, such as one created from that AppOwner's secret.
It must be an Owner with its write key, because a relay accepts a change only with the owner's write key. A SharedReadonlyOwner has none, so it is rejected at compile time instead of storing changes this device cannot upload. The owner does not have to be used yet: its changes are stored locally and upload once Evolu.useOwner registers it.
Example
import {
assertEqual,
createAppOwner,
createOwnerSecret,
createRandomBytes,
createSharedOwner,
createSharedReadonlyOwner,
deriveShardOwner,
id,
NonEmptyTrimmedString100,
type Evolu,
} from "@evolu/common";
const Schema = {
task: { id: id("Task"), title: NonEmptyTrimmedString100 },
comment: { id: id("Comment"), text: NonEmptyTrimmedString100 },
};
const randomBytes = createRandomBytes();
// Create once, persist the mnemonic securely, and restore it on later runs.
const appOwner = createAppOwner(createOwnerSecret({ randomBytes }));
const projectOwner = deriveShardOwner(appOwner, ["project", "project-1"]);
const sharedOwner = createSharedOwner(createOwnerSecret({ randomBytes }));
const _insertOwnedRows = (evolu: Evolu<typeof Schema>): void => {
// Partition app data by project.
evolu.insert(
"task",
{ title: NonEmptyTrimmedString100.orThrow("Task 1") },
{ owner: projectOwner },
);
// Put collaborative data under a shared owner.
evolu.insert(
"comment",
{ text: NonEmptyTrimmedString100.orThrow("Hello") },
{ owner: sharedOwner },
);
// Readers of shared data cannot write it.
evolu.insert(
"comment",
{ text: NonEmptyTrimmedString100.orThrow("Hi") },
// @ts-expect-error A SharedReadonlyOwner has no write key, so it cannot own a mutation.
{ owner: createSharedReadonlyOwner(sharedOwner) },
);
};
assertEqual(projectOwner.type, "ShardOwner");
assertEqual(sharedOwner.type, "SharedOwner");