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 logs in your console
);

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

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

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

📦 Example #

A full example is available in the example/ directory. It demonstrates how to cache results from the Agify.io API and display them in a Flutter app.

📚 API Reference #

RemoteCaching #

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

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 with 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 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