Skip to main content

ds_sync_contract 0.1.0 copy "ds_sync_contract: ^0.1.0" to clipboard
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:

  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.

0
likes
150
points
0
downloads

Documentation

API reference

Publisher

verified publisherdragon-software.net

Weekly Downloads

Pure type contract for the ds_easy_db sync ecosystem: capabilities, conflict policies, delta and push types, and the remote adapter interface.

Repository (GitHub)
View/report issues

License

BSD-3-Clause (license)

More

Packages that depend on ds_sync_contract