---

Cached

Simple Dart package with build-in code generation. It simplifies and speedup creation of cache mechanism for dart classes.

Least Recently Used (LRU) cache algorithm

It is a finite key-value map using the Least Recently Used (LRU) algorithm, where the most recently-used items are "kept alive" while older, less-recently used items are evicted to make room for newer items.

Useful when you want to limit use of memory to only hold commonly-used things or cache some API calls.

Contents

• Least Recently Used (LRU) cache algorithm
• Contents
• Motivation
• Setup
  • Install package
  • Run the generator
  • Dart 3 changes
• Basics
  • WithCache
  • Cached
    • Example
    • Example with getter
    • where
      • sync example
      • async example
  • IgnoreCache
  • Ignore
  • CacheKey
  • ClearCached
  • ClearAllCached
  • StreamedCache
  • CachePeek
  • DeletesCache
• Persistent storage
• Lazy persistent storage
• Direct persistent storage
• Contribution
  • feature request
  • Fix
• Contributors

Motivation

There is quite often situation, that you have to cache something in memory for later usage. Common case is cache some API calls and theirs responses. Usually, it is done in some data layer, probably in - let say - RemoteRepository

Oftentimes, the repository code might look like this:

class RemoteRepository implements Repository {
  final SomeApiDataSource _dataSource;
  final SomeResponseType? cachedResponse;

  const RemoteRepository(this._dataSource);

  @override
  Future<SomeResponseType> getSthData() async {
    if (cachedResponse != null) {
      return cachedResponse;
    }

    cachedResponse = await _dataSource.getData();
    return cachedResponse;
  }
}

So, instead of doing it manually we can use library and write our RemoteRepository in that way:

@WithCache()
abstract mixin class RemoteRepository implements Repository, _$RemoteRepository {
  factory RemoteRepository({required SomeApiDataSource dataSource,}) = _RemoteRepository;

  @Cached()
  Future<SomeResponseType> getSthData() {
    return dataSource.getData();
  }
}

Setup

Install package

Run command:

flutter pub add --dev cached
flutter pub add --dev build_runner
flutter pub add cached_annotation

Or manually add the dependencies in the pubspec.yaml

dependencies:
  cached_annotation:

dev_dependencies:
  cached:
  build_runner:

That's it! Now, you can write your own cached class 🎉

Run the generator

To run the code generator, execute the following command:

dart run build_runner build

For Flutter projects, you can run:

flutter pub run build_runner build

Note that like most code-generators, [Cached] will need you to both import the annotation ([cached_annotation]) and use the part keyword on the top of your files.

As such, a file that wants to use [Cached] will start with:

import 'package:cached_annotation/cached_annotation.dart';

part 'some_file.cached.dart';

Dart 3 changes

Dart 3 introduces a change in the way how mixins work, requiring them to be declared with the mixin keyword. If you are migrating from Dart 2 to Dart 3, you need to add the mixin keyword to your Cached class declarations.

Dart 3:

@WithCache()
abstract mixin class Gen implements _$Gen {
  factory Gen() = _Gen;

  ...
}

Dart 2:

@WithCache()
abstract class Gen implements _$Gen {
  factory Gen() = _Gen;

  ...
}

Basics

WithCache

Annotation for Cached package.

Annotating a class with @WithCache will flag it as a needing to be processed by Cached code generator.
It can take one additional boolean parameter useStaticCache. If this parameter is set to true, generator will generate cached class with static cache. It means each instance of this class will have access to the same cache. Default value is set to false

@WithCache(useStaticCache: true)
abstract mixin class Gen implements _$Gen {
  factory Gen() = _Gen;

  ...
}

Cached

Method/Getter decorator that flag it as needing to be processed by Cached code generator.

There are 4 possible additional parameters:

• ttl - time to live. In seconds. Set how long cache will be alive. Default value is set to null, means infinitive ttl.
• syncWrite - Affects only async methods ( those one that returns Future ) If set to true first method call will be cached, and if following ( the same ) call will occur, all of them will get result from the first call. Default value is set to false;
• limit - limit how many results for different method call arguments combination will be cached. Default value null, means no limit.
• where - function triggered before caching the value. If returns true: value will be cached, if returns false: value wil be ignored. Useful to signal that a certain result must not be cached, but @IgnoreCache is not enough (e.g. condition whether or not to cache known once acquiring data)

Important:

Please note, that persistentStorage is marked as @Deprecated and will be removed with next release. We encourage the use of @PersistentCached annotation

• persistentStorage - Defines optional usage of external persistent storage (e.g. shared preferences). If set to true in order to work, you have to set PersistentStorageHolder.storage in your main.dart file. Check the Persistent storage section of this README for more information.

Example

@Cached(
  ttl: 60,
  syncWrite: true,
  limit: 100,
)
Future<int> getInt(String param) {
  return Future.value(1);
}

Example with getter

@cached
Future<int> get getter {
  return Future.value(1);
}

where

As mentioned before, where takes top-level function to check whether to cache value or not. It also supports async calls, so feel free to create conditional caching based on e.g. http response parsing.

sync example

@Cached(
  ttl: 60,
  syncWrite: true,
  limit: 100,
  where: _shouldCache
)
int getInt(String param) {
  return 1;
}

bool _shouldCache(int candidate) {
  return candidate > 0;
}

async example

@Cached(
  where: _asyncShouldCache,
)
Future<http.Response> getDataWithCached() {
  return http.get(Uri.parse(_url));
}

Future<bool> _asyncShouldCache(http.Response response) async {
  final json = jsonDecode(response.body) as Map<String, dynamic>;
  print('Up to you: check conditionally and decide if should cache: $json');

  print('For now: always cache');
  return true;
}

IgnoreCache

That annotation must be above a field in a method and must be bool, if true the cache will be ignored

Example use:

@cached
Future<int> getInt(String param, {@ignoreCache bool ignoreCache = false}) {
  return Future.value(1);
}

or you can use with useCacheOnError in the annotation and if set true then return the last cached value when an error occurs.

@cached
Future<int> getInt(String param, {@IgnoreCache(useCacheOnError: true) bool ignoreCache = false}) {
  return Future.value(1);
}

Possible reason why the generator gives an error

• if method has multiple @ignoreCache annotation

Ignore

That annotation must be above a field in a method, arguments with @ignore annotations will be ignored while generating cache key.

Example use:

@cached
Future<int> getInt(@ignore String param) {
  return Future.value(1);
}

CacheKey

That annotation must be above a field in a method and must contain constant function that will return cache key for provided field value

Example use:

@cached
Future<int> getInt(@CacheKey(exampleCacheFunction) int test) async {
  await Future.delayed(Duration(milliseconds: 20));
  return test;
}

String exampleCacheFunction(dynamic value) {
  return value.toString();
}

You can also use @iterableCacheKey, which will generate cache key from Iterable<T> values

Example use:

@cached
Future<List<int>> getInt(@iterableCacheKey List<int> test) async {
  await Future.delayed(Duration(milliseconds: 20));
  return test;
}

ClearCached

Method decorator that flag it as needing to be processed by Cached code generator. Method annotated with this annotation can be used to clear result of method annotated with Cached annotation.
Constructor of this annotation can take one possible argument. It is method name, that we want to clear the cache.

Let say there is existing cached method:

@Cached()
Future<SomeResponseType> getUserData() {
  return userDataSource.getData();
}

to generate clearing cache method we can write:

@clearCached
void clearGetUserData();

or

@ClearCached('getUserData')
void clearUserData();

The ClearCached argument or method name has to correspond to cached method name. We can also create a method that returns a bool, and then write our own logic to check if the cache should be cleared or not.

@ClearCached('getUserData')
Future<bool> clearUserData() {
  return userDataSource.isLoggedOut();
}

If the user is logged out, the user cache will be cleared.

Possible reasons why the generator gives an error

• if method with @cached annotation doesn’t exist
• if method to pair doesn’t exist
• if method don’t return bool, Future<bool> or not a void, Future<void>

ClearAllCached

This is exactly the same as ClearCached, except you don't pass any arguments and you don't add a clear statement before the method name, all you have to do is add @clearAllCached above the method, this annotation will clear cached values for all methods in the class with the @WithCache.

Here is a simple example:

@clearAllCached
void clearAllData();

or we can also create a method that returns a bool, and then write our own logic to check if cached values for all methods will be cleared

@clearAllCached
Future<bool> clearAllData() {
  return userDataSource.isLoggedOut();
}

If the user is logged out, will clear cached values for all methods

Possible reasons why the generator gives an error

• if we have too many clearAllCached annotation, only one can be
• if method don’t return bool, Future<bool> or not a void

StreamedCache

Use @StreamedCache annotation to get a stream of cache updates from a cached method. Remember to provide at least the name of the cached class method in the methodName parameter.

Simple example of usage:

@cached
int cachedMethod() {
  return 1;
}

@StreamedCache(methodName: "cachedMethod", emitLastValue: true)
Stream<int> cachedStream();

Method annotated with @StreamedCache should have same parameters (except @ignore or @ignoreCache) as method provided in methodName parameter, otherwise InvalidGenerationSourceError will be thrown. Return type of this method should be a Stream<sync type of target method> - for example for Future<String> the return type will be Stream<String>

Example:

@cached
Future<String> cachedMethod(int x, @ignore String y) async {
  await Future.delayed(Duration(miliseconds: 100));
  return x.toString();
}

@StreamedCache(methodName: "cachedMethod", emitLastValue: false)
Stream<String> cachedStream(int x);

CachePeek

Method decorator that flag it as needing to be processed by Cached code generator. Method annotated with this annotation can be used to peek result of method annotated with Cached annotation.

Constructor of this annotation can take one possible argument. It is method name, that we want to peek the cache.

Let say there is existing cached method:

@Cached()
Future<SomeResponseType> getUserData() {
  return userDataSource.getData();
}

to generate peek cache method we can write:

@CachePeek("getUserData")
SomeResponseType? peekUserDataCache();

The CachePeek methodName argument has to correspond to cached method name

Possible reasons why the generator gives an error

• if more then one method is targeting [Cached] method cache
• if method return type is incorrect
• if method has different parameters then target function (excluding [Ignore], [IgnoreCache])
• if method is not abstract

DeletesCache

@DeletesCache annotaton is a method decorator that marks method to be processed by code generator. Methods preceeded by this annotation clear the cache of all specified methods, annotated with @Cached, if they complete with result.

@DeletesCache annotation takes a list of cached methods that are affected by the use of annotated method, the cache of all specified methods is cleared on method success, but if an error occurs, the cache is not deleted and the error is rethrown.

If there is a cached method:

@Cached()
Future<SomeResponseType> getSthData() {
  return dataSource.getData();
}

Then a method that affects the cache of this method can be written as:

@DeletesCache(['getSthData'])
Future<SomeResponseType> performOperation() {
  ...
  return data;
}

All methods specified in @DeletesCache annotation must correspond to cached method names. If the performOperation method completes without an error, then the cache of getSthData will be cleared.

Throws an [InvalidGenerationSourceError]

• if method with @cached annotation doesn't exist
• if no target method names are specified
• if specified target methods are invalid
• if annotated method is abstract

Persistent storage

Cached library supports usage of any external storage (e.g. Shared Preferences, Hive), by using @PersistentCached() annotation:

Actual version

  @PersistentCached()
  Future<double> getDouble() async {
    return await _source.nextDouble() ;
  }

@Deprecated version

  @Cached(persistentStorage: true)
  Future<double> getDouble() async {
    return await _source.nextDouble() ;
  }

You only have to provide a proper interface by extending CachedStorage abstraction, e.g.:

...
import 'package:cached_annotation/cached_annotation.dart';

class MyStorageImpl extends CachedStorage {
  final _storage = MyExternalStorage();

  @override
  Future<Map<String, dynamic>> read(String key) async {
    return await _storage.read(key);
  }

  @override
  Future<void> write(String key, Map<String, dynamic> data) async {
    await _storage.write(key, data);
  }

  @override
  Future<void> delete(String key) async {
    await _storage.delete(key);
  }

  @override
  Future<void> deleteAll() async {
    await _storage.deleteAll();
  }
}

Now you have to assign instance of your class (preferably on the top of your main method):

...
import 'package:cached_annotation/cached_annotation.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  PersistentStorageHolder.storage = await MyStorageImpl();
  
  runApp(const MyApp());
}

As you can see above, Cached doesn't provide any generic way of error or typing handling. It'll just use PersistentStorageHolder.storage to save and read cached data from storage in generated code. You have to take care of it yourself inside your code.

Lazy persistent storage

Additional feature available only for @LazyPersistentCached() is initialize cache from external storage only after method call. This solution makes it possible to bypass a heavy initial load for large amounts of data.

  @LazyPersistentCached()
  Future<double> getDouble() async {
    return await _source.nextDouble() ;
  }

Direct persistent storage

When the @DirectPersistedCached annotation is used, it prevents the automatic loading of data from external storage into the cache managed by the caching library. For methods with this annotation, the library's generator neither creates a map for storing data fetched from the storage nor initializes such a map before the method's invocation. Consequently, setting this parameter ensures that data is always fetched directly from externalStorage upon method call. If the data is not already present in externalStorage, it is retrieved and then stored there.

  @DirectPersistedCached()
  Future<double> getDirectDouble() async {
    return await _source.nextDouble() ;
  }

Data saved to persistent storage can be deleted by using @ClearCached(), @ClearAllCached() or @DeletesCache annotations.

Usage of persistent storage does not change this library caching behaviour in any way. It only adds new capabilities, but it can affect the way in which you implement your app:

Important:

Please note, that persistent storage usage enforces you to provide async API when using Cached annotations!

For sample project, please check persistent_storage_example inside cached/example directory.

Contribution

We accept any contribution to the project!

Suggestions of a new feature or fix should be created via pull-request or issue.

feature request

• Check if feature is already addressed or declined

• Describe why this is needed

  Just create an issue with label enhancement and descriptive title. Then, provide a description and/or example code. This will help the community to understand the need for it.

• Write tests for your feature

  The test is the best way to explain how the proposed feature should work. We demand a complete test before any code is merged in order to ensure cohesion with existing codebase.

• Add it to the README and write documentation for it

  Add a new feature to the existing featrues table and append sample code with usage.

Fix

• Check if bug was already found

• Describe what is broken

  The minimum requirement to report a bug fix is a reproduction path. Write steps that should be followed to find a problem in code. Perfect situation is when you give full description why some code doesn’t work and a solution code.

Contributors