dio_cache_interceptor 3.5.0

dio_cache_interceptor: ^3.5.0 copied to clipboard

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

HTTP directives: #

Stores #

• 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.
• IsarCacheStore: Cache using Isar 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.

Usage #

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('https://www.foo.com');
// Requesting with global options => status(304) => Content is read from cache store
response = await dio.get('https://www.foo.com');

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

Handling cache with client only #

Follow those intructions if needed.

Options #

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

See documentation for all properties.

Encryption #

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.
  forceCache,

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

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

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

  /// 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.
  request,
}

Features and bugs #

Please file feature requests and bugs at the issue tracker.

License #

License.