synq_manager 1.0.16
synq_manager: ^1.0.16 copied to clipboard
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.16 #
Fixed #
π― onInit Callback Issue: Fixed critical timing issue where onInit callbacks were not being triggered
- Implemented
_waitUntilReady()
helper method inSynqListeners
to ensure manager is fully initialized before setting up listeners - Fixed race condition where
connected
event was being emitted beforeonInit
listeners were registered - Enhanced all listener methods (onEvent, onCreate, onUpdate, onDelete, onError) to wait for manager readiness
- Improved
onInit
reliability by ensuring callback is triggered with all existing data once manager is ready - Better timing control prevents missing initialization events during app startup
Enhanced #
β‘ Listener Reliability: Improved event listener setup and management
- All listeners now wait for SynqManager to be fully ready before registration
- Eliminated timing-dependent failures in event subscription
- More robust initialization flow ensures consistent callback behavior
- Better separation of concerns between manager initialization and listener setup
1.0.15 #
Fixed #
π§ User Account Migration Loop: Fixed critical bug causing infinite sync loops during offline data upload
- Fixed missing user ID persistence in
_uploadLocalData()
function that caused endless account migration cycles - Added
cloudUserId
parameter to_uploadLocalData()
method to ensure user ID is properly stored after successful uploads - Enhanced account conflict resolution to persist user ID in all scenarios (
keepLocalData
action) - Improved account scenario detection to prevent false positive offline data upload triggers
Enhanced #
π Sync Reliability: Improved account migration handling and prevented unnecessary sync repetitions
- Better user ID tracking across different account scenarios (guest sign-in, offline data upload, account switch)
- Enhanced logging and metadata for account scenario debugging
- Optimized sync flow to avoid redundant migration checks after successful user ID persistence
1.0.14 #
Fixed #
π Infinite Push Loop: Fixed critical bug where successful push operations caused infinite sync loops
- Added timestamp buffer (1 second) in
_scanForUntrackedChanges()
to prevent recently synced items from being detected as new changes - Enhanced
_persistSyncTimestamp()
to clear pending changes after successful timestamp persistence - Improved
_pushToCloud()
to immediately remove pushed keys from pending changes upon successful completion - Modified sync strategy to exclude successfully pushed items from remote data application, preventing unnecessary re-writes
- Added
excludeKeys
parameter to_applyRemoteChanges()
to avoid re-applying data that was just pushed - Enhanced
StorageService
withputWithTimestamp()
method for sync operations that preserve original timestamps
Enhanced #
β‘ Sync Performance: Significantly improved sync efficiency and reliability
- Eliminated redundant local storage writes after successful push operations
- Prevented timestamp conflicts between local and remote data during sync cycles
- Optimized pending changes tracking to avoid false positives
- Better separation between user-initiated changes and sync-related operations
1.0.13 #
Changed #
π Code Structure Refactoring: Improved code organization and API structure
- Extracted cloud callback types to separate
CloudCallbacks
model file - Moved
SyncResult
andSyncStats
classes to dedicated model files for better maintainability - Enhanced type safety with proper CloudFetchResponse structure including
cloudUserId
field - Updated example app to demonstrate new CloudFetchResponse format
- Improved export structure in main library file for better API access
Added #
β¨ Enhanced Cloud Integration: New CloudFetchResponse structure with user identity support
- Added
cloudUserId
field to CloudFetchResponse for better user tracking - Enhanced metadata support in cloud operations
1.0.12 #
Fixed #
π§ Delete Sync Issue: Fixed critical bug where deleted items were not being synced to cloud
- Changed delete operation from hard delete to soft delete (marks items as
deleted: true
) - Added automatic hard delete after successful cloud sync to maintain storage efficiency
- Ensures all delete operations are properly synchronized with cloud services
Added #
ποΈ Hard Delete Support: Added hardDelete()
method for permanent local deletion
- Available in both
SynqManager
andStorageService
- Bypasses sync and removes items immediately from local storage
- Should be used with caution as it doesn't sync deletions to cloud
Enhanced #
β‘ Sync Performance: Improved sync service to handle deleted items correctly
- Deleted items are now included in pending changes and synced to cloud
- After successful cloud sync, deleted items are automatically hard deleted locally
- Better storage space management with automatic cleanup of synced deletions
1.0.11 #
Added #
- π Metadata Storage: Implemented metadata storage for sync timestamps in SyncService
- π Empty SyncData Support: Enhanced SynqManager and SyncEvent with empty SyncData support
- π― Recent Data Retrieval: Improved pending changes retrieval in SyncService to include recent data
Fixed #
- π§ Dependency Management: Reverted hive_plus_secure dependency to stable version 1.1.14 from git reference
- π Debug Logging: Replaced print statements with debugPrint for better error handling and logging consistency
- π§Ή Code Cleanup: Removed debug print statements from storage event handling
Enhanced #
- β‘ Storage Service: Updated StorageService event handling for better performance
- π‘οΈ Error Management: Improved error handling throughout SynqManager core functionality
- π Sync Performance: Enhanced sync service with better metadata tracking and recent data handling
1.0.10 #
Added #
- π DocumentSerializable Support: Added support for DocumentSerializable interface to SynqManager
- π Enhanced Serialization: Improved data serialization capabilities for better document handling
- π§ Storage Service Enhancement: Major improvements to storage service functionality
Enhanced #
- β‘ SynqManager Core Updates: Refactored core SynqManager implementation for better performance
- π Storage Service Optimization: Streamlined storage service operations (258 additions, 272 deletions)
- π οΈ Sync Service Improvements: Enhanced sync service logic for more reliable data synchronization
- π¦ Model Updates: Simplified SyncData model implementation
- π― Example Integration: Updated example app to demonstrate new DocumentSerializable features
Technical Improvements #
- π Code Refactoring: Major refactoring across core services for better maintainability
- π API Consistency: Improved API consistency across storage and sync services
- π§Ή Code Cleanup: Removed redundant code and improved overall code quality
1.0.9 #
Fixed #
- π§ Duplicate Event Emissions: Fixed critical issue where storage events were being emitted twice
- β‘ Event Handling Optimization: Removed duplicate event emissions from storage service manual triggers
- π― Watcher-Only Events: Streamlined event system to only emit events through Hive watcher
- π Create vs Update Detection: Improved event type detection to properly distinguish between create and update operations
- π Storage Service Refactor: Cleaned up storage service event emission logic for better performance
Enhanced #
- π Single Event Source: All storage events now flow through a single, consistent watcher mechanism
- π Better Performance: Eliminated redundant event processing and improved overall system responsiveness
- π‘οΈ Reliable Event Tracking: Event listeners now receive exactly one event per operation
1.0.8 #
Fixed #
- π§ Critical Sync Logic Bug: Fixed major issue where
cloudFetchFunction
was never called - β‘ Proper Conflict Detection: Implemented correct conflict detection by fetching remote data first
- π Improved Sync Flow: Restructured sync process to properly use both
cloudFetchFunction
andcloudSyncFunction
- π Separation of Concerns:
cloudFetchFunction
now only handles data fetching,cloudSyncFunction
only handles data pushing - π Two-Phase Sync: Added separate initial sync and incremental sync modes
- π Better Pending Changes Logic: Fixed logic to only track actual pending changes, not all data
Enhanced #
- π― Cleaner Function Responsibilities: Each cloud function now has a single, well-defined responsibility
- π More Efficient Syncing: Reduced unnecessary data transfers and improved sync performance
- π‘οΈ Robust Conflict Handling: Conflicts are now properly detected and handled before data corruption
Breaking Changes #
- β οΈ CloudSyncFunction Behavior:
cloudSyncFunction
should now only handle pushing data, not conflict detection
1.0.7 #
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
andonSyncComplete
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
andtoJson
function parameters toSynqManager.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 optionalfromJson
andtoJson
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 adaptersisar_plus_flutter_libs
: Additional storage supportworkmanager
: Background task executionflutter_secure_storage
: Secure credential storageconnectivity_plus
: Network state monitoringsupabase_flutter
: Optional Supabase integrationhttp
: 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