SyncService class abstract

Service interface for sync operations.

Handles synchronization of location data with remote servers, including offline queue management and retry logic.

Example:

// Trigger immediate sync
await Locus.sync.now();

// Listen to sync events
Locus.sync.events.listen((event) {
  if (event.success) {
    print('Synced ${event.count} locations');
  } else {
    print('Sync failed: ${event.statusCode}');
  }
});

// Set sync policy
await Locus.sync.setPolicy(SyncPolicy(
  minBatteryLevel: 20,
  requireWifi: true,
  maxRetries: 3,
));

// Enqueue custom payload
await Locus.sync.enqueue({
  'type': 'check-in',
  'locationId': 'store-123',
});
Implementers

Constructors

SyncService()

Properties

connectivityEvents Stream<ConnectivityChangeEvent>
Stream of connectivity changes.
no setter
events Stream<HttpEvent>
Stream of HTTP sync events.
no setter
hashCode int
The hash code for this object.
no setterinherited
runtimeType Type
A representation of the runtime type of the object.
no setterinherited

Methods

clearHeadersCallback() → void
Clears the dynamic headers callback.
clearQueue() Future<void>
Clears all queued payloads.
clearSyncBodyBuilder() → void
Clears the sync body builder callback.
enqueue(JsonMap payload, {String? type, String? idempotencyKey}) Future<String>
Enqueues a custom payload for offline-first delivery.
evaluatePolicy({required SyncPolicy policy}) Future<SyncDecision>
Evaluates if sync should proceed based on current conditions.
getQueue({int? limit}) Future<List<QueueItem>>
Returns queued payloads.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
now() Future<bool>
Triggers an immediate sync of pending locations.
onConnectivityChange(void callback(ConnectivityChangeEvent), {Function? onError}) StreamSubscription<ConnectivityChangeEvent>
Subscribes to connectivity change events.
onHttp(void callback(HttpEvent), {Function? onError}) StreamSubscription<HttpEvent>
Subscribes to HTTP sync events.
refreshHeaders() Future<void>
Manually triggers a header update.
registerHeadlessSyncBodyBuilder(Future<JsonMap> builder(SyncBodyContext context)) Future<bool>
Registers a headless-compatible sync body builder.
resume() Future<bool>
Resumes sync after a pause (e.g., after token refresh).
setHeadersCallback(Future<Map<String, String>> callback()?) → void
Sets a callback to provide dynamic HTTP headers.
setPolicy(SyncPolicy policy) Future<void>
Sets the sync policy.
setSyncBodyBuilder(SyncBodyBuilder? builder) → void
Sets a callback to build custom HTTP sync body.
syncQueue({int? limit}) Future<int>
Attempts to sync queued payloads immediately.
toString() String
A string representation of this object.
inherited

Operators

operator ==(Object other) bool
The equality operator.
inherited