ds_sync_contract 0.1.0
ds_sync_contract: ^0.1.0 copied to clipboard
Pure type contract for the ds_easy_db sync ecosystem: capabilities, conflict policies, delta and push types, and the remote adapter interface.
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.