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.0.0 stable release. Battle-tested with 242+ downloads and perfect pub.flutter-io.cn 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, or client-wins
🔌 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 (NEW in v1.1.0!)
🎯 Selective Sync - Filter what data gets synced (privacy, bandwidth, storage) (NEW in v1.2.0!)
📊 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 #

• ✅ REST APIs (built-in adapter)
• ✅ Firebase Firestore (copy adapter from GitHub)
• ✅ Supabase (copy adapter from GitHub)
• ✅ Appwrite (copy adapter from GitHub)
• ✅ Custom backends (implement SyncBackendAdapter)

⚠️ Note: Platform adapters (Firebase, Supabase, Appwrite) are NOT in the pub.flutter-io.cn package.
You must copy them from the GitHub repository into your project.

Why? To keep the package lightweight and avoid forcing optional dependencies on all users.

📖 Setup guide: Platform Adapters Guide

Quick Start #

1. Add dependency #

dependencies:
  synclayer: ^1.1.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, or Appwrite

⚠️ Important: Platform adapters are NOT included in the pub.flutter-io.cn package. You must copy them from GitHub.

Quick Install (Windows PowerShell):

# Create adapters folder
New-Item -ItemType Directory -Force -Path lib\adapters

# Download Firebase adapter
Invoke-WebRequest -Uri "https://rawgit.flutter-io.cn/hostspicaindia/synclayer/main/lib/adapters/firebase_adapter.dart" -OutFile "lib\adapters\firebase_adapter.dart"

Or manually:

1. Go to GitHub adapters folder
2. Copy the adapter file (e.g., firebase_adapter.dart)
3. Paste into your project at lib/adapters/firebase_adapter.dart

Then use it:

// 1. Add platform package to pubspec.yaml
dependencies:
  synclayer: ^1.1.0
  cloud_firestore: ^5.7.0  # For Firebase

// 2. Import the adapter you copied
import 'adapters/firebase_adapter.dart';

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

📖 Full setup guide: Platform Adapters Guide

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.

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
• ❌ Encryption support
• ❌ WebSocket support for real-time sync
• ❌ Migration tools

vs Other Solutions #

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