json_cache 0.3.0

An object-oriented package for caching user data locally in json; a combinable layer on top of local storage packages that unifies them as an elegant caching API.

json_cache

Contents

• Overview
• Getting Started
• List of JsonCache implementations
  • JsonCacheMem — Thread-safe In-memory cache
  • JsonCachePrefs — SharedPreferences
  • JsonCacheLocalStorage — LocalStorage
• Demo application
• References

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.

— Cache_(computing) (2021, August 22). In Wikipedia, The Free Encyclopedia. Retrieved 09:55, August 22, 2021

JsonCache is an object-oriented package to cache user data locally in json. It can also be thought of as a layer on top of Flutter's local storage packages like the sharable_preferences and localstorage packages.

The ultimate goal of this package is to unify Flutter's main local caching packages into an elegant caching API.

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 data cached in json.
abstract class JsonCache {
  /// Frees up storage space.
  Future<void> clear();

  /// It either updates the data found at [key] with [value] or, if there is no
  /// previous 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);

  /// Removes data from cache at [key].
  Future<void> remove(String key);

  /// Retrieves the data value at [key] or null if a cache miss occurs.
  Future<Map<String, dynamic>?> value(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': '[e-mail]', 'accountType': 'premium'};
'preferences': {'theme': {'dark': true}, 'notifications':{'enabled': true}}

Above, the profile key is associated with the profile-related data group, while the preferences key is associated with the preferences-related data.

List of JsonCache 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 is a thread-safe in-memory implementation of the JsonCache interface. Moreover, it encapsulates a secondary cache or "slower level2 cache". Typically, the secondary cache instance is responsible for the local cache; that is, it is the cache instance that persists data on the user's device.

Typical Usage

Due to the fact that JsonCacheMem is a decorator, you should always pass another JsonCache instance to it whenever you instantiates a JsonCacheMem object. For example:

  …
  final prefs = await SharedPreferences.getInstance();
  final JsonCacheMem jsonCache = JsonCacheMem(JsonCachePrefs(prefs));
  …

In addition, JsonCacheMem has the JsonCacheMem.init constructor whose purpose is the initialize the cache. Data is deep copied from the initialization buffer to its internal in-memory cache and to its level2 cache as well.

  …
  final LocalStorage storage = LocalStorage('my_data');
  final Map<String, Map<String, dynamic>?> initData = await fetchInfo();
  final JsonCacheMem jsonCache = JsonCacheMem.init(initData, level2:JsonCacheLocalStorage(storage));
  …

JsonCachePrefs

JsonCachePrefs is an implementation on top of the shared_preferences package.

  …
  final prefs = await SharedPreferences.getInstance();
  final JsonCache jsonCache = JsonCacheMem(JsonCachePrefs(prefs));
  …

JsonCacheLocalStorage

JsonCacheLocalStorage is an implementation on top of the localstorage

  …
  final LocalStorage storage = LocalStorage('my_data');
  final JsonCache jsonCache = JsonCacheMem(JsonCacheLocalStorage(storage));
  …

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.

References

• Caching for objects
• Dart and race conditions