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, which evoluError reports.
  • Syncing: a relay connects for the first time or reconciles. A first connection to a host that drops packets stays Syncing until 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 stays Synced until the shared worker replaces it: within about five seconds of waking from a system sleep where performance.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 where performance.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, so Disconnected can 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. error is 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.",
);