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");