offline_sync_engine 3.0.0

Offline-first CRDT-based sync engine with automatic conflict resolution. Seamlessly sync data across multiple devices with built-in implementations for quick start.

Offline Sync Engine

Offline-first CRDT-based sync engine for Flutter and Dart applications. It keeps data synchronized across devices with deterministic conflict resolution.

Features

• 🔄 Automatic Sync - Push local operations and pull remote operations.
• 📴 Offline-First - Create/update/delete records without network.
• 🔀 Deterministic Merge - Concurrent updates converge predictably.
• 📱 Multi-Device - Same account on multiple devices stays in sync.
• 🎯 Operation-Based - Sync is based on replayable operations.
• 🔢 Vector Clocks - Causality tracking across devices.
• ⚡ Idempotent Apply - Safe against duplicate operation delivery.
• 🧩 Adapter-Based - Plug in your own database and cloud backend.
• ✅ Type Safe - Null-safe Dart API.

Installation

dart pub add offline_sync_engine

or

flutter pub add offline_sync_engine

Your pubspec.yaml:

dependencies:
  offline_sync_engine: ^3.0.0

Then run:

dart pub get

or

flutter pub get

Quick Start

import 'package:offline_sync_engine/offline_sync_engine.dart';

void main() async {
  final manager = SyncManager(
    database: InMemoryDatabaseAdapter(),
    cloud: InMemoryCloudAdapter(),
    deviceId: 'device_123',
  );

  // Local write (works offline)
  await manager.createOrUpdate('user_1', {
    'name': 'John',
    'email': '[e-mail]',
  });

  // Push + pull sync
  await manager.sync();
}

Core Concepts

1) Adapters

You provide two adapters:

1. DatabaseAdapter: local persistence (SQLite, Hive, Isar, etc.)
2. CloudAdapter: backend transport (REST/Firebase/Supabase/etc.)

For demos/tests, use built-ins:

• InMemoryDatabaseAdapter
• InMemoryCloudAdapter

2) SyncManager

SyncManager is the main entry point:

final manager = SyncManager(
  database: myDatabaseAdapter,
  cloud: myCloudAdapter,
  deviceId: 'unique_device_id',
);

await manager.createOrUpdate('note_1', {'title': 'hello'});
await manager.delete('note_1');
await manager.sync();

final syncing = manager.isSyncing;

3) Conflict Resolution

The engine uses vector clocks with deterministic merge:

• If one version dominates another, dominant record wins.
• If versions are concurrent, fields are merged deterministically.
• Merge result is stable and commutative for concurrent records.

Production Checklist (Important)

Before publishing your app with custom adapters:

• ❌ Ensure saveOperation + applyOperation are durable.
• ❌ Keep operation IDs unique and indexed.
• ❌ Make isApplied fast (index/table/set).
• ❌ Use retries/backoff for cloud calls.
• ❌ Add authentication/authorization at transport layer.
• ❌ Add pagination/incremental pull strategy on backend.
• ❌ Add monitoring for sync failures.

Running Examples

cd example
dart run main.dart
dart run multi_device_example.dart
dart run delete_example.dart
dart run custom_adapters_example.dart

More details: example/README.md

Adapter Contract Notes

DatabaseAdapter expectations

• saveOperation should persist operation before app crash risk.
• getUnsentOperations should return unsent operations reliably.
• markOperationSent should be idempotent.
• isApplied should be idempotency source-of-truth.
• applyOperation must be deterministic and safe to replay.

CloudAdapter expectations

• push should accept duplicate deliveries safely.
• pull can return already-seen operations; manager handles dedupe via isApplied.
• Server ordering should be stable where possible.

License

MIT License - see LICENSE.