Smart Cached Network Image #

A smart cached network image package with queue management, retry logic, and rate limiting.

Description #

smart_cached_network_image is an advanced package for loading and caching images from the internet in Flutter applications. The package provides intelligent queue management for image loading, automatic retry logic on errors, rate limiting, and efficient caching.

Features #

• 🚀 Queue Management - Controlled number of simultaneous downloads
• 🔄 Automatic Retries - Configurable number of retry attempts on errors
• ⏱️ Rate Limiting - Delays between requests to reduce server load
• 💾 Smart Caching - Efficient storage of images in the file system
• 🎯 Two Usage Modes - StatefulWidget and FutureBuilder
• 📊 State Monitoring - Track queue and loading statistics

Installation #

Add the dependency to your pubspec.yaml:

dependencies:
  smart_cached_network_image: ^1.0.0

Then run:

flutter pub get

Quick Start #

1. Initialization #

import 'package:smart_cached_network_image/smart_cached_network_image.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize with configuration
  await SmartCachedNetworkImageProvider.initialize(
    const ImageLoadConfig(
      maxConcurrentRequests: 2,        // Maximum 2 simultaneous downloads
      requestDelay: Duration(milliseconds: 100), // 100ms delay between requests
      retryCount: 3,                   // 3 retry attempts on error
      retryDelay: Duration(seconds: 1), // 1 second delay between retries
    ),
  );
  
  runApp(MyApp());
}

2. Using StatefulWidget (Recommended) #

SmartCachedNetworkImage(
  imageUrl: 'https://example.com/image.jpg',
  placeholder: const Center(child: CircularProgressIndicator()),
  errorWidget: const Icon(Icons.error),
  fit: BoxFit.cover,
  width: 200,
  height: 200,
)

3. Using FutureBuilder #

SmartCachedNetworkImageFuture(
  imageUrl: 'https://example.com/image.jpg',
  placeholder: const Center(child: CircularProgressIndicator()),
  errorWidget: const Icon(Icons.error),
  fit: BoxFit.cover,
)

Detailed Documentation #

SmartCachedNetworkImage #

Main widget for displaying cached network images.

Parameters

SmartCachedNetworkImageFuture #

Alternative widget using FutureBuilder for asynchronous loading.

ImageLoadConfig #

Configuration for managing image loading behavior.

const ImageLoadConfig(
  maxConcurrentRequests: 2,                    // Maximum number of simultaneous downloads
  requestDelay: Duration(milliseconds: 100),   // Delay between requests
  retryCount: 3,                               // Number of retry attempts
  retryDelay: Duration(seconds: 1),            // Delay between retries
  defaultHeaders: {'User-Agent': 'MyApp/1.0'}, // Default headers
)

SmartCacheManager #

Cache manager for managing saved images.

Methods

• clearCache() - Clear all cache
• getCacheSize() - Get cache size in bytes
• cachedFilesCount - Number of cached files
• isCached(url, headers) - Check if image is cached

State Monitoring #

// Loading queue length
int queueLength = SmartCachedNetworkImageProvider.queueLength;

// Current loading count
int loadingCount = SmartCachedNetworkImageProvider.loadingCount;

// Check if URL is loading
bool isLoading = SmartCachedNetworkImageProvider.isLoading('https://example.com/image.jpg');

// Clear queue
SmartCachedNetworkImageProvider.clearQueue();

// Get cache manager
SmartCacheManager cacheManager = SmartCachedNetworkImageProvider.cacheManager;

Usage Examples #

Image Gallery #

GridView.builder(
  gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
    crossAxisCount: 2,
    crossAxisSpacing: 16.0,
    mainAxisSpacing: 16.0,
  ),
  itemCount: imageUrls.length,
  itemBuilder: (context, index) {
    return Card(
      child: SmartCachedNetworkImage(
        imageUrl: imageUrls[index],
        placeholder: const Center(child: CircularProgressIndicator()),
        errorWidget: const Icon(Icons.error),
        fit: BoxFit.cover,
      ),
    );
  },
)

With Custom Headers #

SmartCachedNetworkImage(
  imageUrl: 'https://api.example.com/image',
  headers: {
    'Authorization': 'Bearer your-token',
    'User-Agent': 'MyApp/1.0',
  },
  cacheKey: 'unique-image-key',
  placeholder: const Center(child: CircularProgressIndicator()),
  errorWidget: const Icon(Icons.error),
)

Cache Management #

// Clear cache
await SmartCachedNetworkImageProvider.cacheManager.clearCache();

// Get cache size
int cacheSize = await SmartCachedNetworkImageProvider.cacheManager.getCacheSize();
print('Cache size: ${cacheSize / 1024 / 1024} MB');

// Number of cached files
int fileCount = SmartCachedNetworkImageProvider.cacheManager.cachedFilesCount;
print('Cached files: $fileCount');

Performance #

The package is optimized for performance:

• Loading Queue prevents network overload
• Caching reduces repeated downloads
• Retry Logic improves reliability
• Rate Limiting reduces server load