dio_smart_cache 1.0.0

A smart caching interceptor for Dio with configurable endpoint-based cache rules and duration types.

Dio Smart Cache

A smart caching interceptor for Dio with configurable endpoint-based cache rules and duration types.

Features

• Predefined cache duration types: veryLong (1 day), long (12 hours), medium (1 hour), short (20 minutes)
• Endpoint-specific cache rules: Define cache behavior per endpoint with pattern matching
• Force refresh support: Bypass cache when needed
• Flexible configuration: Customize durations, cache store, and matching strategies
• Shared Preferences Storage: Uses native Shared Preferences for persistent storage by default
• Built on dio_cache_interceptor: Leverages the reliable dio_cache_interceptor package

Installation

Add to your pubspec.yaml:

dependencies:
  dio_smart_cache:
    path: packages/dio_smart_cache # For local development
    # Or from git:
    # git:
    #   url: https://github.com/your-repo/dio_smart_cache.git
    #   ref: master

Quick Start

import 'package:dio/dio.dart';
import 'package:dio_smart_cache/dio_smart_cache.dart';

// Create Dio instance
final dio = Dio();

// Configure smart cache
// Configure smart cache
final smartCache = SmartCacheInterceptor(
  options: SmartCacheOptions(
    // By default, it uses SharedPreferences for storage.
    // You can provide a custom store implementation if needed:
    // store: MyCustomStore(),

    cacheRules: [
      CacheRule(pattern: '/locations', durationType: CacheDurationType.veryLong),
      CacheRule(pattern: '/countries', durationType: CacheDurationType.veryLong),
      CacheRule(pattern: '/products', durationType: CacheDurationType.long),
      CacheRule(pattern: '/promotions', durationType: CacheDurationType.short),
    ],
  ),
);

// Add interceptor to Dio
dio.addSmartCache(smartCache);

// Make requests with automatic caching
final response = await dio.get(
  '/api/locations',
  options: smartCache.cacheOptionsFor('/locations'),
);

// Force refresh (bypass cache)
final freshResponse = await dio.get(
  '/api/locations',
  options: smartCache.cacheOptionsFor('/locations', forceRefresh: true),
);

Configuration Options

SmartCacheOptions

Option	Type	Default	Description
store	CacheStore?	null	Custom cache store
allowPostMethod	bool	false	Allow caching POST requests
defaultPolicy	CachePolicy	request	Default cache policy
hitCacheOnErrorExcept	List<int>	[401, 403]	Status codes to not use cache on error
priority	CachePriority	normal	Cache priority
maxStale	Duration	7 days	Maximum stale duration
cacheDurations	Map<CacheDurationType, Duration>	Default values	Override default durations
cacheRules	List<CacheRule>	[]	Endpoint cache rules

CacheRule

// Simple pattern matching (contains)
CacheRule(
  pattern: '/users',
  durationType: CacheDurationType.medium,
);

// Exact match
CacheRule(
  pattern: '/api/v1/users',
  durationType: CacheDurationType.long,
  exactMatch: true,
);

// Regex match
CacheRule(
  pattern: r'/users/\d+',
  durationType: CacheDurationType.short,
  regexMatch: true,
);

// Custom duration
CacheRule.custom(
  pattern: '/special',
  duration: Duration(minutes: 45),
);

Cache Duration Types

Type	Default Duration
veryLong	1 day
long	12 hours
medium	1 hour
short	20 minutes
none	No caching

Override defaults:

SmartCacheOptions(
  cacheDurations: {
    CacheDurationType.veryLong: Duration(days: 3),
    CacheDurationType.long: Duration(hours: 24),
  },
  // ...
);

Cache Management

// Clear all cache
await smartCache.clearCache();

// Delete specific cache entry
await smartCache.deleteCache('https://api.example.com/users');

// Get cached response
final cached = await smartCache.getCache('https://api.example.com/users');

Migration from BaseNetwork

If you're migrating from the original BaseNetwork implementation:

Before:

class BaseNetwork {
  final Map<String, CacheDurationType> _endpointCacheRules = {
    "/locations": CacheDurationType.veryLong,
    "/countries": CacheDurationType.veryLong,
  };
  // ...
}

After:

final smartCache = SmartCacheInterceptor(
  options: SmartCacheOptions(
    cacheRules: [
      CacheRule(pattern: '/locations', durationType: CacheDurationType.veryLong),
      CacheRule(pattern: '/countries', durationType: CacheDurationType.veryLong),
    ],
  ),
);

License

MIT License