Remote Caching

A lightweight, flexible, and persistent cache layer for remote API calls in Flutter.
Avoid redundant network calls. Boost performance. Cache smartly.

A lightweight yet powerful Flutter package for caching asynchronous remote calls locally using SQLite — with full support for expiration, serialization, and custom deserializers.

🧠 Save your API responses. 🔁 Avoid unnecessary calls. ⚡ Go fast. 💡 Stay clean.

✨ Features #

• ✅ Automatic caching of remote data
• ⏳ Configurable expiration duration per call
• 🔄 Manual cache invalidation (by key or all)
• 💾 SQLite-powered persistent cache
• 🧩 Generic support for any type (Map, List, custom models...)
• 🧰 Custom fromJson() support for deserializing complex types
• 📊 Cache statistics API
• 🧪 Test-friendly and easy to debug (verboseMode)

❗ Why RemoteCaching? #

• 🔍 You need structured, persistent caching for remote API calls
• 💡 You want control over serialization and expiration
• 🧼 You don’t want to reinvent the wheel each time you need simple cache logic

🚀 Getting Started #

Add to your pubspec.yaml:

flutter pub add remote_caching

Then run:

flutter pub get

🛠️ Usage #

1. Initialize the cache system #

await RemoteCaching.instance.init(
  defaultCacheDuration: Duration(hours: 1), // Optional
  verboseMode: true, // Optional: see RemoteCaching logs in your console, default is enabled only in debug mode
);

2. Cache a remote API call #

final user = await RemoteCaching.instance.call<UserProfile>(
  'user_profile',
  cacheDuration: Duration(minutes: 30), // Optional
  remote: () async => await fetchUserProfile(),
  fromJson: (json) => UserProfile.fromJson(json as Map<String, dynamic>), // Optional if the object have a fromJson method or is not a List
);

Or if you want to cache a remote call with a dynamic key:

final pizza = await RemoteCaching.instance.call<Pizza>(
  'pizza_${pizzaName}',
  cacheDuration: Duration(minutes: 30), // Optional
  remote: () async => await fetchPizza(pizzaName),
  fromJson: (json) => Pizza.fromJson(json as Map<String, dynamic>), // Optional if the object have a fromJson method or is not a List
);

• The first call fetches from remote and caches the result.
• Subsequent calls within 30 minutes return the cached value.
• After expiration, the remote is called again and cache is updated.

3. Force refresh #

await RemoteCaching.instance.call(
  'user_profile',
  forceRefresh: true,
  remote: () async => await fetchUserProfile()
);

4. Clear cache #

await RemoteCaching.instance.clearCache(); // All
await RemoteCaching.instance.clearCacheForKey('user_profile'); // By key

5. Get cache statistics #

final stats = await RemoteCaching.instance.getCacheStats();
print(stats); // CachingStats(totalEntries: 3, totalSizeBytes: 1234, expiredEntries: 1)

⚠️ Serialization Note (for Lists)

If you want to cache a list of objects, you need to provide a fromJson function.

## 📦 Example

A full example is available in the [`example/`](example/) directory. It demonstrates how to cache results from the [Agify.io](https://agify.io) API and display them in a Flutter app.

---

## 📚 API Reference

### RemoteCaching

| Method | Description |
|--------|-------------|
| `init({Duration? defaultCacheDuration, bool verboseMode = false})` | Initialize the cache system |
| `call<T>(String key, {required Future<T> Function() remote, Duration? cacheDuration, bool forceRefresh = false, T Function(Object? json)? fromJson})` | Cache a remote call |
| `clearCache()` | Clear all cache |
| `clearCacheForKey(String key)` | Clear cache for a specific key |
| `getCacheStats()` | Get cache statistics |
| `dispose()` | Dispose the cache system |

---

## ❓ FAQ

**Q: What happens if serialization or deserialization fails?**  
A: The error is logged, the cache is ignored, and the remote call is used. Your app will never crash due to cache errors.

**Q: Can I use my own model classes?**  
A: Yes! Just provide a fromJson function and ensure your model supports toJson when caching. The package relies on jsonEncode / jsonDecode under the hood.

**Q: Does it work offline?**  
A: Cached data is available offline until it expires or is cleared.

**Q: Does it work on all platforms?**  
A: We use [sqlite3](https://pub.flutter-io.cn/packages/sqflite) with [sqflite_common_ffi](https://pub.flutter-io.cn/packages/sqflite_common_ffi) to support all platforms. Refer to the packages docs for more information.

---

## 🤝 Contributing

Contributions, issues and feature requests are welcome! Feel free to check [issues page](https://github.com/eliatolin/remote_caching/issues) or submit a pull request.

1. Fork the repo
2. Create your feature branch (`git checkout -b feature/my-feature`)
3. Commit your changes (`git commit -am 'Add new feature'`)
4. Push to the branch (`git push origin feature/my-feature`)
5. Create a new Pull Request

---

_Made with ❤️ by [Eliatolin](https://github.com/eliatolin)_