rev_sync library
A reusable offline-first sync engine: a connectivity-driven scheduler plus a generic CRUD sync (push queue + delta pull) that reconciles a local store with a remote adapter over a server revision cursor, with conflict detection.
Classes
- ConnectivitySource
-
A minimal connectivity signal the scheduler reacts to, abstracted so the
engine stays pure Dart (the app supplies a
connectivity_plus-backed implementation) and is trivially fakeable in tests. -
OfflineCrudSync<
T extends Syncable> -
The generic body of an offline-first CRUD sync: a push queue followed by a
delta pull, reconciling a SyncLocalStore with a SyncRemoteAdapter using
the server's revision (
rev) as both the delta cursor and the optimistic-concurrency token. -
PushApplied<
T extends Syncable> - The server accepted the write; record carries its authoritative values.
-
PushConflict<
T extends Syncable> - An update/delete was rejected because the server revision no longer matches the one the edit was based on — a genuine conflict needing resolution.
-
PushGone<
T extends Syncable> - An update/delete targeted a row the server no longer has.
-
PushResult<
T extends Syncable> - The outcome of pushing one pending row to the server.
-
PushSuperseded<
T extends Syncable> - A create was rejected because the row already exists server-side (a retried create whose first response was lost). It is effectively synced; the next pull refreshes its fields.
-
RemoteRecord<
T extends Syncable> - A server view of one row, returned by a delta pull or a push acknowledgement.
- Syncable
- A local row the sync engine can reconcile with the server.
- SyncCursorStore
- Persists the per-resource delta cursor — the highest server revision a pull has already applied. The next pull asks the server only for newer rows.
-
SyncLocalStore<
T extends Syncable> - The local persistence the sync engine drives, abstracted over the concrete store (ObjectBox in the app). Implementations are expected to be backed by a fast local database; all methods are async only to keep the contract storage-agnostic.
-
SyncRemoteAdapter<
T extends Syncable> - The server side of one synced resource, implemented per feature.
- SyncScheduler
- Drives a sync body on the right triggers and shields it from overlap.
Enums
- SyncOutcome
- The result of one sync run, returned by a scheduler body. Drives both the surfaced SyncStatus and the scheduler's backoff.
- SyncState
- The sync lifecycle of a single local row.
- SyncStatus
- The user-facing sync state, surfaced by the scheduler to drive UI such as an app-bar indicator.
Exceptions / Errors
- SyncTerminalException
- A non-retryable failure (e.g. validation 4xx). The row is marked failed and surfaced rather than retried forever.
- SyncTransientException
- A retryable failure (network down, timeout, server 5xx). The row keeps its pending state and is retried on the next sync.