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:

  1. Error mapping is the connectivity check. An unreachable backend maps to SyncErrorKind.transient — the ecosystem needs no connectivity plugin.
  2. 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.
  3. 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_db sync ecosystem.