synq_manager 1.0.16 copy "synq_manager: ^1.0.16" to clipboard
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 in SynqListeners to ensure manager is fully initialized before setting up listeners
  • Fixed race condition where connected event was being emitted before onInit 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 with putWithTimestamp() 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 and SyncStats 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 and StorageService
  • 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 and cloudSyncFunction
  • πŸ“Š 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 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
1
likes
150
points
563
downloads

Publisher

verified publisherahmetaydin.dev

Weekly Downloads

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

Repository (GitHub)
View/report issues

Documentation

API reference

License

MIT (license)

Dependencies

connectivity_plus, flutter, hive_plus_secure, isar_plus_flutter_libs, meta, path_provider, uuid, workmanager

More

Packages that depend on synq_manager