syncitron library

Enterprise-grade local-first synchronization framework for Flutter.

syncitron provides a robust, battle-tested foundation for building offline-capable Flutter applications with automatic data synchronization, conflict resolution, and comprehensive monitoring.

Quick Start

import 'package:syncitron/syncitron.dart';

// 1. Create a config (production defaults recommended)
final config = syncitronConfig.production();

// 2. Create engine with your database and remote adapter
final engine = SyncEngine(
  localStore: SqfliteStore(database, conflictAlgorithm: ConflictAlgorithm.replace),
  remoteAdapter: SupabaseAdapter(
    client: supabaseClient,
    localStore: sqfliteStore,
    postgresChangeEventAll: PostgresChangeEvent.all,
  ),
  config: config,
  logger: ConsoleLogger(),
);

// 3. Register tables with conflict resolution strategies
engine
  .registerTable(TableConfig(
    name: 'todos',
    columns: ['id', 'title', 'completed', 'updated_at', 'deleted_at'],
    strategy: SyncStrategy.lastWriteWins,
  ))
  .registerTable(TableConfig(
    name: 'projects',
    columns: ['id', 'name', 'updated_at', 'deleted_at'],
    strategy: SyncStrategy.serverWins,
  ));

// 4. Perform synchronization
await engine.init();
final metrics = await engine.syncAll();
print(metrics);

Features

Offline-First: Works seamlessly offline, syncs when connected
Flexible Sync Strategies: ServerWins, LocalWins, LastWriteWins, Custom
Automatic Retry: Exponential backoff with configurable limits
Comprehensive Logging: Structured logging for debugging and analytics
Metrics & Monitoring: Track sync performance and data flow
Health Checks: Built-in diagnostics for system state
Dependency Injection: Fully composable with your architecture
Enterprise-Ready: Configuration management, error handling, and recovery
Multi-Engine Management: Coordinate multiple sync contexts

See the documentation for more details on advanced features: https://github.com/leonhardWullich/syncitron

Classes

AppwriteAdapter: Appwrite implementation of RemoteAdapter.
AppwriteRealtimeProvider: Appwrite implementation of RealtimeSubscriptionProvider.
CompositeSyncOrchestration: Builder for composing multiple orchestrations sequentially.
ConflictResolution: Explicit result type for custom conflict resolvers. Using a sealed class makes the intent clear and avoids null-as-signal ambiguity.
ConsoleLogger: Default console logger implementation.
DatabaseDiagnosticsProvider: Local database diagnostics.
DiagnosticsProvider: Interface for providing diagnostic information.
DriftStore: Drift (typed SQLite) implementation of LocalStore.
FetchPolicy: GraphQL Fetch Policy enum.
FirebaseFirestoreAdapter: Firebase Firestore implementation of RemoteAdapter.
FirebaseFirestoreRealtimeProvider: Firebase Firestore implementation of RealtimeSubscriptionProvider.
Gql: Helper placeholder for GraphQL document parsing. In real use, you'd import from 'graphql/language/ast.dart'
GraphQLAdapter: Generic GraphQL implementation of RemoteAdapter.
GraphQLRealtimeProvider: GraphQL implementation of RealtimeSubscriptionProvider.
HealthCheckResult: Health check result for a single component.
HiveStore: Hive (NoSQL) implementation of LocalStore.
InMemoryMetricsCollector: Default in-memory metrics collector.
IsarStore: Isar (embedded NoSQL) implementation of LocalStore.
LocalStore: Abstraction over the local persistence layer.
LogEntry: Represents a structured log entry for enterprise applications.
Logger: Abstract logger interface for dependency injection.
MetricsCollector: Abstract interface for metrics collection and reporting.
MultiLogger: Aggregates multiple loggers (useful for multi-channel logging).
MutationOptions: GraphQL Client mutation options placeholder.
NoOpLogger: No-op logger for production (disable logging).
NoOpMetricsCollector: No-op metrics collector for production (disable metrics).
OfflineFirstSyncOrchestration: Built-in orchestration: Offline-first with graceful degradation.
OfflineIndicator: Indicator showing whether the device is online or offline.
PrioritySyncOrchestration: Built-in orchestration: Selective sync by table priority.
PullRequest
PullResult
QueryOptions: GraphQL Client query options placeholder.
RealtimeChangeEvent: Event emitted when a real-time change is received.
RealtimeSubscriptionConfig: Configuration for real-time subscription behavior.
RealtimeSubscriptionManager: Manages real-time subscriptions across tables.
RealtimeSubscriptionProvider: Abstract interface for real-time subscription functionality. Implementations provided by RemoteAdapters.
RemoteAdapter
SqfliteStore: SQLite implementation of LocalStore backed by sqflite.
StandardSyncOrchestration: Built-in orchestration: Standard pull-push-conflicts pattern (default).
StrictManualOrchestration: Built-in orchestration: Manual-only with strict error handling.
SupabaseAdapter: RemoteAdapter implementation backed by Supabase.
SupabaseRealtimeProvider: Supabase implementation of RealtimeSubscriptionProvider.
SyncButton: A button that triggers sync and shows loading state.
SyncCursor
SyncDiagnosticsProvider: Sync diagnostics provider.
SyncEngine: Enterprise-grade synchronization engine for local-first Flutter applications.
SyncErrorBanner: Displays an error banner for sync exceptions.
syncitronConfig: Configuration for the syncitron sync engine.
SyncManager: Manages multiple SyncEngine instances with coordinated synchronization.
SyncMetrics: Metrics for monitoring syncitron's sync performance.
SyncMetricsCard: Displays sync metrics (pulled, pushed, duration) in a card format.
SyncOrchestrationContext: Execution context provided to custom sync orchestrations.
SyncOrchestrationStrategy: Defines the lifecycle and behavior of custom sync orchestrations.
SyncSessionMetrics: Aggregated metrics for the entire sync session.
SyncStatusPanel: Comprehensive sync status panel with metrics, errors, and controls.
SyncStatusWidget: Displays the current sync status with customizable UI.
SystemDiagnosticsProvider: Comprehensive system diagnostics provider.
SystemHealth: Aggregation of health checks for the entire system.
TableConfig: Configuration for a single table in the sync topology.
UniqueId: Helper for generating unique IDs compatible with Appwrite.
UseLocal: Keep the local (dirty) record. The remote update is ignored.
UseMerged: Save a manually merged record combining both versions.
UseRemote: Overwrite local with the remote record.

Enums

HealthStatus: Represents the health status of a component.
LogLevel: Severity levels for log messages.
RealtimeOperation: Real-time operation types.
SyncStrategy: Strategies for resolving conflicts between local and remote changes.

Functions

retry<T>(Future<T> action(), {int retries = 3, Duration initialDelay = const Duration(milliseconds: 300), Duration maxDelay = const Duration(seconds: 30), Logger? logger}) → Future<T>: Retry a future with exponential backoff.

Typedefs

ConflictResolver = Future<ConflictResolution> Function(Map<String, dynamic> local, Map<String, dynamic> remote): A resolver callback for SyncStrategy.custom.

Exceptions / Errors

ConflictResolutionException: Thrown when a SyncStrategy.custom resolver throws an unhandled error.
EngineConfigurationException: Thrown when SyncEngine is used before SyncEngine.init has completed, or when configuration is invalid (e.g. SyncStrategy.custom without a ConflictResolver).
LocalStoreException: Thrown when a batch upsert to the local SQLite store fails.
RemoteAdapterException
SchemaMigrationException: Thrown when an auto-migration (ALTER TABLE) fails.
SyncAuthException: Thrown when the remote adapter signals that the request is unauthorized.
syncitronException: Base class for all exceptions thrown by the syncitron framework.
SyncNetworkException: Thrown when a network request to the remote adapter fails.
UnregisteredTableException: Thrown when SyncEngine.syncTable is called with a table name that was not registered via SyncEngine.registerTable.

syncitron library

Quick Start

Features

Classes

Enums

Functions

Typedefs

Exceptions / Errors

syncitron package

syncitron library