image_cache_sync 0.0.1

A lightweight Flutter package for caching network images locally with offline support and smart sync using update timestamps.

image_cache_sync

A lightweight Flutter package for caching network images locally with offline support and smart synchronization using update timestamps.

This package is designed to efficiently download, store, and reuse images while keeping them in sync with backend updates.

---

🚀 Features

• 📥 Download and cache images locally
• 💾 Persistent storage using Hive
• 🔄 Smart sync using updatedAt timestamps
• 📦 Bulk image handling (pagination friendly)
• 📴 Offline support (works without internet after first load)
• 🧹 Cache management (clear/delete images)
• 🎨 Easy-to-use Flutter widget (CachedImageView)
• ⚡ Efficient network usage (downloads only when needed)

---

🧠 Why use this package?

In many apps, images are:

• Loaded repeatedly from network ❌
• Not available offline ❌
• Not synced with backend updates ❌

This package solves that by:

• Caching images locally
• Reusing cached images
• Updating only when required

---

📦 Installation

Add this to your pubspec.yaml:

dependencies:
  image_cache_sync: ^0.0.1

Then run:

flutter pub get

---

🧪 Usage

🔹 1. Display Image (Recommended)

CachedImageView(
  id: "1",
  url: "https://your-api.com/image.jpg",
  updatedAt: DateTime(2024, 1, 1),
)

---

🔹 2. Fetch Image Manually

final manager = ImageCacheManager();

final image = await manager.fetchImage(
  id: "1",
  url: "https://your-api.com/image.jpg",
  updatedAt: DateTime(2024, 1, 1),
);

print(image.localPath);

---

🔹 3. Bulk Sync (Pagination Friendly)

final manager = ImageCacheManager();

final images = await manager.syncImages([
  ImageItem(
    id: "1",
    url: "https://your-api.com/image.jpg",
    localPath: "",
    updatedAt: DateTime(2024, 1, 1),
  ),
]);

---

🔹 4. Clear Cache

final manager = ImageCacheManager();

await manager.clearAll();

---

🔹 5. Get Cached Image Only

final cached = await manager.getCached("1");

---

🧠 How It Works

Step 1: Check Cache

The package checks if the image already exists locally.

Step 2: Compare Timestamp

It compares updatedAt from API with cached value.

Step 3: Decide Action

Condition	Action
Not cached	Download image
Cached + same updatedAt	Use local image
Cached + updatedAt changed	Re-download

Step 4: Store Data

• Image file → local storage
• Metadata → Hive database

---

📱 Pagination Support

This package works seamlessly with paginated APIs.

• Sync happens per item (not per page)
• Only current page needs syncing
• Efficient for large datasets

---

📴 Offline Support

Once images are cached:

• No internet required
• Images load instantly
• Works even in airplane mode

---

🧹 Cache Management

Clear all cached data

await manager.clearAll();

This will:

• Remove all images from storage
• Clear Hive database

---

🎯 Use Cases

• 🛒 E-commerce apps
• 📰 News apps
• 📸 Gallery apps
• 📱 Social media feeds
• 📡 Offline-first apps

---

⚠️ Important Notes

• updatedAt must come from your API
• Changing updatedAt triggers re-download
• Ensure id is unique for each image
• URL is required for sync functionality

---

📊 Example Flow

1. App loads image → downloads & caches
2. App restarts → loads from cache
3. Backend updates image → updatedAt changes
4. Package detects change → re-downloads

---

🔮 Future Improvements (Planned)

• Placeholder & error widgets
• Retry mechanism
• Cache size control
• Performance optimizations

---

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

---

📄 License

MIT License