json_cache 1.4.0

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

json_cache

Contents

• Overview
• Getting Started
  • Storing Simple Values
  • Suggested Dependency Relationship
• Implementations
  • JsonCacheMem — Thread-safe In-memory cache
  • JsonCacheTry — Enhanced Diagnostic Messages
  • JsonCachePrefs — SharedPreferences
  • JsonCacheEncPrefs — EncryptedSharedPreferences
  • JsonCacheLocalStorage — LocalStorage
  • JsonCacheSecStorage — FlutterSecureStorage
  • JsonCacheCrossLocalStorage — CrossLocalStorage
  • JsonCacheHive — Hive
• Unit Test Tips
  • Mocking
  • Fake Implementations
  • Widget Testing
    • Example of Widget Test Code
  • SharedPreferences in Tests
• Demo application
• Contribute
• 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 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': '[e-mail]', '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': '[e-mail]', '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 simple text information.
  jsonCache.refresh('info', {'an 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); // 'an 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 prefs = await SharedPreferences.getInstance();
  final JsonCacheMem jsonCache = JsonCacheMem(JsonCachePrefs(prefs));
  …
  /// Saving profile and preferences data.
  await jsonCache.refresh('profile', {'name': 'John Doe', 'email': '[e-mail]', '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 a JsonCacheException exception.

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 prefs = await SharedPreferences.getInstance();
  // JsonCacheTry instance initialized with in-memory and local storage caches.
  final jsonCacheTry = JsonCacheTry(JsonCacheMem(JsonCachePrefs(prefs)));
  …

JsonCachePrefs

JsonCachePrefs is an implementation on top of the shared_preferences package.

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

JsonCacheEncPrefs

JsonCacheEncPrefs is an implementation on top of the encrypted_shared_preferences package.

  …
  final encPrefs = EncryptedSharedPreferences();
  final JsonCache jsonCache = JsonCacheMem(JsonCacheEncPrefs(encPrefs));
  …

JsonCacheLocalStorage

JsonCacheLocalStorage is an implementation on top of the localstorage package.

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

JsonCacheSecStorage

JsonCacheSecStorage is an implementation on top of the flutter_secure_storage package.

  …
  final secStorage = FlutterSecureStorage(…);
  final JsonCache jsonCache = JsonCacheSecStorage(secStorage);
  // 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'

JsonCacheCrossLocalStorage

JsonCacheLocalCrossStorage is an implementation on top of the cross_local_storage package.

  …
  final LocalStorageInterface prefs = await LocalStorage.getInstance();
  final JsonCache jsonCache = JsonCacheMem(JsonCacheCrossLocalStorage(prefs));

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!

1. Open an issue regarding an improvement, a bug you noticed, or ask to be assigned to an existing one.
2. If the issue is confirmed, fork the repository, do the changes on a separate branch and make a Pull Request.
3. 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

• Dart and race conditions