SyncLayer #

Build offline-first Flutter apps in minutes — Production-grade sync engine with automatic background synchronization and conflict resolution.

Works with REST APIs, Firebase, Supabase, Appwrite, or any custom backend.

✅ PRODUCTION READY - v1.3.1 stable release. Battle-tested with 242+ downloads and perfect pub.dev score (160/160).

Why SyncLayer? #

Your users expect apps to work offline. But building sync is hard:

❌ Manual queue management
❌ Conflict resolution logic
❌ Network retry handling
❌ Version tracking

SyncLayer handles all of this for you.

// That's it. Your app now works offline.
await SyncLayer.init(
  SyncConfig(
    baseUrl: 'https://api.example.com',
    collections: ['todos'],
  ),
);

// Save works instantly (local-first)
await SyncLayer.collection('todos').save({
  'text': 'Buy groceries',
  'done': false,
});

// Auto-syncs in background when online
// Handles conflicts automatically
// Retries on failure

What You Get #

🚀 Local-First - Writes happen instantly to local storage
🔄 Auto-Sync - Background sync every 5 minutes (configurable)
📡 Offline Queue - Operations sync automatically when online
⚔️ Conflict Resolution - Last-write-wins, server-wins, client-wins, or custom resolvers
🎨 Custom Conflict Resolvers - Merge arrays, sum numbers, field-level merging (NEW in v1.3.0!)
⚡ Delta Sync - Only sync changed fields, save 70-98% bandwidth (NEW in v1.3.0!)
🔐 Encryption at Rest - AES-256-GCM, CBC, ChaCha20 for HIPAA/PCI compliance (NEW in v1.3.0!)
🔌 Backend Agnostic - Works with REST, Firebase, Supabase, or custom backends
📦 Batch Operations - Save/delete multiple documents efficiently
👀 Reactive - Watch collections for real-time UI updates
🔍 Query & Filter - Powerful querying with sorting and pagination
🎯 Selective Sync - Filter what data gets synced (privacy, bandwidth, storage)
📊 Metrics & Telemetry - Track sync performance and success rates
📝 Structured Logging - Production-ready logging framework
⚡ High Performance - 50-90% faster with optimizations
🔒 Data Integrity - SHA-256 hashing and proper validation

Supported Backends #

Works With 14+ Databases #

BaaS Platforms (3)

✅ Firebase Firestore - Google's NoSQL cloud database
✅ Supabase - Open-source Firebase alternative with PostgreSQL
✅ Appwrite - Self-hosted backend-as-a-service

SQL Databases (4)

✅ PostgreSQL - Advanced open-source relational database
✅ MySQL - Popular open-source relational database
✅ MariaDB - MySQL fork with enhanced features
✅ SQLite - Embedded relational database

NoSQL Databases (5)

✅ MongoDB - Document-oriented database
✅ CouchDB - Document database with built-in sync
✅ Redis - In-memory key-value store
✅ DynamoDB - AWS managed NoSQL database
✅ Cassandra - Distributed wide-column store

API Protocols (2)

✅ REST APIs - Generic HTTP/REST backend (built-in)
✅ GraphQL - Flexible query language for APIs

Custom Backends

✅ Implement SyncBackendAdapter for any backend

✅ NEW in v1.5.0: Database adapters are now available as separate packages on pub.dev!

Available Adapter Packages:

synclayer_firebase - Firebase Firestore
synclayer_supabase - Supabase PostgreSQL
synclayer_postgres - PostgreSQL
synclayer_mongodb - MongoDB
synclayer_mysql - MySQL
synclayer_sqlite - SQLite
synclayer_redis - Redis
synclayer_appwrite - Appwrite

Why separate packages? To keep the main package lightweight and let you install only what you need.

📖 Setup guides:

Database Support Guide - Overview of all 14 databases
Database Comparison - Choose the right database
Platform Adapters Guide - Firebase, Supabase, Appwrite

Quick Start #

1. Add dependency #

dependencies:
  synclayer: ^1.5.0

2. Initialize #

Option A: REST API (default)

import 'package:synclayer/synclayer.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await SyncLayer.init(
    SyncConfig(
      baseUrl: 'https://api.example.com',
      syncInterval: Duration(minutes: 5),
      collections: ['todos', 'users'],
    ),
  );
  
  runApp(MyApp());
}

Option B: Firebase, Supabase, PostgreSQL, MongoDB, or 8+ other databases

✅ NEW in v1.5.0: Install adapters directly from pub.dev!

Quick Install:

# Firebase
flutter pub add synclayer_firebase

# Supabase
flutter pub add synclayer_supabase

# PostgreSQL
flutter pub add synclayer_postgres

# MongoDB
flutter pub add synclayer_mongodb

# MySQL
flutter pub add synclayer_mysql

# SQLite
flutter pub add synclayer_sqlite

# Redis
flutter pub add synclayer_redis

# Appwrite
flutter pub add synclayer_appwrite

Then use it:

// 1. Add adapter package to pubspec.yaml
dependencies:
  synclayer: ^1.5.0
  synclayer_firebase: ^1.0.0  # For Firebase
  # OR synclayer_postgres: ^1.0.0  # For PostgreSQL
  # OR synclayer_mongodb: ^1.0.0   # For MongoDB
  # See pub.dev for all adapters

// 2. Import the adapter package
import 'package:synclayer_firebase/synclayer_firebase.dart';
// OR import 'package:synclayer_postgres/synclayer_postgres.dart';
// OR import 'package:synclayer_mongodb/synclayer_mongodb.dart';

// 3. Initialize with Firebase
await Firebase.initializeApp();
await SyncLayer.init(
  SyncConfig(
    customBackendAdapter: FirebaseAdapter(
      firestore: FirebaseFirestore.instance,
    ),
    collections: ['todos'],
  ),
);

// OR with PostgreSQL
final connection = await Connection.open(
  Endpoint(host: 'localhost', database: 'mydb', username: 'user', password: 'pass'),
);
await SyncLayer.init(
  SyncConfig(
    customBackendAdapter: PostgresAdapter(connection: connection),
    collections: ['todos'],
  ),
);

// OR with MongoDB
final db = await Db.create('mongodb://localhost:27017/mydb');
await db.open();
await SyncLayer.init(
  SyncConfig(
    customBackendAdapter: MongoDBAdapter(db: db),
    collections: ['todos'],
  ),
);

📖 Full setup guides:

Database Support Guide - All 14 databases
Database Comparison - Choose the right one
Adapter Guide - Setup instructions
Platform Adapters Guide - Firebase, Supabase, Appwrite

3. Use it #

// Save (works offline)
final id = await SyncLayer.collection('todos').save({
  'text': 'Buy milk',
  'done': false,
});

// Get
final todo = await SyncLayer.collection('todos').get(id);

// Update (same as save with id)
await SyncLayer.collection('todos').save({
  'text': 'Buy milk',
  'done': true,
}, id: id);

// Delete
await SyncLayer.collection('todos').delete(id);

// Query & Filter (NEW in v1.1.0!)
final incompleteTodos = await SyncLayer.collection('todos')
  .where('done', isEqualTo: false)
  .orderBy('priority', descending: true)
  .limit(10)
  .get();

// Watch for changes (reactive UI)
StreamBuilder(
  stream: SyncLayer.collection('todos').watch(),
  builder: (context, snapshot) {
    final todos = snapshot.data ?? [];
    return ListView.builder(
      itemCount: todos.length,
      itemBuilder: (context, i) => Text(todos[i]['text']),
    );
  },
);

How It Works #

┌─────────────┐
│  Your App   │
└──────┬──────┘
       │ save()
       ▼
┌─────────────┐     ┌──────────────┐
│   SyncLayer │────▶│ Local Storage│  (Instant)
│             │     │    (Isar)    │
└──────┬──────┘     └──────────────┘
       │
       │ (Background)
       ▼
┌─────────────┐     ┌──────────────┐
│ Sync Engine │────▶│   Backend    │  (Auto-sync)
│   + Queue   │     │     API      │
└─────────────┘     └──────────────┘

Architecture:

SyncLayer - Main API (what you use)
Collections - Data abstraction (like tables)
SyncEngine - Background processor (handles sync)
Queue Manager - Retry logic and ordering
Conflict Resolver - Handles conflicts automatically

Example App #

See the Todo App example for a complete working app with:

Offline editing
Auto-sync when online
Conflict resolution
Real-time UI updates

Backend Integration #

SyncLayer works with any backend. You need two endpoints:

// Push: Receive changes from client
POST /sync/{collection}
Body: { recordId, data, version, updatedAt }

// Pull: Send changes to client
GET /sync/{collection}?since={timestamp}
Response: [{ recordId, data, version, updatedAt }]

See backend example for a complete Node.js implementation.

Advanced Features #

Selective Sync (Sync Filters) (NEW in v1.2.0!) #

Control exactly what data gets synced to save bandwidth, storage, and ensure privacy.

Why use sync filters?

🔒 Privacy: Users don't want to download everyone's data
📱 Bandwidth: Mobile users have limited data plans
💾 Storage: Devices have limited space
🔐 Security: Multi-tenant apps need user isolation
⚖️ Legal: GDPR requires data minimization

// Multi-tenant: Only sync current user's data
await SyncLayer.init(
  SyncConfig(
    baseUrl: 'https://api.example.com',
    collections: ['todos', 'notes'],
    syncFilters: {
      'todos': SyncFilter(
        where: {'userId': currentUserId},
      ),
    },
  ),
);

// Time-based: Only sync recent data
syncFilters: {
  'todos': SyncFilter(
    since: DateTime.now().subtract(Duration(days: 30)),
  ),
}

// Bandwidth optimization: Exclude large fields
syncFilters: {
  'documents': SyncFilter(
    excludeFields: ['fullContent', 'attachments', 'thumbnail'],
  ),
}

// Or include only specific fields
syncFilters: {
  'documents': SyncFilter(
    fields: ['id', 'title', 'summary', 'createdAt'],
  ),
}

// Progressive sync: Limit initial sync size
syncFilters: {
  'todos': SyncFilter(
    limit: 50, // Only sync first 50 items
  ),
}

// Combined filters: All together
syncFilters: {
  'todos': SyncFilter(
    where: {
      'userId': currentUserId,
      'archived': false,
    },
    since: DateTime.now().subtract(Duration(days: 30)),
    limit: 100,
    excludeFields: ['attachments', 'comments'],
  ),
}

Real-world example: Todo app

final currentUserId = 'user-123';

await SyncLayer.init(
  SyncConfig(
    baseUrl: 'https://api.example.com',
    collections: ['todos', 'projects', 'tags'],
    syncFilters: {
      // Todos: Only user's active todos from last 90 days
      'todos': SyncFilter(
        where: {
          'userId': currentUserId,
          'deleted': false,
        },
        since: DateTime.now().subtract(Duration(days: 90)),
      ),
      // Projects: Only user's projects
      'projects': SyncFilter(
        where: {'userId': currentUserId},
      ),
      // Tags: Only user's tags, exclude metadata
      'tags': SyncFilter(
        where: {'userId': currentUserId},
        excludeFields: ['usage_stats', 'metadata'],
      ),
    },
  ),
);

GDPR compliance example:

syncFilters: {
  'user_data': SyncFilter(
    where: {
      'userId': currentUserId,
      'consentGiven': true, // Only sync if consent given
    },
    since: DateTime.now().subtract(Duration(days: 365)), // Data retention
    excludeFields: ['ssn', 'creditCard', 'medicalRecords'], // Privacy
  ),
}

Mobile bandwidth optimization:

syncFilters: {
  // Messages: Only recent, only essential fields
  'messages': SyncFilter(
    where: {'userId': currentUserId},
    since: DateTime.now().subtract(Duration(days: 7)),
    fields: ['id', 'text', 'senderId', 'timestamp'],
    limit: 200,
  ),
  // Media: Only thumbnails, no full resolution
  'media': SyncFilter(
    where: {'userId': currentUserId},
    fields: ['id', 'thumbnailUrl', 'type'],
  ),
}

See sync filter example for more use cases.

Query & Filtering (NEW in v1.1.0!) #

// Basic filtering
final incompleteTodos = await SyncLayer.collection('todos')
  .where('done', isEqualTo: false)
  .get();

// Multiple conditions
final urgentTodos = await SyncLayer.collection('todos')
  .where('done', isEqualTo: false)
  .where('priority', isGreaterThan: 5)
  .get();

// String operations
final searchResults = await SyncLayer.collection('todos')
  .where('text', contains: 'urgent')
  .get();

// Sorting
final sortedTodos = await SyncLayer.collection('todos')
  .orderBy('priority', descending: true)
  .orderBy('createdAt')
  .get();

// Pagination
final page1 = await SyncLayer.collection('todos')
  .limit(10)
  .get();

final page2 = await SyncLayer.collection('todos')
  .offset(10)
  .limit(10)
  .get();

// Complex queries
final results = await SyncLayer.collection('todos')
  .where('done', isEqualTo: false)
  .where('priority', isGreaterThanOrEqualTo: 5)
  .where('userId', isEqualTo: currentUserId)
  .orderBy('priority', descending: true)
  .limit(20)
  .get();

// Reactive queries with filters
SyncLayer.collection('todos')
  .where('done', isEqualTo: false)
  .watch()
  .listen((todos) {
    print('Incomplete todos: ${todos.length}');
  });

// Array operations
final workTodos = await SyncLayer.collection('todos')
  .where('tags', arrayContains: 'work')
  .get();

// Nested fields
final userTodos = await SyncLayer.collection('todos')
  .where('user.name', isEqualTo: 'John')
  .get();

// Utility methods
final firstTodo = await SyncLayer.collection('todos')
  .where('done', isEqualTo: false)
  .first();

final count = await SyncLayer.collection('todos')
  .where('done', isEqualTo: true)
  .count();

Supported Operators:

Comparison: isEqualTo, isNotEqualTo, isGreaterThan, isLessThan, etc.
String: startsWith, endsWith, contains
Array: arrayContains, arrayContainsAny, whereIn, whereNotIn
Null: isNull, isNotNull

See query example for more details.

Custom Conflict Resolvers (NEW in v1.3.0!) #

Go beyond the built-in strategies with custom conflict resolution logic:

await SyncLayer.init(
  SyncConfig(
    baseUrl: 'https://api.example.com',
    conflictStrategy: ConflictStrategy.custom,
    customConflictResolver: (local, remote, localTime, remoteTime) {
      // Social app: Merge likes and comments
      return {
        ...remote,
        'likes': [...local['likes'], ...remote['likes']].toSet().toList(),
        'comments': [...local['comments'], ...remote['comments']],
      };
    },
  ),
);

Pre-built resolvers for common scenarios:

// Merge arrays (social apps)
customConflictResolver: ConflictResolvers.mergeArrays(['tags', 'likes'])

// Sum numbers (inventory apps)
customConflictResolver: ConflictResolvers.sumNumbers(['quantity', 'views'])

// Field-level last-write-wins (collaborative editing)
customConflictResolver: ConflictResolvers.fieldLevelLastWriteWins()

// Deep merge (nested objects)
customConflictResolver: ConflictResolvers.deepMerge()

// Max value (analytics)
customConflictResolver: ConflictResolvers.maxValue(['version', 'score'])

See custom conflict resolver example for more use cases.

Delta Sync - Partial Updates (NEW in v1.3.0!) #

Save 70-98% bandwidth by only syncing changed fields:

// Instead of sending entire document (wasteful):
await collection.save({
  'id': '123',
  'title': 'My Document',
  'content': '... 50KB of content ...',
  'done': true,  // Only this changed!
}, id: '123');

// Use delta sync - only send changed field (efficient):
await collection.update('123', {'done': true});
// Saves 98% bandwidth!

Real-world examples:

// Toggle todo completion
await collection.update(todoId, {'done': true});

// Increment view count
final doc = await collection.get(docId);
await collection.update(docId, {'views': (doc!['views'] ?? 0) + 1});

// Update user status
await collection.update(userId, {
  'status': 'online',
  'lastSeen': DateTime.now().toIso8601String(),
});

Benefits:

70-98% bandwidth reduction
Faster sync performance
Lower server costs
Better battery life
Fewer conflicts (only specific fields change)

See delta sync example for more details.

Encryption at Rest (NEW in v1.3.0!) #

Protect sensitive data with industry-standard encryption:

import 'dart:math';
import 'dart:typed_data';

// Generate secure encryption key (32 bytes for AES-256)
Uint8List generateSecureKey() {
  final random = Random.secure();
  return Uint8List.fromList(
    List.generate(32, (_) => random.nextInt(256)),
  );
}

await SyncLayer.init(
  SyncConfig(
    baseUrl: 'https://api.example.com',
    collections: ['patients', 'transactions'],
    encryption: EncryptionConfig(
      enabled: true,
      key: encryptionKey,
      algorithm: EncryptionAlgorithm.aes256GCM, // Recommended
      compressBeforeEncryption: true, // Reduce storage
    ),
  ),
);

// Data is automatically encrypted before storage
await SyncLayer.collection('patients').save({
  'name': 'John Doe',
  'ssn': '123-45-6789', // Encrypted at rest
  'diagnosis': 'Hypertension',
});

Supported algorithms:

aes256GCM - Best balance (recommended for most apps)
aes256CBC - Legacy compatibility
chacha20Poly1305 - Mobile-optimized

Use cases:

Healthcare apps (HIPAA compliance)
Finance apps (PCI DSS compliance)
Legal apps (attorney-client privilege)
Enterprise apps (SOC2, ISO 27001)

IMPORTANT: Store encryption keys securely using flutter_secure_storage or platform keychain. Never hardcode keys!

See encryption example for complete guide.

Batch Operations #

// Save multiple
await SyncLayer.collection('todos').saveAll([
  {'text': 'Task 1'},
  {'text': 'Task 2'},
  {'text': 'Task 3'},
]);

// Delete multiple
await SyncLayer.collection('todos').deleteAll([id1, id2, id3]);

Manual Sync #

// Trigger sync immediately (e.g., pull-to-refresh)
await SyncLayer.syncNow();

Conflict Resolution #

await SyncLayer.init(
  SyncConfig(
    baseUrl: 'https://api.example.com',
    conflictStrategy: ConflictStrategy.lastWriteWins, // Default
    // or: ConflictStrategy.serverWins
    // or: ConflictStrategy.clientWins
  ),
);

Event Monitoring #

SyncLayerCore.instance.syncEngine.events.listen((event) {
  switch (event.type) {
    case SyncEventType.syncStarted:
      print('Sync started');
      break;
    case SyncEventType.syncCompleted:
      print('Sync completed');
      break;
    case SyncEventType.conflictDetected:
      print('Conflict in ${event.collectionName}');
      break;
  }
});

Metrics & Monitoring #

// Get current sync metrics
final metrics = SyncLayer.getMetrics();
print('Success rate: ${(metrics.successRate * 100).toStringAsFixed(1)}%');
print('Average sync: ${metrics.averageSyncDuration?.inMilliseconds}ms');
print('Conflicts: ${metrics.conflictsDetected}');

// Configure custom metrics handler
SyncLayer.configureMetrics(
  customHandler: (event) {
    // Send to your analytics service
    analytics.track(event.type, event.data);
  },
);

Logging Configuration #

// Configure logging for production
SyncLayer.configureLogger(
  enabled: !kReleaseMode, // Disable in release mode
  minLevel: LogLevel.warning, // Only warnings and errors
  customLogger: (level, message, error, stackTrace) {
    // Send errors to crash reporting
    if (level == LogLevel.error) {
      crashlytics.recordError(error, stackTrace);
    }
  },
);

Known Limitations #

This is a beta release. Known issues:

⚠️ Pull sync requires explicit collections configuration
⚠️ Example backend uses in-memory storage (not production-ready)
⚠️ Basic authentication (token-based only)

See CHANGELOG for details.

Performance #

v0.2.0-beta.7 Improvements:

90% less memory usage for large datasets (pagination)
50-80% faster queries (database indexes)
70% faster bulk operations (batch processing)
SHA-256 data integrity verification
30-second operation timeouts

Roadmap #

✅ Production-grade logging and metrics
✅ Database indexes for performance
✅ Pagination for large datasets
✅ Batch operations
✅ Data validation
✅ Custom conflict resolvers ⭐ NEW in v1.3.0
✅ Delta sync (partial updates) ⭐ NEW in v1.3.0
✅ Encryption at rest ⭐ NEW in v1.3.0
❌ WebSocket support for real-time sync
❌ Migration tools

vs Other Solutions #

Feature	SyncLayer	Drift	Firebase	Supabase
Offline-first	✅	✅	❌	❌
Backend agnostic	✅	✅	❌	❌
Auto-sync	✅	❌	✅	✅
Conflict resolution	✅	❌	✅	✅
Queue management	✅	❌	✅	✅
Custom backend	✅	✅	❌	❌

SyncLayer = Drift's offline-first + Firebase's auto-sync + Your own backend

Contributing #

Issues and PRs welcome! See CONTRIBUTING.md.

License #

MIT License - see LICENSE file.

Support #

📖 Complete API Reference
🎯 Sync Filters Guide - Control what data gets synced
🚀 Quick Start: Sync Filters - 5-minute tutorial
🔄 Migration Guide v1.2.0 - Upgrade from v1.1.0
🔌 Platform Adapters Guide - Firebase, Supabase, Appwrite
📖 Documentation
🐛 Issues
💬 Discussions
🤝 Contributing

Made with ❤️ by Hostspica

synclayer 1.5.0 synclayer: ^1.5.0 copied to clipboard

Metadata