dio_cache_plus 2.1.0

Enhanced Dio caching interceptor with per-request control, conditional caching, and expiration.

Changelog

All notable changes to Dio Cache Plus will be documented in this file.

2.1.0 2026-Oct-31

No breaking changes. Existing cached data stays valid after upgrading.

Fixed

• A throwing isErrorResponse callback no longer hangs the request; the response is returned and not cached
• Creating the interceptor more than once no longer throws Bad state: Future already completed
• Requests with FormData, stream or other non-JSON bodies no longer hang forever (even with caching disabled); they are never cached, saved or deduplicated
• Query parameters that aren't JSON values (e.g. DateTime) no longer break cache key generation
• Failed requests no longer raise an uncaught async error
• Force refresh (invalidateCache) now waits for the old entry to be removed before checking the cache
• HiveCacheManager initialization failures no longer leave later calls waiting forever; the next call retries
• removeConditionalCachingData no longer iterates the box while deleting from it, and a throwing matcher skips that entry instead of aborting

Added

• Every response passing through the interceptor now has a standard Cache-Status header (RFC 9211), e.g. dio_cache_plus; hit; ttl=240 or dio_cache_plus; fwd=uri-miss; stored, and cached responses get an Age header (RFC 9111). Upstream Cache-Status/Age values are preserved; the original Date header is never changed
• Optional cacheManager parameter to supply a custom SanitizerCacheManager (now exported)
• resetInstance() (visible for testing) to discard the singleton

Documentation

• getCacheData() requires the full URL, including the Dio baseUrl
• Static methods wait until the interceptor has been created

2.0.6 2025-Dec-16

Added

• Added getCacheData() to fetch cached responses without making a network call.
• Added saveResponse option to persist responses with a configurable expiry, even when caching is disabled.

2.0.5 2025-Dec-04

Added

• Added logs in debug mode

2.0.4 2025-Dec-03

Fixed

• Fixed HiveCacheManager init to avoid duplicate adapter registration

2.0.3 2025-Nov-04

Fixed

• Query parameters extraction - Properly merge query parameters from both URL string and request options
• Conditional rule matching - Use complete query parameters for accurate request pattern matching
• Cache consistency - Ensure parameterized requests are correctly identified for caching rules

2.0.2 2025-Nov-03

Added

• Conditional cache data removal - New removeConditionalCachingData() method to remove cached data based on request patterns

2.0.1 2025-Oct-28

Optimizations

• Skip caching when validity duration is zero or null
• Prevent duplicate cache overwriting from cached responses
• Preserve extra map reference in request options

2.0.0 2025-Oct-27

🚀 Major Enhancements

• Dynamic function support for duration and expiry calculations
  • durationFn parameter for dynamic duration calculation at cache time
  • expiryFn parameter for dynamic expiry calculation at cache time
• Factory constructors for ConditionalCacheRule for better type safety
• Enhanced CacheOptionsExtension with type-safe methods
• RequestDetails class for better type safety in condition matching
• Comprehensive test suite with 100% test coverage for all major features

⚠️ Breaking Changes

• RequestMatcher signature now uses RequestDetails object instead of separate parameters
  • Old: (String requestUrl, Map<String, dynamic> queryParameters) => ...
  • New: (RequestDetails request) => request.url.contains(...)
• Conditional caching API now requires ConditionalCacheRule objects
  • Old: addConditionalCaching(key, condition, duration)
  • New: addConditionalCaching(key, ConditionalCacheRule.duration(...))
• Per-request caching methods are now type-specific
  • Old: setCaching(enableCache: true, duration: ...)
  • New: setCachingWithDuration(enableCache: true, duration: ...)

For detailed migration instructions, see Migration Guide

🔧 Improvements

• Enhanced cache expiry calculation to happen at storage time for precise timing
• Improved caching logic precedence with more intuitive rule evaluation
• Better error handling throughout the interceptor
• Comprehensive test coverage ensuring reliability and stability

1.0.2 2025-Aug-16

Fixed

• Cache invalidation issues with force refresh
• Request deduplication edge cases
• Hive storage initialization race conditions

1.0.1 2025-Aug-15

Fixed

• Package publishing issues
• Documentation formatting and examples

1.0.0 2025-Aug-15

Added

• Initial stable release with all core features
• Conditional caching rules system
• Request deduplication for identical concurrent requests
• Hive-based persistent storage
• Per-request cache control via Options extension
• Force refresh capability

0.0.1 2025-Aug-14

Added

• Initial development release
• Basic caching interceptor functionality
• Foundation for conditional caching