ds_sync_contract
Pure type contract for the ds_easy_db sync ecosystem — types only, no logic.
ds_easy_db_sync (the engine) and every sync-capable remote adapter depend on this
package, and on nothing else beyond the Dart SDK. That makes it the most stable package
of the ecosystem: types here rarely change, so adapters and engine can evolve
independently.
What it defines
| Area | Types |
|---|---|
| Errors | SyncErrorKind, SyncError, SyncResolution |
| Capabilities | SyncCapabilities, CapabilityFallback |
| Content conflicts | ConflictPolicy, MergeFn, ThreeWayMergeFn, SyncDocument |
| Delete conflicts | DeleteConflictPolicy, DeleteConflictContext, DeleteConflictOutcome |
| Scoping | UserScope |
| Delta pull | DeltaResult, RemoteRecord, RemoteAnchor |
| Push | PushItem, PushResult, PushStatus |
| Adapter contract | SyncRemoteAdapter |
Building an adapter
class MyAdapter implements SyncRemoteAdapter {
@override
SyncCapabilities get capabilities => const SyncCapabilities(
supportsTimestamps: true,
supportsDeltaPull: true,
supportsDeltaDeletes: true,
);
@override
SyncError mapError(Object error, StackTrace stackTrace) => /* classify */;
@override
Future<DeltaResult> pullSince(String collection, Object? cursor) async => /* ... */;
@override
Future<List<PushResult>> pushBatch(List<PushItem> items) async => /* ... */;
}
Three rules an adapter must respect:
- Error mapping is the connectivity check. An unreachable backend maps to
SyncErrorKind.transient— the ecosystem needs no connectivity plugin. - Push results are always per record, even for atomic batch backends (they emit a uniform status across all items). This keeps an aborted push idempotently retryable.
- The cursor is opaque. Only the adapter that produced it may interpret it.
Policy is the application's decision
This package deliberately offers several conflict strategies instead of one. There is no
universally right answer: lastWriteWins is fine for a cleaning plan and wrong for a
shared cash book — use ConflictPolicy.custom there, so both edits survive. The engine
never picks for the consumer.
License
BSD-3-Clause.
Libraries
- ds_sync_contract
- Pure type contract for the
ds_easy_dbsync ecosystem.