Event system

Subscribe to sync lifecycle events for state management and UI updates.

Subscribe to typed events for UI updates, notifications, or side effects.

Subscribing to events

Use onEvent to listen to all event types. It returns an unsubscribe function.


const unsubscribe = client.onEvent((event) => {
  switch (event.type) {
    case "syncStart":
      console.log("Sync started");
      break;

Published with Edda

Event Name	Key Fields	Description
`syncStart`	-	A sync cycle has begun.
`syncComplete`	`lastSyncId: number`	A sync cycle finished. `lastSyncId` is the highest sync ID received.
`syncError`	`error: Error`	A sync cycle failed.
`stateChange`	`state: SyncClientState`	The client transitioned to a new sync state.
`connectionChange`	`state: ConnectionState`	The transport connection state changed.
`outboxChange`	`pendingCount: number`	The count of unsynced transactions changed.
`mutationRejected`	`modelName: string`, `modelId: string`, `action: TransactionAction`, `error: string`	The server rejected a mutation and its persisted optimistic change was rolled back.
`modelChange`	`modelName: string`, `modelId: string`, `action: ModelChangeAction`	A model was inserted, updated, deleted, archived, or unarchived (local or server).
`rebaseConflict`	`modelName: string`, `modelId: string`, `conflictType: string`, `resolution: string`	A conflict was detected during transaction rebasing.


// Full type definitions

type SyncEvent =
  | { type: "syncStart" }
  | { type: "syncComplete"; lastSyncId: number }
  | { type: "syncError"; error: Error }
  | { type: "stateChange"; state: SyncClientState }
  | { type: "connectionChange"; state: ConnectionState }
  | { type: "outboxChange"; pendingCount: number }
  | {
      type: "mutationRejected";
      modelName: string;
      modelId: string;
      action: TransactionAction;
      error: string;
    }
  | {
      type: "modelChange";
      modelName: string;
      modelId: string;
      action: ModelChangeAction;
    }
  | {
      type: "rebaseConflict";
      modelName: string;
      modelId: string;
      conflictType: string;
      resolution: string;
    };

type ModelChangeAction =
  | "insert"
  | "update"
  | "delete"
  | "archive"
  | "unarchive";

State	Description
`"disconnected"`	Not connected to the server.
`"connecting"`	Establishing a connection.
`"bootstrapping"`	Loading initial data from the server.
`"syncing"`	Connected and syncing deltas. This is the "ready" state.
`"error"`	An unrecoverable error occurred.


import { useConnectionState, usePendingCount } from "@stratasync/react";

function SyncStatus() {
  const { status, lastSyncId, error } = useConnectionState();
  const { count, hasPending } = usePendingCount();

  return (
    <div>
      <span>Status: {status}</span>
      <span>Sync ID: {lastSyncId}</span>
      {hasPending && <span>{count} pending</span>}
      {error && <span>Error: {error.message}</span>}
    </div>
  );
}

Event system

Subscribing to events

Event system

Subscribing to events

Specialized subscribers

onStateChange

onConnectionStateChange

Event types

SyncClientState values

Usage with React