Flutter Offline Queue Pro 🚀 #

A production-grade, offline-first networking layer for Flutter. Capture API calls when connectivity is lost and automatically execute them when the internet returns.

Similar to how Uber, WhatsApp, and Instagram handle actions, flutter_offline_queue_pro ensures that user actions like likes, comments, bookings, and payments are never lost due to flaky network conditions.

✨ Features #

• 📶 Smart Connectivity Detection: Uses connectivity_plus combined with real internet reachability checks.
• 📦 Pluggable Storage:
  • Isar (Default - High performance)
  • Hive (Lightweight backup)
  • Custom Storage Adapter support.
• 🔄 Advanced Retry System:
  • Exponential backoff.
  • Configurable retry limits and intervals.
• ⚡ Queue Management:
  • Priority-based execution (High, Normal, Low).
  • Request fingerprinting to prevent duplicates (Debouncing).
  • Manual triggers, cancel specific requests, and clear queue.
• 🔐 Authentication Handling: Automatically pauses the queue on 401 errors, allowing token refresh before resuming.
• 📎 Full HTTP Support: GET, POST, PUT, PATCH, DELETE + Multipart/form-data support.
• 📊 Real-time Progress: Stream based progress tracking and queue status updates.

🚀 Quick Start #

1. Initialize the Queue #

Initialize the queue in your main() or at the start of your app.

await OfflineQueue.init(
  baseUrl: "https://api.example.com",
  retryLimit: 5,
  retryInterval: Duration(seconds: 5),
  debug: true, // Enable logging
);

2. Capture Actions #

Replace your standard HTTP calls with OfflineQueue methods.

// Simple POST request
await OfflineQueue.post(
  "/like", 
  body: {"post_id": 12},
  priority: OfflinePriority.high,
);

// Request with headers (Auth tokens are handled automatically via provider)
await OfflineQueue.get("/profile");

🛠 Advanced Usage #

Custom Auth Handling #

Supply an authHeaderProvider and onTokenExpired callback during initialization.

await OfflineQueue.init(
  baseUrl: "https://api.example.com",
  authHeaderProvider: () async => {
    'Authorization': 'Bearer ${await getSavedToken()}',
  },
  onTokenExpired: () async {
    final success = await refreshToken();
    return success; // If true, the queue resumes and retries the failed request
  },
);

Pluggable Storage #

By default, Isar is used. You can switch to Hive or your own:

await OfflineQueue.init(
  baseUrl: "...",
  storage: HiveStorage(), // Use Hive instead of Isar
);

Monitoring the Queue #

// Get number of pending requests
int count = await OfflineQueue.pendingCount;

// Listen to sync progress
OfflineQueue.progressStream.listen((progress) {
  print("Syncing: ${(progress * 100).toStringAsFixed(0)}%");
});

// Listen to status changes
OfflineQueue.statusStream.listen((status) {
  print("Queue is ${status.name}");
});

📊 Comparison vs Normal HTTP/Dio #

🧩 Edge Case Handling #

1. Duplicate Prevention: Every request generates a unique fingerprint (SHA-256) based on method, URL, and body. If a request is already in the queue, identical subsequent requests are ignored (debouncing).
2. App Restarts: Since requests are stored in Isar/Hive, they persist even if the app or device restarts. The queue initializes and checks for pending tasks on startup.
3. Partial Success: If a sync session is interrupted (e.g., network drops again), successfully completed requests are removed, while failed ones stay in the queue with an incremented retry counter.
4. 401 Unauthorized: The queue intelligently pauses when it encounters an auth error. This prevents "hammering" the server with unauthorized requests while your app refreshes the token.
5. Multipart/Large Files: Supports file path storage for large uploads. Instead of storing the whole file in the DB, it stores the path and reads it during execution.

📂 Folder Structure #

lib/
 ├── flutter_offline_queue_pro.dart (Main Facade)
 └── src/
      ├── core/
      │    ├── queue_manager.dart (Orchestrator)
      │    ├── queue_worker.dart  (Execution logic)
      ├── storage/
      │    ├── queue_storage.dart (Interface)
      │    ├── isar_storage.dart  (Isar Implementation)
      │    └── hive_storage.dart  (Hive Implementation)
      ├── models/
      │    ├── offline_request.dart
      │    ├── priority.dart
      │    └── retry_policy.dart
      ├── services/
      │    └── connectivity_service.dart
      └── utils/
           ├── fingerprinter.dart
           └── logger.dart

📝 License #

This project is licensed under the MIT License - see the LICENSE file for details.