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

Feature	Standard (http/dio)	Offline Queue Pro
Offline Handling	Throws Exception / Fails	Automatically Queues
Retry Logic	Manual Implementation	Automatic Exponential Backoff
Persistence	Lost on App Close	Persisted in Local DB
Duplicates	Risk of double execution	Fingerprinting / Debouncing
UX	Shows "No Connection" error	Seamless "Action Captured" experience

🧩 Edge Case Handling

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).
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.
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.
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.
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.