pub package codecov

Dio HTTP cache interceptor with multiple stores respecting HTTP directives (or not).

HTTP directives:

Cache triggers ETag
Cache freshness Age
max-age (Cache-Control)
max-stale (Cache-Control)
min-fresh (Cache-Control)
Request date (added by interceptor)
Response date (added by interceptor)
Cache commutators no-cache (Cache-Control)
no-store (Cache-Control request & response)


  • BackupCacheStore: Combined store with primary and secondary.
  • DbCacheStore: Cache with database (Drift) Get it.
  • FileCacheStore: Cache with file system (Does nothing on web platform) Get it.
  • HiveCacheStore: Cache using Hive package (available on all platforms) Get it.
  • ObjectBoxCacheStore: Cache using ObjectBox package (no web support) Get it.
  • SembastCacheStore: Cache using Sembast package Get it.
  • MemCacheStore: Volatile cache with LRU strategy.


import 'package:dio_cache_interceptor/dio_cache_interceptor.dart';

// Global options
final options = const CacheOptions(
  // A default store is required for interceptor.
  store: MemCacheStore(),

  // All subsequent fields are optional.
  // Default.
  policy: CachePolicy.request,
  // Returns a cached response on error but for statuses 401 & 403.
  // Also allows to return a cached response on network errors (e.g. offline usage).
  // Defaults to [null].
  hitCacheOnErrorExcept: [401, 403],
  // Overrides any HTTP directive to delete entry past this duration.
  // Useful only when origin server has no cache config or custom behaviour is desired.
  // Defaults to [null].
  maxStale: const Duration(days: 7),
  // Default. Allows 3 cache sets and ease cleanup.
  priority: CachePriority.normal,
  // Default. Body and headers encryption with your own algorithm.
  cipher: null,
  // Default. Key builder to retrieve requests.
  keyBuilder: CacheOptions.defaultCacheKeyBuilder,
  // Default. Allows to cache POST requests.
  // Overriding [keyBuilder] is strongly recommended when [true].
  allowPostMethod: false,

// Add cache interceptor with global/default options
final dio = Dio()..interceptors.add(DioCacheInterceptor(options: options));

// ...

// Requesting with global options => status(200) => Content is written to cache store
var response = await dio.get('');
// Requesting with global options => status(304) => Content is read from cache store
response = await dio.get('');

// Requesting by modifying policy with refresh option
// for this single request => status(200) => Content is written to cache store
response = await dio.get('',
  options: options.copyWith(policy: CachePolicy.refresh).toOptions(),

Handling cache with client only

Follow those intructions if needed.


CacheOptions is widely available on interceptor and on requests to take precedence.

See documentation for all properties.


Optionally, you can encrypt body and headers with your own algorithm via CacheCipher.

Cache policy

enum CachePolicy {
  /// Same as [CachePolicy.request] when origin server has no cache config.
  /// In short, you'll save every successful GET requests.

  /// Same as [CachePolicy.refresh] when origin server has no cache config.

  /// Requests and skips cache save even if
  /// response has cache directives.

  /// Requests regardless cache availability.
  /// Caches if response has cache directives.

  /// Returns the cached value if available (and un-expired).
  /// Checks against origin server otherwise and updates cache freshness
  /// with returned headers when validation is needed.
  /// Requests otherwise and caches if response has directives.

Features and bugs

Please file feature requests and bugs at the issue tracker.