json_cache
Contents
Overview
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.
Getting Started
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 interface of this package and represents the concept of cached data. It is defined as:
/// Represents cached data in json format.
abstract class JsonCache {
/// 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);
}
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:
final JsonCache 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}});
Storing Simple Values
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.'
Suggested Dependency Relationship
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.
class JsonCacheRepository implements ILocalRepository {
/// Sets the [JsonCache] instance.
const JsonCacheRepository(this._cache);
// This class depends on an interface rather than any actual implementation
final JsonCache _cache;
/// Retrieves a cached email by [userId] or `null` if not found.
@override
Future<String?> getUserEmail(String userId) async {
final userData = await _cache.value(userId);
if (userData != null) {
// the email value or null if absent.
return userData['email'] as String?;
}
// There is no data associated with [userId].
return null;
}
}
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.
Implementations
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
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.
Typical Usage
Since JsonCacheMem is a
Decorator, you should
normally pass another JsonCache instance to it whenever you instantiate a
JsonCacheMem object. For example:
…
/// Cache initialization
final sharedPrefs = await SharedPreferences.getInstance();
final JsonCacheMem 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.
final Map<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) async
await jsonCache.remove(userId);
}
Cache Initialization
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.
…
final LocalStorage storage = LocalStorage('my_data');
final Map<String, Map<String, dynamic>?> initData = await fetchData();
final JsonCacheMem jsonCache = JsonCacheMem.init(initData, level2:JsonCacheLocalStorage(storage));
…
JsonCacheTry
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 initialization
final sharedPrefs = await SharedPreferences.getInstance();
// JsonCacheTry instance initialized with in-memory and local storage caches.
final jsonCacheTry = JsonCacheTry(JsonCacheMem(JsonCacheSharedPreferences(sharedPrefs)));
…
JsonCacheSharedPreferences
JsonCacheSharedPreferences is an implementation on top of the shared_preferences package.
…
final sharedPrefs = await SharedPreferences.getInstance();
final JsonCache jsonCache = JsonCacheMem(JsonCacheSharedPreferences(sharedPrefs));
…
JsonCacheLocalStorage
JsonCacheLocalStorage is an implementation on top of the localstorage package.
…
final LocalStorage storage = LocalStorage('my_data');
final JsonCache jsonCache = JsonCacheMem(JsonCacheLocalStorage(storage));
…
JsonCacheSafeLocalStorage
JsonCacheSafeLocalStorage is an implementation on top of the safe_local_storage package.
…
final storage = SafeLocalStorage('/path/to/your/cache/file.json');
final JsonCache jsonCache = JsonCacheMem(JsonCacheSafeLocalStorage(storage));
…
JsonCacheFlutterSecureStorage
JsonCacheFlutterSecureStorage is an implementation on top of the flutter_secure_storage package.
…
final flutterSecureStorage = FlutterSecureStorage(…);
final JsonCache 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
JsonCacheHive is an implementation on top of the hive package.
…
await Hive.initFlutter(); // mandatory initialization.
final box = await Hive.openBox<String>('appBox'); // it must be a Box<String>.
final JsonCache hiveCache = JsonCacheMem(JsonCacheHive(box));
…
Unit Test Tips
This package has been designed with unit testing in mind. This is one of the
reasons for the existence of the JsonCache interface.
Mocking
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';
class JsonCacheMock extends Mock implements JsonCache {}
void main() {
// 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');
// Assert
expect(
preferencesData,
equals(
<String, dynamic>{
'theme': {'dark': true},
'notifications': {'enabled': true}
},
),
);
// Check if the interaction occurred only once.
verify(() => jsonCacheMock.value('preferences')).called(1);
});
}
Fake Implementations
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.
Widget Testing
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.
Example of Widget Test Code
Your widget test code should look similar to the following code snippet:
testWidgets('refresh cached value', (WidgetTester tester) async {
final LocalStorage 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'});
});
});
SharedPreferences in Tests
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:
void main() {
SharedPreferences.setMockInitialValues({});
// the test cases come below
…
}
Demo application
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 chrome
This should launch the demo application on Chrome in debug mode.
Contribute
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
References
Libraries
- json_cache
- A collection of JsonCache decorators.