advanced_cached_network_image 1.0.0

A Flutter package that provides queued image loading with caching to prevent 429 (Too Many Requests) errors. Load images sequentially through a queue system with retry mechanisms.

Advanced Cached Network Image

A Flutter package that provides queued image loading with caching to prevent 429 (Too Many Requests) errors. This package ensures images are loaded sequentially through a queue system while providing retry mechanisms and caching support.

Why This Package?

When loading multiple images from APIs (like AliExpress, Amazon, or any rate-limited service), you might encounter 429 errors due to too many simultaneous requests. This package solves this by:

• Sequential Loading: Images are loaded one at a time through a queue
• Retry Mechanism: Automatic retry on failed loads (3 attempts by default)
• Caching: Built on top of cached_network_image for efficient caching
• Rate Limiting: Configurable delays between requests
• Queue Management: Monitor and control the loading queue

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  advanced_cached_network_image: ^1.0.0

Then run:

flutter pub get

Usage

Basic Usage

import 'package:advanced_cached_network_image/advanced_cached_network_image.dart';
import 'package:cached_network_image/cached_network_image.dart';

// Load image with queue (prevents 429 errors)
Widget buildImage() {
  return FutureBuilder<CachedNetworkImageProvider>(
    future: AdvancedCachedNetworkImageProvider.create(
      url: 'https://example.com/image.jpg',
    ),
    builder: (context, snapshot) {
      if (snapshot.hasData) {
        return Image(image: snapshot.data!);
      } else if (snapshot.hasError) {
        return Icon(Icons.error);
      } else {
        return CircularProgressIndicator();
      }
    },
  );
}

Advanced Usage

// Custom retry count and delay
Widget buildAdvancedImage() {
  return FutureBuilder<CachedNetworkImageProvider>(
    future: AdvancedCachedNetworkImageProvider.create(
      url: 'https://example.com/image.jpg',
      retryCount: 5, // Retry up to 5 times
      queueDelay: Duration(milliseconds: 1000), // 1 second delay between requests
      headers: {'Authorization': 'Bearer token'},
      cacheKey: 'custom_key',
      maxWidth: 300,
      maxHeight: 300,
    ),
    builder: (context, snapshot) {
      if (snapshot.hasData) {
        return Image(
          image: snapshot.data!,
          width: 300,
          height: 300,
          fit: BoxFit.cover,
        );
      } else if (snapshot.hasError) {
        return Icon(Icons.error);
      }
      return CircularProgressIndicator();
    },
  );
}

// Direct loading (bypasses queue)
Widget buildDirectImage() {
  final directProvider = AdvancedCachedNetworkImageProvider.createDirect(
    url: 'https://example.com/image.jpg',
  );
  
  return Image(image: directProvider);
}

Queue Management

class ImageListWithQueue extends StatefulWidget {
  @override
  _ImageListWithQueueState createState() => _ImageListWithQueueState();
}

class _ImageListWithQueueState extends State<ImageListWithQueue> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Image Queue'),
        actions: [
          // Show queue status
          Text('Queue: ${AdvancedCachedNetworkImageProvider.queueLength}'),
          SizedBox(width: 8),
          Text('Loading: ${AdvancedCachedNetworkImageProvider.loadingCount}'),
          SizedBox(width: 16),
          // Clear queue button
          IconButton(
            icon: Icon(Icons.clear),
            onPressed: () {
              AdvancedCachedNetworkImageProvider.clearQueue();
              setState(() {}); // Refresh UI
            },
          ),
        ],
      ),
      body: ListView.builder(
        itemCount: imageUrls.length,
        itemBuilder: (context, index) {
          final url = imageUrls[index];
          final isLoading = AdvancedCachedNetworkImageProvider.isLoading(url);
          
          return ListTile(
            leading: isLoading 
              ? CircularProgressIndicator()
              : Icon(Icons.image),
            title: Text('Image ${index + 1}'),
            subtitle: Text(isLoading ? 'Loading...' : 'Ready'),
          );
        },
      ),
    );
  }
}

API Reference

AdvancedCachedNetworkImageProvider

create()

Creates a CachedNetworkImageProvider with queued loading.

Parameters:

• url (required): The URL of the image to load
• headers: Optional HTTP headers for the request
• cacheKey: Optional custom cache key for the image
• maxWidth: Optional maximum width for the image
• maxHeight: Optional maximum height for the image
• queueDelay: Optional delay between requests to prevent rate limiting
• retryCount: Number of retry attempts on failure (default: 3)

Returns: Future<CachedNetworkImageProvider>

createDirect()

Creates a CachedNetworkImageProvider WITHOUT queuing (for fast access).

Parameters:

• url (required): The URL of the image to load
• headers: Optional HTTP headers for the request
• cacheKey: Optional custom cache key for the image
• maxWidth: Optional maximum width for the image
• maxHeight: Optional maximum height for the image

Returns: CachedNetworkImageProvider

Static Methods

• clearQueue(): Clears the loading queue and cancels all pending requests
• queueLength: Returns the current number of images in the loading queue
• loadingCount: Returns the current number of images being loaded
• isLoading(String url): Checks if a specific image is currently being loaded

Example

Here's a complete example showing how to use the package:

import 'package:flutter/material.dart';
import 'package:advanced_cached_network_image/advanced_cached_network_image.dart';
import 'package:cached_network_image/cached_network_image.dart';

class ImageList extends StatefulWidget {
  @override
  _ImageListState createState() => _ImageListState();
}

class _ImageListState extends State<ImageList> {
  final List<String> imageUrls = [
    'https://picsum.photos/200/300?random=1',
    'https://picsum.photos/200/300?random=2',
    'https://picsum.photos/200/300?random=3',
    // Add more URLs...
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Queued Image Loading'),
        actions: [
          Text('Queue: ${AdvancedCachedNetworkImageProvider.queueLength}'),
          IconButton(
            icon: Icon(Icons.clear),
            onPressed: () => AdvancedCachedNetworkImageProvider.clearQueue(),
          ),
        ],
      ),
      body: ListView.builder(
        itemCount: imageUrls.length,
        itemBuilder: (context, index) {
          return Card(
            child: ListTile(
              leading: FutureBuilder<CachedNetworkImageProvider>(
                future: AdvancedCachedNetworkImageProvider.create(
                  url: imageUrls[index],
                  retryCount: 3,
                  queueDelay: Duration(milliseconds: 500),
                ),
                builder: (context, snapshot) {
                  if (snapshot.hasData) {
                    return Container(
                      width: 60,
                      height: 60,
                      child: Image(
                        image: snapshot.data!,
                        fit: BoxFit.cover,
                      ),
                    );
                  } else if (snapshot.hasError) {
                    return Container(
                      width: 60,
                      height: 60,
                      child: Icon(Icons.error),
                    );
                  }
                  return Container(
                    width: 60,
                    height: 60,
                    child: CircularProgressIndicator(),
                  );
                },
              ),
              title: Text('Image ${index + 1}'),
              subtitle: Text(imageUrls[index]),
            ),
          );
        },
      ),
    );
  }
}

Features

• ✅ Sequential Loading: Prevents 429 errors by loading images one at a time
• ✅ Retry Mechanism: Automatic retry on failed loads (configurable)
• ✅ Caching: Built on cached_network_image for efficient caching
• ✅ Rate Limiting: Configurable delays between requests
• ✅ Queue Management: Monitor and control the loading queue
• ✅ Direct Loading: Bypass queue when needed
• ✅ Error Handling: Comprehensive error handling and reporting