feat: JsonCache interface and Fake, Mem, Wrap impl

Author: rafamizes

README.md

@@ -28,39 +28,38 @@ Rultor.com](https://www.rultor.com/b/dartoos-dev/json_cache)](https://www.rultor
 
 ## Overview
 
-**Json Cache** is an object-oriented package to serve as a layer on top of local
-storage packages, unifying them as an elegant caching API.
+**Json Cache** is an object-oriented layer on top of local storage packages to
+unify them as an elegant caching API.
 
 In addition, this package gives developers great flexibility by providing a set
-of classes that can be selected and combined in various ways to meet specific
-requirements.
+of classes that can be selected and grouped in various combinations to meet
+specific cache requirements.
 
 **Why Json?**
 
 - Because most of the local storage packages available for Flutter applications
   use json as the data format.
-- There is an one-to-one relationship between the Dart's built-in type
-  `Map<String, dynamic>` and json, which makes json encoding/decoding a
-  trivial task.
+- 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
 
 `JsonCache` is the core interface of this package and represents the concept of
 cached data. It is defined as:
 
 ```dart
-/// Represents a cached json data.
+/// Represents data cached in json.
 abstract class JsonCache {
   /// Frees up cache storage space.
   Future<void> clear();
 
-  /// Refreshes some cached data by its associated key.
+  /// Updates cached data found by its associated [key].
   Future<void> refresh(String key, Map<String, dynamic> data);
 
   /// Erases [key] and returns its associated data.
   Future<Map<String, dynamic>?> erase(String key);
 
-  /// Recovers some cached data; null if a cache miss occurs - no [key] found.
+  /// Recovers cached data by [key]; returns null if a cache miss occurs.
   Future<Map<String, dynamic>?> recover(String key);
 }
 ```
@@ -96,3 +95,6 @@ flutter run -d chrome
 This should launch the demo application on Chrome in debug mode.
 
 ## References
+
+- [Caching for objects](https://www.pragmaticobjects.com/chapters/012_caching_for_objects.html)
+- [Dart and race conditions](https://pub.dev/packages/mutex)

lib/json_cache.dart

@@ -1,7 +1,7 @@
+/// Collection of json cache decorators.
 library json_cache;
 
-/// A Calculator.
-class Calculator {
-  /// Returns [value] plus 1.
-  int addOne(int value) => value + 1;
-}
+export 'src/json_cache.dart';
+export 'src/json_cache_fake.dart';
+export 'src/json_cache_mem.dart';
+export 'src/json_cache_wrap.dart';

lib/src/json_cache.dart

@@ -0,0 +1,16 @@
+/// Represents data cached in json.
+abstract class JsonCache {
+  /// Frees up storage space.
+  Future<void> clear();
+
+  /// Updates data at [key], or creates a new cache line at [key] if there is no
+  /// previous data there.
+  Future<void> refresh(String key, Map<String, dynamic> data);
+
+  /// Removes data from cache at [key] and returns it, or returns null if there
+  /// is no data at [key].
+  Future<Map<String, dynamic>?> erase(String key);
+
+  /// Retrieves either the data at [key] or null if a cache miss occurs.
+  Future<Map<String, dynamic>?> recover(String key);
+}

lib/src/json_cache_fake.dart

@@ -0,0 +1,37 @@
+import 'package:json_cache/json_cache.dart';
+
+/// In-memory cache. It is intended for unit testing and prototyping.
+///
+/// **Warning**: do not use it in production code. It is not thread safe.
+class JsonCacheFake implements JsonCache {
+  /// Default ctor. Shares a static memory with other instances.
+  JsonCacheFake() : this.mem(_shrMem);
+
+  /// Cache with custom memory.
+  JsonCacheFake.mem(this._memory);
+
+  /// in-memory storage.
+  final Map<String, Map<String, dynamic>?> _memory;
+
+  static final Map<String, Map<String, dynamic>> _shrMem = {};
+
+  /// Clears the internal map.
+  @override
+  Future<void> clear() async => _memory.clear();
+
+  /// Updates data located at [key].
+  @override
+  Future<void> refresh(String key, Map<String, dynamic> data) async =>
+      _memory[key] = Map<String, dynamic>.of(data);
+
+  /// Removes data located at [key].
+  @override
+  Future<Map<String, dynamic>?> erase(String key) async => _memory.remove(key);
+
+  /// Retrieves the data at [key] or null if there is no data.
+  @override
+  Future<Map<String, dynamic>?> recover(String key) async {
+    final cached = _memory[key];
+    return cached == null ? cached : Map<String, dynamic>.of(cached);
+  }
+}

lib/src/json_cache_mem.dart

@@ -0,0 +1,94 @@
+import 'package:mutex/mutex.dart';
+
+import 'json_cache.dart';
+
+/// Thread-safe, in-memory [JsonCache] decorator.
+///
+/// It is a kind of level 1 cache.
+///
+/// TODO: limit the maximum number of cache entries via "size" parameter in
+/// constructors.
+///
+/// It encapsulates a slower chache but keeps its own data in-memory.
+class JsonCacheMem implements JsonCache {
+  /// Default ctor. [level2] the slower level 2 cache.
+  JsonCacheMem(JsonCache level2) : this.main(level2, _shrMem, _shrMutex);
+
+  /// Cache with custom memory.
+  JsonCacheMem.mem(JsonCache level2, Map<String, Map<String, dynamic>?> mem)
+      : this.main(level2, mem, ReadWriteMutex());
+
+  /// Main ctor.
+  JsonCacheMem.main(
+    JsonCache level2,
+    Map<String, Map<String, dynamic>?> mem,
+    ReadWriteMutex mutex,
+  )   : _level2 = level2,
+        _memory = mem,
+        _mutex = mutex;
+
+  /// Slower cache level.
+  final JsonCache _level2;
+
+  /// in-memory storage.
+  final Map<String, Map<String, dynamic>?> _memory;
+
+  /// Mutex lock-guard.
+  final ReadWriteMutex _mutex;
+
+  /// in-memory shared storage.
+  static final Map<String, Map<String, dynamic>> _shrMem = {};
+
+  /// shared mutex.
+  static final _shrMutex = ReadWriteMutex();
+
+  /// Frees up storage space in both the level2 cache and in-memory cache.
+  @override
+  Future<void> clear() async {
+    await _mutex.protectWrite(() async {
+      await _level2.clear();
+      _memory.clear();
+    });
+  }
+
+  /// Updates data located at [key] in both the level2 cache and in-memory
+  /// cache.
+  @override
+  Future<void> refresh(String key, Map<String, dynamic> data) async {
+    /// ATTENTION: It is safer to copy the content of [data] before calling an
+    /// asynchronous method that will copy it to avoid data races. For example,
+    /// if the client code clears [data] right after passing it to this method,
+    /// there's a high chance of having _level2 and this object with different
+    /// contents.
+    ///
+    /// In Dart, synchronous code cannot be interrupted, so there is no need to
+    /// protect it using mutual exclusion.
+    final copy = Map<String, dynamic>.of(data);
+    await _mutex.protectWrite(() async {
+      await _level2.refresh(key, copy);
+      _memory[key] = copy;
+    });
+  }
+
+  /// Removes data located at [key] from both the level2 cache and in-memory
+  /// cache.
+  @override
+  Future<Map<String, dynamic>?> erase(String key) async {
+    return _mutex.protectWrite(() async {
+      await _level2.erase(key);
+      return _memory.remove(key);
+    });
+  }
+
+  /// Retrieves the data at [key] or null if there is no data.
+  @override
+  Future<Map<String, dynamic>?> recover(String key) async {
+    return _mutex.protectRead(() async {
+      if (!_memory.containsKey(key)) {
+        _memory[key] = await _level2.recover(key);
+      }
+      final cached = _memory[key];
+      return cached == null ? cached : Map<String, dynamic>.of(cached);
+    });
+  }
+}

lib/src/json_cache_wrap.dart

@@ -0,0 +1,29 @@
+import 'json_cache.dart';
+
+///  Decorator Envelope of [JsonCache].
+///
+/// It just forwards method calls to its encapsulated [JsonCache] instance.
+abstract class JsonCacheWrap implements JsonCache {
+  /// Ctor.
+  const JsonCacheWrap(this._wrapped);
+
+  // wrapped instance.
+  final JsonCache _wrapped;
+
+  /// Forwards to its encapsulated [JsonCache] instance.
+  @override
+  Future<void> clear() => _wrapped.clear();
+
+  /// Forwards to its encapsulated [JsonCache] instance.
+  @override
+  Future<Map<String, dynamic>?> erase(String key) => _wrapped.erase(key);
+
+  /// Forwards to its encapsulated [JsonCache] instance.
+  @override
+  Future<Map<String, dynamic>?> recover(String key) => _wrapped.recover(key);
+
+  /// Forwards to its encapsulated [JsonCache] instance.
+  @override
+  Future<void> refresh(String key, Map<String, dynamic> data) =>
+      _wrapped.refresh(key, data);
+}

pubspec.lock

@@ -7,7 +7,7 @@ packages:
       name: async
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "2.7.0"
+    version: "2.8.1"
   boolean_selector:
     dependency: transitive
     description:
@@ -81,6 +81,13 @@ packages:
       url: "https://pub.dartlang.org"
     source: hosted
     version: "1.7.0"
+  mutex:
+    dependency: "direct main"
+    description:
+      name: mutex
+      url: "https://pub.dartlang.org"
+    source: hosted
+    version: "3.0.0"
   path:
     dependency: transitive
     description:
@@ -134,7 +141,7 @@ packages:
       name: test_api
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "0.4.1"
+    version: "0.4.2"
   typed_data:
     dependency: transitive
     description:

pubspec.yaml

@@ -11,6 +11,7 @@ environment:
 dependencies:
   flutter:
     sdk: flutter
+  mutex: ^3.0.0
 
 dev_dependencies:
   flutter_test:

test/json_cache_mem_test.dart

@@ -0,0 +1,14 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:json_cache/json_cache.dart';
+
+void main() {
+  group('JsonCacheMem', () {
+    test('clear', () async {
+      final Map<String, Map<String, dynamic>> data = {
+        'profile': <String, dynamic>{'id': 1, 'name': 'John Due'}
+      };
+      await JsonCacheMem.mem(JsonCacheFake.mem(data), data).clear();
+      expect(data.isEmpty, true);
+    });
+  });
+}