API reference › @evolu/common › local‑first/Shared › OwnerSyncStatus
type OwnerSyncStatus = NoRelaysSyncStatus | RelaySyncStatus;
Defined in: packages/common/src/local-first/Shared.ts:1201
What an app shows users about syncing one owner of one database, from
syncStateToOwnerSyncStatus or the React and Vue useOwnerSyncStatus.
Its variants:
NoRelays: nothing syncs the owner here. There is no snapshot yet, the owner's transports are still being set up, the app uses no relays for it, it is registered only as readonly, or the database is refused, whichevoluErrorreports.Syncing: a relay connects for the first time or reconciles. A first connection to a host that drops packets staysSyncinguntil the platform gives up on it, which can take a minute.Synced: a relay is up to date, and none syncs. A connection that dies without closing staysSynceduntil the shared worker replaces it: within about five seconds of waking from a system sleep whereperformance.now()stops during sleep, and otherwise, on a relay that sends heartbeats and while no request is outstanding on the connection, at most two and a half minutes after its last frame, or up to five seconds more after a sleep whereperformance.now()counts it. An outstanding request of any owner on the connection leaves it to the request timeout instead, ninety seconds without a Response for its owner unless the timeout has grown; see Liveness in this module's documentation.Disconnected: every relay is disconnected. Evolu can't tell whether the device is offline or the relays are down (WebSockets report only that a connection failed, not why), so tell users that the app can't reach its sync server, not that they are offline. Evolu keeps reconnecting, up to 30 seconds apart, soDisconnectedcan briefly outlast the outage.Error: a relay failed, a relay offers a change this database skipped, or this database stores a change too large to send.erroris the newest failure, or without one, the newest skipped change: a failure stops syncing through its relay, while a skipped change leaves out only that change.
Evolu stores changes in the local database before they sync, so sync needs no
UI while it works: show nothing for NoRelays, Syncing, and Synced. An
indicator that changes with every edit distracts, and screen readers announce
each change.
An app that shows an indicator anyway, such as a dot, may show a time when
someone opens it, from the routes syncStateToRelaySyncStates returns.
While Synced, say "Up to date since" the newest completeAt of the routes
whose type is Complete. That is when the owner last became up to date,
after the last edit or the last change from another device, so it stays true
however long the connection is quiet, while a route's lastReceivedAt would
read "Last synced 4 hours ago" on a quiet connection that works. While
Disconnected, say since when, from the newest disconnectedAt of the
connections. After a sleep, that is when the connection was replaced after
waking, not when syncing stopped.
For Disconnected and Error, show one quiet line that lasts as long as the
status, not a dialog, which interrupts, or a toast, which disappears while
the problem lasts. Put it in an element with role="status" that stays
mounted, because screen readers announce changes only in a live region that
already exists. Do not say that changes are saved on this device unless
Evolu.devicePersistence is Persisted: a browser may keep them only
for a private session or delete them later. Evolu reports Disconnected at
once; an app may wait a few seconds before showing it, because brief
disconnections, such as waking from sleep, reconnect quickly. For Error,
write actionable text for the error types the app can act on, such as a
ProtocolQuotaError: the relay stores no more data for the owner, so
offer more quota, such as a plan upgrade, then call Evolu.requestSync
with the owner's ID. For any other error, show generic text that names the
error type, which helps when the user reports it.
Render the line inside one element with role="status" that stays mounted:
screen readers announce changes only in a live region that already exists,
and a polite announcement fits a status that loses nothing. Do not use
role="alert".
Show the app owner's status once for the whole app, such as below the header, and another owner's status where the app shows that owner's data. Each Evolu instance finds its own status by Evolu.name, so an app with several databases shows the status of the one the user works in.
Example
import { assertEqual, Millis } from "@evolu/common";
import { testAppOwner, type OwnerSyncStatus } from "@evolu/common/local-first";
// What to tell the user, or null while sync works or is not used.
const syncStatusToMessage = (status: OwnerSyncStatus): string | null => {
switch (status.type) {
case "NoRelays":
case "Syncing":
case "Synced":
return null;
case "Disconnected":
return "Can't reach the sync server. Changes will sync once the connection is back.";
case "Error":
return status.error.type === "ProtocolQuotaError"
? "Sync is paused because the sync server is full."
: `Sync error: ${status.error.type}.`;
}
};
assertEqual(syncStatusToMessage({ type: "Synced" }), null);
assertEqual(
syncStatusToMessage({ type: "Disconnected" }),
"Can't reach the sync server. Changes will sync once the connection is back.",
);
assertEqual(
syncStatusToMessage({
type: "Error",
error: {
type: "ProtocolQuotaError",
ownerId: testAppOwner.id,
at: Millis.orThrow(1000),
},
}),
"Sync is paused because the sync server is full.",
);
assertEqual(
syncStatusToMessage({
type: "Error",
error: { type: "SyncFailed", at: Millis.orThrow(1000) },
}),
"Sync error: SyncFailed.",
);