flutter_cache_store 0.4.0

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 88

flutter_cache_store #

A flexible cache manager for Flutter.

This package is highly inspired by flutter_cache_manager. Can be easily switched to each other.

Quick Start #

import 'package:flutter_cache_store/flutter_cache_store.dart';

void demo(String url) async {
  final store = await CacheStore.getInstance();
  final file = await store.getFile(url);
  // do something with file...
}

APIs #

CacheStore #

void api() async {
  // set expiration policy.
  // must be called before `CacheStore.getInstance` or will raise an exception.
  // default: LessRecentlyUsedPolicy(maxCount: 999)
  CacheStore.setPolicy(LessRecentlyUsedPolicy(maxCount: 4096));

  // get a singleton store instance
  CacheStore store = await CacheStore.getInstance(
    clearNow: true, // default: false - whether to clean up immediately
    httpGetter: myFetch, // default: null - a shortcut of `CacheStore.fetch`
  );

  // Optional:
  // You can change custom fetch method at anytime.
  // Set it to `null` will simply use `http.get`
  CacheStore.fetch = myFetch;

  // fetch a file from an URL and cache it
  File file = await store.getFile(
    'url', // GET method
    key: null, // use custom string instead of URL
    headers: {}, // same as http.get
    // Optional: Map<String, dynamic> any custom you want to pass to your custom fetch function.
    custom: {'method': 'POST', 'body': 'test'},
    flushCache: false, // whether to re-download the file
  );

  // flush specific files by keys
  await store.flush([
    'key', // key (default is the URL) passed to `getFile`
  ]);

  // remove all cached files
  await store.clearAll();
}

// Custom fetch function.
// A demo of how you can achieve a fetch supporting POST with body
Future<Response> myFetch(url,
    {Map<String, String> headers, Map<String, dynamic> custom}) {
  final data = custom ?? {};
  switch (data['method'] ?? '') {
    case 'POST':
      {
        return post(url, headers: headers, body: data['body']);
      }
    default:
      return get(url, headers: headers);
  }
}

Cache File Structure #

By default, the cached files will be saved under $TEMP/cache_store. $TEMP is generated by path_provider. The default temp filenames are timestamp-based 11 chars.

You can customize your own file structure under $TEMP/cache_store by overriding Policy. There is an example:

Let's suppose your are developing a reader for novels, and your app will cache chapters of books. Your API returns some IDs of books and chapters, and an ID only contains letters and digits.

// Extends a Policy class and override `generateFilename`
class LRUCachePolicy extends LessRecentlyUsedPolicy {
  LRUCachePolicy({int maxCount}) : super(maxCount: maxCount);

  @override
  String generateFilename({final String key, final String url}) =>
      key; // use key as the filename
}

void customizedCacheFileStructure() async {
  // Set it as your Policy
  CacheStore.setPolicy(LRUCachePolicy(maxCount: 4096));

  // get a singleton store instance
  CacheStore store = await CacheStore.getInstance();

  // fetch a file from an URL and cache it
  String bookId = 'book123';
  String chapterId = 'ch42';
  String chapterUrl = 'https://example.com/book123/ch42';
  File file = await store.getFile(
    chapterUrl,
    key: '$bookId/$chapterId', // use IDs as path and filename
  );

  // Your file will be cached as `$TEMP/cache_store/book123/ch42`
}

Cache Policy #

  • LessRecentlyUsedPolicy

    LRU policy. Less Recently Used files will be removed when reached maxCount. Each time you access a file will update its used timestamp.

    new LessRecentlyUsedPolicy(
      maxCount: 999,
    );
    
  • LeastFrequentlyUsedPolicy

    LFU policy. Least Frequently Used files will be removed when reached maxCount. Each time you access a file will increase its hit count. After hitAge time the hit will expire. It will fallback to LRU policy if files have same hit count.

    new LeastFrequentlyUsedPolicy(
      maxCount: 999,
      hitAge: Duration(days: 30),
    );
    
  • CacheControlPolicy

    Cache-Control header policy. This policy generally follows max-age=<seconds> or s-maxage=<seconds> rules of http response header Cache-Control. If the max-age-seconds not been set, it will use minAge unless you set it to null. The age will not be longer than maxAge.

    new CacheControlPolicy(
      maxCount: 999,
      minAge: Duration(seconds: 30), // nullable
      maxAge: Duration(days: 30), // nullable
    );
    
  • FifoPolicy

    First-In, First-Out policy, super simple and maybe for example only.

    new LessRecentlyUsedPolicy(
      maxCount: 999, // default: 999
    );
    

Performance Warning #

  • The implementation maintains all key-item in memory to improve the speed. So maxCount must between 1 and 100000 (100k) due to the cost of RAM and file system.

  • Currently, all the policies simply sort all items to expire files. It may hit performance due to O(N*logN) complexity.

    Will switch to priority queue which has O(N*logK) while K usually is a very small number.

How to implement your own policy #

The interface is a simple abstract class. You only have to implement a few methods.

abstract class CacheStorePolicy {
  // IT'S THE ONLY METHOD YOU HAVE TO IMPLEMENT.
  // `store` will invoke this method from time to time.
  // Make sure return all expired items at once.
  // then `store` will manage to remove the cached files.
  // you also have to save your data if need to persist some data.
  Future<Iterable<CacheItem>> cleanup(Iterable<CacheItem> allItems);

  // will be invoked when store.clearAll called.
  Future<void> clearAll(Iterable<CacheItem> allItems) async {}

  // will invoke only once when the `store` is created and load saved data.
  // you need to load persistent data and restore items' payload.
  // only returned items will be cached. others will be recycled later.
  Future<Iterable<CacheItem>> restore(List<CacheItem> allItems) async => allItems;

  // event when a new `CacheItem` has been added to the cache.
  // you may need to attach a `CacheItemPayload` instance to it.
  Future<void> onAdded(final CacheItem addedItem) async {}

  // event when an item just been accessed.
  // you may need to attach or update item's payload.
  Future<void> onAccessed(final CacheItem accessedItem, bool flushed) async {}

  // event when a request just finished.
  // the response headers will be passed as well.
  Future<void> onDownloaded(final CacheItem item, final Map<String, String> headers) async {}

  // event when `store.flush` has called
  Future<void> onFlushed(final Iterable<CacheItem> flushedItems) async {}

  // filename (including path) relative to `CacheItem.rootPath`.
  // usually ignore this unless need a better files structure.
  // you must provide valid filenames.
  String generateFilename({final String key, final String url}) =>
      Utils.genName(); // timestamp based random filename
}
  • Tips

    You don't have to implement all of the onAdded, onAccessed and onDownloaded.

Change Log #

[0.4.0] - Released on 2019-02-06

  • Added CustomFetch support:
    • Now you can use custom function to fetch data instead of http.get.
    • Added named optional parameter Map<String, dynamic> custom to getFile, so you can pass custom data to your custom fetch function.

[0.3.2+2] - Released on 2019-01-20

  • Fixed stupid Health suggestions.

[0.3.2] - Released on 2019-01-15

  • First official release. Nothing changed.

[0.3.1-RC2] - Released on 2018-12-08

  • Fixed deprecated int.parse.

[0.3.0-RC2] - Released on 2018-12-08

  • Added inline documents.
  • LessRecentlyUsedPolicy has been tested for a while and worked pretty well.

[0.3.0-RC1] - Updated on 2018-11-24

  • Added LeastFrequentlyUsedPolicy, CacheControlPolicy and FifoPolicy.
  • File structure changes.
  • Checking maxCount parameter now.

[0.2.0-beta2] - Released on 2018-11-10

Breaking Changes #

  • Changed interface of CacheStorePolicy.generateFilename to make it easier to customize your own cache file structure.

Others #

  • Updated document and example.
  • Fixed some bugs.

[0.1.3-beta] - Released on 2018-11-10

  • Some bug fixes.
  • Document updates.
  • Better 0 size files handling.

[0.1.1-beta] - Released on 2018-11-04

  • Finished basic designs.
  • Updated documentation to match requirements
  • Started to use in my own project.

example/example.dart

import 'dart:io';
import 'package:flutter_cache_store/flutter_cache_store.dart';
import 'package:http/http.dart' show Response, get, post;

// [GET STARTED]
void demo(String url) async {
  final store = await CacheStore.getInstance();
  final file = await store.getFile(url);
  // do something with file...
}

// [BASIC OPTIONS]
void api() async {
  // set expiration policy.
  // must be called before `CacheStore.getInstance` or will raise an exception.
  // default: LessRecentlyUsedPolicy(maxCount: 999)
  CacheStore.setPolicy(LessRecentlyUsedPolicy(maxCount: 4096));

  // get a singleton store instance
  CacheStore store = await CacheStore.getInstance(
    clearNow: true, // default: false - whether to clean up immediately
    httpGetter: myFetch, // default: null - a shortcut of `CacheStore.fetch`
  );

  // Optional:
  // You can change custom fetch method at anytime.
  // Set it to `null` will simply use `http.get`
  CacheStore.fetch = myFetch;

  // fetch a file from an URL and cache it
  File file = await store.getFile(
    'url', // GET method
    key: null, // use custom string instead of URL
    headers: {}, // same as http.get
    // Optional: Map<String, dynamic> any custom you want to pass to your custom fetch function.
    custom: {'method': 'POST', 'body': 'test'},
    flushCache: false, // whether to re-download the file
  );

  // flush specific files by keys
  await store.flush([
    'key', // key (default is the URL) passed to `getFile`
  ]);

  // remove all cached files
  await store.clearAll();
}

// Custom fetch function.
// A demo of how you can achieve a fetch supporting POST with body
Future<Response> myFetch(url,
    {Map<String, String> headers, Map<String, dynamic> custom}) {
  final data = custom ?? {};
  switch (data['method'] ?? '') {
    case 'POST':
      {
        return post(url, headers: headers, body: data['body']);
      }
    default:
      return get(url, headers: headers);
  }
}

// [ADVANCED USAGE]
// Extends a Policy class and override `generateFilename`
class LRUCachePolicy extends LessRecentlyUsedPolicy {
  LRUCachePolicy({int maxCount}) : super(maxCount: maxCount);

  @override
  String generateFilename({final String key, final String url}) =>
      key; // use key as the filename
}

void customizedCacheFileStructure() async {
  // Set it as your Policy
  CacheStore.setPolicy(LRUCachePolicy(maxCount: 4096));

  // get a singleton store instance
  CacheStore store = await CacheStore.getInstance();

  // fetch a file from an URL and cache it
  String bookId = 'book123';
  String chapterId = 'ch42';
  String chapterUrl = 'https://example.com/book123/ch42';
  File file = await store.getFile(
    chapterUrl,
    key: '$bookId/$chapterId', // use IDs as path and filename
  );

  // Your file will be cached as `$TEMP/cache_store/book123/ch42`
}

Use this package as a library

1. Depend on it

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


dependencies:
  flutter_cache_store: ^0.4.0

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter packages get

Alternatively, your editor might support flutter packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:flutter_cache_store/flutter_cache_store.dart';
  
Version Uploaded Documentation Archive
0.4.0 Feb 6, 2019 Go to the documentation of flutter_cache_store 0.4.0 Download flutter_cache_store 0.4.0 archive
0.3.2+2 Jan 20, 2019 Go to the documentation of flutter_cache_store 0.3.2+2 Download flutter_cache_store 0.3.2+2 archive
0.3.2+1 Jan 19, 2019 Go to the documentation of flutter_cache_store 0.3.2+1 Download flutter_cache_store 0.3.2+1 archive
0.3.2 Jan 15, 2019 Go to the documentation of flutter_cache_store 0.3.2 Download flutter_cache_store 0.3.2 archive
0.3.1-RC2 Dec 8, 2018 Go to the documentation of flutter_cache_store 0.3.1-RC2 Download flutter_cache_store 0.3.1-RC2 archive
0.3.0-RC2 Dec 8, 2018 Go to the documentation of flutter_cache_store 0.3.0-RC2 Download flutter_cache_store 0.3.0-RC2 archive
0.2.0-beta2 Nov 10, 2018 Go to the documentation of flutter_cache_store 0.2.0-beta2 Download flutter_cache_store 0.2.0-beta2 archive
0.1.4-beta Nov 10, 2018 Go to the documentation of flutter_cache_store 0.1.4-beta Download flutter_cache_store 0.1.4-beta archive
0.1.3-beta Nov 10, 2018 Go to the documentation of flutter_cache_store 0.1.3-beta Download flutter_cache_store 0.1.3-beta archive
0.1.2-beta Nov 10, 2018 Go to the documentation of flutter_cache_store 0.1.2-beta Download flutter_cache_store 0.1.2-beta archive

All 13 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
77
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
88
Learn more about scoring.

We analyzed this package on Apr 16, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.2.0
  • pana: 0.12.14
  • Flutter: 1.4.7

Platforms

Detected platforms: Flutter

References Flutter, and has no conflicting libraries.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.68.0 <3.0.0
flutter 0.0.0
http ^0.12.0 0.12.0+2
path_provider ^0.4.0 0.4.1 0.5.0+1
shared_preferences ^0.4.0 0.4.3 0.5.2
synchronized ^1.5.0 1.5.3+2 2.1.0
Transitive dependencies
async 2.2.0
charcode 1.1.2
collection 1.14.11
http_parser 3.1.3
meta 1.1.6 1.1.7
path 1.6.2
pedantic 1.5.0
sky_engine 0.0.99
source_span 1.5.5
string_scanner 1.0.4
term_glyph 1.1.0
typed_data 1.1.6
vector_math 2.0.8