sync_vault 0.0.3

An offline-first data synchronization layer for Flutter apps. Automatically queues API requests when offline and syncs with exponential backoff.

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.

0.0.3 - 2025-12-27

Added

• Event Bus System:

  • New SyncEvent class for tracking individual action lifecycles
  • SyncEventStatus enum: queued, started, success, failed, deadLetter
  • SyncVault.instance.onEvent stream for listening to all events
  • SyncVault.instance.eventsFor(id) for filtering events by action ID
  • SyncVault.instance.eventsForKey(key) for filtering by idempotency key

• Flutter UI Widgets:

  • SyncVaultListener - Widget that listens to events and calls callbacks
  • SyncStatusBuilder - Widget that rebuilds on sync status changes
  • SyncEventBuilder - Widget that rebuilds on specific action events

Fixed

• Race Condition: Worker now properly prevents duplicate executions when triggered by both "add action" and "network restore" events simultaneously

Changed

• Worker now emits SyncEvent for each action state change (started, success, failed, deadLetter)
• _handleDeadLetter callback now receives events through the event bus as well

---

0.0.2 - 2025-12-26

Added

• SQLite Storage Adapter:
  • New SqfliteStorageAdapter class for SQLite-based persistence
  • Full CRUD operations with proper JSON serialization for complex types
  • Automatic schema creation with indexed timestamp column for FIFO ordering
  • Custom database path support
  • Schema migration support for future updates

Dependencies

• Added sqflite: ^2.3.0 - SQLite database support
• Added path: ^1.9.0 - Path manipulation utilities

---

0.0.1 - 2025-12-25

Added

• Initial release of SyncVault

• Core Features:

  • SyncVault singleton client for making offline-safe HTTP requests
  • SyncAction model for representing queued requests
  • StorageAdapter abstract interface for pluggable persistence
  • HiveStorageAdapter default implementation using Hive
  • NetworkManager for connectivity monitoring via connectivity_plus
  • Worker for queue processing with retry logic

• HTTP Methods:

  • GET, POST, PUT, DELETE, PATCH support
  • Custom headers support
  • Idempotency key support

• Sync Features:

  • Automatic sync on network restoration
  • Manual sync trigger via processQueue()
  • FIFO queue processing
  • Exponential backoff with jitter
  • Configurable max retries
  • Dead letter handling for failed requests

• Observability:

  • SyncStatus stream for UI updates
  • Pending action count
  • Access to all pending actions

• Example App:

  • Complete Todo app demonstrating all features
  • Beautiful dark UI with sync status indicators
  • Optimistic UI updates

Architecture

• Clean architecture with separated layers:
  • core/ - Main business logic (SyncClient, Worker, NetworkManager)
  • data/ - Data models and storage (SyncAction, StorageAdapter)
  • utils/ - Utilities (Exceptions)

Dependencies

• dio: ^5.4.0 - HTTP client
• hive: ^2.2.3 - Local persistence
• connectivity_plus: ^6.0.0 - Network monitoring
• uuid: ^4.3.0 - Unique ID generation
• equatable: ^2.0.5 - Value equality