Cache is a hardware or software component that stores data so that future requests for that data can be served faster; the data stored in a cache might be the result of an earlier computation or a copy of data stored elsewhere.
JsonCache is an object-oriented package for local caching of user data in json. It can also be considered as a layer on top of Flutter's local storage packages that aims to unify them with a stable and elegant interface — JsonCache.
Why Json?
- Because most of the local storage packages available for Flutter applications use Json as the data format.
- There is a one-to-one relationship between Dart's built-in type
Map<String, dynamic>and Json, which makes encoding/decoding data in Json a trivial task.
This package gives developers great flexibility by providing a set of classes that can be selected and grouped in various combinations to meet specific cache requirements.
JsonCache is the core Dart interface of this package and represents the concept of cached data. It is defined as:
/// Represents cached data in json format.abstractinterfaceclassJsonCache {
/// Frees up storage space — deletes all keys and values.Future<void> clear();
/// Removes cached data located at [key].Future<void> remove(String key);
/// Retrieves cached data located at [key] or `null` if a cache miss occurs.Future<Map<String, dynamic>?> value(String key);
/// It either updates data located at [key] with [value] or, if there is no /// data at [key], creates a new cache row at [key] with [value]. /// /// **Note**: [value] must be json encodable.Future<void> refresh(String key, Map<String, dynamic> value);
/// Checks for cached data located at [key]. /// /// Returns `true` if there is cached data at [key]; `false` otherwise.Future<bool> contains(String key);
/// The cache keys. /// /// Returns an **unmodifiable** list of all cache keys without duplicates.Future<UnmodifiableListView<String>> keys();
}It is reasonable to consider each cache entry (a key/data pair) as a group of related data. Thus, it is expected to cache data into groups, where a key represents the name of a single data group. For example:
'profile': {'name':'John Doe', 'email':'johndoe@email.com', 'accountType':'premium'};
'preferences': {'theme': {'dark':true}, 'notifications': {'enabled':true}}Above, the profile key is associated with profile-related data, while the preferences key is associated with the user's preferences.
A typical code for saving the previous profile and preferences data is:
finalJsonCache jsonCache = … retrieve one of the JsonCache implementations.
…
await jsonCache.refresh('profile', {'name':'John Doe', 'email':'johndoe@email.com', 'accountType':'premium'});
await jsonCache.refresh('preferences', {'theme': {'dark':true}, 'notifications':{'enabled':true}});In order to store a simple value such as a string, int, double, etc,
define it as a map key whose associated value is a boolean placeholder value
set to true. For example:
/// Storing a phrase. jsonCache.refresh('info', {'This is very important information.':true});
// later on…// This variable is a Map containing a single key.final cachedInfo =await jsonCache.value('info');
// The key itself is the content of the stored information.final info = cachedInfo?.keys.first;
print(info); // 'This is very important information.'Whenever a function, method, or class needs to interact with cached user data,
this should be done via a reference to the JsonCache interface.
See the code snippet below:
/// Stores/retrieves user data from the device's local storage.classJsonCacheRepositoryimplementsILocalRepository {
/// Sets the [JsonCache] instance.constJsonCacheRepository(this._cache);
// This class depends on an interface rather than any actual implementationfinalJsonCache _cache;
/// Retrieves a cached email by [userId] or `null` if not found.@overrideFuture<String?> getUserEmail(String userId) async {
final userData =await _cache.value(userId);
if (userData !=null) {
// the email value or null if absent.return userData['email'] asString?; }
// There is no data associated with [userId].returnnull;
}
}By depending on an interface rather than an actual implementation, your code becomes loosely coupled to this package — which makes unit testing a lot easier.
The library JsonCache contains all classes that implement the JsonCache interface with more in-depth details.
The following sections are an overview of each implementation.
JsonCacheMem
is a thread-safe in-memory implementation of the JsonCache interface.
Moreover, it encapsulates a secondary cache or "slower level2 cache". Typically,
this secondary cache instance is responsible for the local cache; that is, it is
the JsonCache implementation that actually persists the data on the user's
device.
Since JsonCacheMem is a
Decorator, you should
normally pass another JsonCache instance to it whenever you instantiate a
JsonCacheMem object. For example:
…
/// Cache initializationfinal sharedPrefs =awaitSharedPreferences.getInstance();
finalJsonCacheMem jsonCache =JsonCacheMem(JsonCacheSharedPreferences(sharedPrefs));
…
/// Saving profile and preferences data.await jsonCache.refresh('profile', {'name':'John Doe', 'email':'johndoe@email.com', 'accountType':'premium'});
await jsonCache.refresh('preferences', {'theme': {'dark':true}, 'notifications':{'enabled':true}});
…
/// Retrieving preferences data.finalMap<String, dynamic>? preferences =await jsonCache.value('preferences');
…
/// Frees up cached data before the user leaves the application.Future<void> signout() async {
await jsonCache.clear();
}
…
/// Removes cached data related to a specific user.Future<void> signoutId(String userId) asyncawait jsonCache.remove(userId);
}JsonCacheMem.init
is the constructor whose purpose is to initialize the cache upon object
instantiation. The data passed to the init parameter is deeply copied to both
the internal in-memory cache and the level2 cache.
…
finalLocalStorage storage =LocalStorage('my_data');
finalMap<String, Map<String, dynamic>?> initData =awaitfetchData();
finalJsonCacheMem jsonCache =JsonCacheMem.init(initData, level2:JsonCacheLocalStorage(storage));
…JsonCacheTry
is an implementation of the JsonCache interface whose sole purpose is to
supply enhanced diagnostic information when a cache failure occurs. It does this
by throwing JsonCacheException
with the underlying stack trace.
Since JsonCacheTry is a
Decorator, you must pass
another JsonCache instance to it whenever you instantiate a JsonCacheTry
object. For example:
…
// Local storage cache initializationfinal sharedPrefs =awaitSharedPreferences.getInstance();
// JsonCacheTry instance initialized with in-memory and local storage caches.final jsonCacheTry =JsonCacheTry(JsonCacheMem(JsonCacheSharedPreferences(sharedPrefs)));
…JsonCacheSharedPreferences is an implementation on top of the shared_preferences package.
…
final sharedPrefs =awaitSharedPreferences.getInstance();
finalJsonCache jsonCache =JsonCacheMem(JsonCacheSharedPreferences(sharedPrefs));
…JsonCacheLocalStorage is an implementation on top of the localstorage package.
import'package:flutter/material.dart';
import'package:localstorage/localstorage.dart';
…
WidgetsFlutterBinding.ensureInitialized();
awaitinitLocalStorage();
finalJsonCache jsonCache =JsonCacheMem(JsonCacheLocalStorage(localStorage));
…JsonCacheSafeLocalStorage is an implementation on top of the safe_local_storage package.
…
final storage =SafeLocalStorage('/path/to/your/cache/file.json');
finalJsonCache jsonCache =JsonCacheMem(JsonCacheSafeLocalStorage(storage));
…JsonCacheFlutterSecureStorage is an implementation on top of the flutter_secure_storage package.
…
final flutterSecureStorage =FlutterSecureStorage(…);
finalJsonCache jsonCache =JsonCacheFlutterSecureStorage(flutterSecureStorage);
// In order to write a string value, define it as a map key whose associated// value is a boolean placeholder value set to 'true'.
jsonCache.refresh('secret', {'a secret info':true});
// later on…final cachedInfo =await jsonCache.value('secret');
final info = cachedInfo?.keys.first; // 'a secret info'JsonCacheHive is an implementation on top of the hive package.
…
awaitHive.initFlutter(); // mandatory initialization.final box =awaitHive.openBox<String>('appBox'); // it must be a Box<String>.finalJsonCache hiveCache =JsonCacheMem(JsonCacheHive(box));
…This package has been designed with unit testing in mind. This is one of the
reasons for the existence of the JsonCache interface.
Since JsonCache is the core interface of this package, you can easily
mock a implementation
that suits you when unit testing your code.
For example, with mocktail a mock implementation should look like this:
import'package:mocktail/mocktail.dart';
classJsonCacheMockextendsMockimplementsJsonCache {}
voidmain() {
// the mock instance.final jsonCacheMock =JsonCacheMock();
test('should retrieve the preferences data', () async {
// Stub the 'value' method.when(() => jsonCacheMock.value('preferences')).thenAnswer(
(_) async=><String, dynamic>{
'theme': {'dark':true},
'notifications': {'enabled':true}
},
);
// Verify no interactions have occurred.verifyNever(() => jsonCacheMock.value('preferences'));
// Interact with the jsonCacheMock instance.final preferencesData =await jsonCacheMock.value('preferences');
// Assertexpect(
preferencesData,
equals(
<String, dynamic>{
'theme': {'dark':true},
'notifications': {'enabled':true}
},
),
);
// Check if the interaction occurred only once.verify(() => jsonCacheMock.value('preferences')).called(1);
});
}
In addition to mocking, there is another approach to unit testing: making use of
a 'fake' implementation. Usually this so-called 'fake' implementation provides
the functionality required by the JsonCache interface without touching the
device's local storage. An example of this implementation is the
JsonCacheFake
class — whose sole purpose is to help developers with unit tests.
Because of the asynchronous nature of dealing with cached data, you're better
off putting all your test code inside a tester.runAsync method; otherwise,
your test case may stall due to a
deadlock caused by a race
condition
as there might be multiple Futures trying to access the same resources at the
same time.
Your widget test code should look similar to the following code snippet:
testWidgets('refresh cached value', (WidgetTester tester) async {
finalLocalStorage localStorage =LocalStorage('my_cached_data');
final jsonCache =JsonCacheMem(JsonCacheLocalStorage(localStorage));
tester.runAsync(() async {
// asynchronous code inside runAsync.await jsonCache.refresh('test', <String, dynamic>{'aKey':'aValue'});
});
});Whenever you run any unit tests involving the
shared_preferences package, you
must call the SharedPreferences.setMockInitialValues() function at the very
beginning of the test file; otherwise, the system may throw an error whose
description is: 'Binding has not yet been initialized'.
Example:
voidmain() {
SharedPreferences.setMockInitialValues({});
// the test cases come below
… }The demo application provides a fully working example, focused on demonstrating the caching API in action. You can take the code in this demo and experiment with it.
To run the demo application:
git clone https://github.com/dartoos-dev/json_cache.git
cd json_cache/example/
flutter run -d chromeThis should launch the demo application on Chrome in debug mode.
Contributors are welcome!
- Open an issue regarding an improvement, a bug you noticed, or ask to be assigned to an existing one.
- If the issue is confirmed, fork the repository, do the changes on a separate branch and make a Pull Request.
- After review and acceptance, the PR is merged and closed.
Make sure the command below passes before making a Pull Request.
flutter analyze && flutter test