synq_manager 1.0.7

A powerful synchronization manager for Flutter apps with secure local storage, real-time state management, and background cloud sync capabilities.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.0.7 - 2025-09-24

Added

• 🚀 Cloud Sync Event Tracking: Added detailed event emissions for cloud sync operations
• ☁️ CloudSyncFunction Events: cloudSyncStart, cloudSyncSuccess, cloudSyncError events
• 📡 CloudFetchFunction Events: cloudFetchStart, cloudFetchSuccess, cloudFetchError events
• 📊 Enhanced Metadata: Cloud sync/fetch events include detailed metadata (counts, error info, etc.)
• 🎯 Socket.io Style Cloud Events: New listener methods onCloudSyncStart(), onCloudSyncSuccess(), etc.
• 🛡️ Detailed Error Information: Cloud sync errors now include operation context and metadata
• 📋 Example Integration: Updated example app to demonstrate cloud sync event handling

Enhanced

• ⚡ Real-time Cloud Operation Tracking: Users can now monitor cloud sync progress in real-time
• 🎨 Better User Experience: Apps can show specific status for cloud operations ("Pushing to cloud...", etc.)
• 🔍 Debugging Support: Enhanced error reporting for cloud sync troubleshooting

1.0.6 - 2025-09-24

Added

• 🚀 Socket.io Style Event Listeners: Added Socket.io-like event handling with intuitive API
• ✨ Builder Pattern Support: Quick setup with fluent onInit().onCreate().onUpdate().start() pattern
• 🎯 Granular Event Handling: Separate callbacks for onInit, onCreate, onUpdate, onDelete events
• 📡 Real-time Data Streaming: onInit provides all data, other events provide only changed data
• 🔄 Sync State Management: Built-in onSyncStart and onSyncComplete event handlers
• 🛡️ Error Handling: Dedicated onError callback for better error management
• 🌐 Connection State: onConnectionChange for network connectivity monitoring
• 📋 Comprehensive Documentation: Added detailed usage guide for Socket.io style API

Enhanced

• 💡 Developer Experience: More intuitive API similar to Socket.io for web developers
• ⚡ Performance: Optimized event handling with direct data access instead of full reloads
• 🔧 Flexibility: Support for both traditional stream-based and Socket.io style event handling

Examples

• 📚 Updated Example App: Demonstrates Socket.io style usage with real-time note management
• 📖 Usage Guide: Created comprehensive guide for Socket.io style implementation

1.0.5

Added

• 🔧 Generic Type Serialization: Added fromJson and toJson function parameters to SynqManager.getInstance()
• 📦 Custom Object Support: Improved support for complex custom data types with proper JSON serialization/deserialization
• 🛠️ Type-Safe Serialization: Enhanced type safety for generic types T through configurable serialization functions

Changed

• ⚡ Breaking Change: SynqManager.getInstance() now accepts optional fromJson and toJson parameters for custom object serialization
• 📝 Updated Documentation: Enhanced README and example documentation with serialization function usage examples

1.0.4

Enhanced

• 🚀 Initial Sync Improvement: First-time connection now automatically syncs all local data to cloud
• 📤 Complete Data Upload: When _lastSyncTimestamp == 0, all existing local data is included in the initial sync
• 🔄 Better Sync Logic: Improved sync behavior for first-time users and fresh installations

1.0.3

• new structure

1.0.2

Changed

• 📱 Platform Support: Limited to Android and iOS only due to WorkManager dependency requirements
• 🧹 Removed desktop and web platform files to reduce package size
• 📝 Updated documentation to reflect mobile-only support

Removed

• 🗑️ Linux, macOS, Windows, and Web platform support
• 🗑️ Desktop-specific configuration files

1.0.1

Fixed

• 📝 Updated documentation and examples
• 🐛 Minor bug fixes and improvements
• ✅ Package validation improvements

1.0.0

Added

• 🎉 Initial release of SynQ Manager
• ⚡ Offline-first synchronization layer for Flutter applications
• 🔀 Real-time and configurable sync policies
• 👤 Guest mode support with account upgrade capability
• 🔄 Background synchronization using WorkManager
• 🔌 Backend-agnostic architecture:
  • CloudAdapter interface for any backend implementation
  • No built-in backend dependencies - complete freedom of choice
  • Examples for REST API, Supabase, Firebase, and more
• 💾 Local storage support:
  • Hive implementation with type adapters
  • Generic LocalStore interface for other storage engines
• ⚔️ Intelligent conflict resolution:
  • Built-in strategies (local wins, remote wins, newer wins, prompt, merge)
  • Custom conflict resolver interface
  • Automatic conflict detection based on versions and timestamps
• 🎯 Type-safe APIs:
  • Generic support for any data model
  • Strongly typed interfaces throughout
  • SyncCacheModel base class for easy integration
• 🧪 Comprehensive testing:
  • Unit tests for all core components
  • Mock implementations for testing
  • Example app demonstrating all features
• 📊 Real-time monitoring:
  • Sync status streams
  • Conflict event streams
  • Network connectivity tracking
• 🚀 Production-ready features:
  • Error handling and retry logic
  • Detailed logging with configurable levels
  • Background task scheduling
  • Memory-efficient data streaming

Technical Features

• Mobile platform support: iOS and Android (WorkManager requirement)
• Background sync: Reliable synchronization even when app is closed
• Network awareness: Automatic sync when connectivity is restored
• Data integrity: Version-based conflict detection and resolution
• Scalable architecture: Modular design for easy extension
• Performance optimized: Efficient change tracking and delta sync

Dependencies

• hive: Local storage with type adapters
• isar_plus_flutter_libs: Additional storage support
• workmanager: Background task execution
• flutter_secure_storage: Secure credential storage
• connectivity_plus: Network state monitoring
• supabase_flutter: Optional Supabase integration
• http: HTTP client for REST APIs

Documentation

• Complete README with quick start guide
• API documentation with examples
• Platform-specific setup instructions
• Testing guidelines and examples
• Architecture overview and best practices

Example App

• Note-taking app demonstrating all features
• Guest mode and account upgrade flow
• Real-time sync with conflict resolution
• Background sync demonstration
• Production-ready code patterns

[Unreleased]

Planned Features

• 📱 Enhanced mobile platform support
• 🔄 Incremental sync optimizations
• 📊 Analytics and metrics collection
• 🌐 GraphQL adapter support
• 💾 Isar storage adapter
• 🔌 Additional cloud service adapters
• 🎨 UI components for common sync patterns