feat: JsonCachePrefs class

Closes #17

Author: rafamizes

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- JsonCachePrefs, a implementation on top of the shared_preferences package —
+  [26](https://github.com/dartoos-dev/json_cache/issues/26).
+
+### Changed
+
+- renaming JsonCache methods: erase to remove; recovery to value. **BREAKING
+  CHANGES**.
+
 ## [0.1.0] - 2021-08-22
 
 ### Added

README.md

@@ -1,8 +1,6 @@
 # json_cache
 
-<center>
-  <img width="406" hight="192" alt="json cache logo" src="https://user-images.githubusercontent.com/24878574/119276278-56ef4a80-bbf0-11eb-8701-53a94f24f75b.png" align="middle">
-</center>
+<img width="406" hight="192" alt="json cache logo" src="https://user-images.githubusercontent.com/24878574/119276278-56ef4a80-bbf0-11eb-8701-53a94f24f75b.png" align="middle">
 
 [![EO principles respected
 here](https://www.elegantobjects.org/badge.svg)](https://www.elegantobjects.org)
@@ -28,6 +26,15 @@ Rultor.com](https://www.rultor.com/b/dartoos-dev/json_cache)](https://www.rultor
 
 ## 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](https://en.wikipedia.org/wiki/Cache_(computing))
+
 **Json Cache** 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 [sharable_preferences](https://pub.dev/packages/shared_preferences) and
@@ -57,16 +64,17 @@ 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);
+  /// 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] and returns it or returns null if there
-  /// is no data at [key].
-  Future<Map<String, dynamic>?> erase(String key);
+  /// Removes data from cache at [key].
+  Future<void> remove(String key);
 
-  /// Retrieves either the data at [key] or null if a cache miss occurs.
-  Future<Map<String, dynamic>?> recover(String key);
+  /// Retrieves the data value at [key] or null if a cache miss occurs.
+  Future<Map<String, dynamic>?> value(String key);
 }
 ```
 
@@ -82,7 +90,24 @@ represents the name of a single data group. For example:
 Above, the _profile_ key is associated with the profile-related data group,
 while the _preferences_ key is associated with the preferences-related data.
 
-<!-- @todo #10 Some implementation is needed to add more examples -->
+### JsonCacheMem
+
+It 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.
+
+#### JsonCacheMem Usage
+
+Due to the fact that `JsonCacheMem` is a decorator, you should always pass
+another `JsonCache` instance when you instantiates it. For example:
+
+```dart
+  …
+  final prefs = await SharedPreferences.getInstance();
+  final JsonCacheMem jsonCache = JsonCacheMem(JsonCachePrefs(prefs));
+  …
+```
 
 ## Demo application
 

lib/json_cache.dart

@@ -4,4 +4,5 @@ library json_cache;
 export 'src/json_cache.dart';
 export 'src/json_cache_fake.dart';
 export 'src/json_cache_mem.dart';
+export 'src/json_cache_prefs.dart';
 export 'src/json_cache_wrap.dart';

lib/src/json_cache.dart

@@ -1,16 +1,23 @@
 /// Represents data cached in json.
+///
+///> 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 Wikipedia](https://en.wikipedia.org/wiki/Cache_(computing))
 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);
+  /// 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]. It returns the removed data or null if
-  /// no removal was performed — there was no data at [key].
-  Future<Map<String, dynamic>?> erase(String key);
+  /// Removes data from cache at [key].
+  Future<void> remove(String key);
 
-  /// Retrieves either the data at [key] or null if a cache miss occurs.
-  Future<Map<String, dynamic>?> recover(String key);
+  /// Retrieves the data value at [key] or null if a cache miss occurs.
+  Future<Map<String, dynamic>?> value(String key);
 }

lib/src/json_cache_fake.dart

@@ -4,7 +4,7 @@ import 'package:json_cache/json_cache.dart';
 ///
 /// **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.
+  /// It will share a static memory with other instances.
   JsonCacheFake() : this.mem(_shrMem);
 
   /// Cache with custom memory.
@@ -26,12 +26,12 @@ class JsonCacheFake implements JsonCache {
 
   /// Removes data located at [key].
   @override
-  Future<Map<String, dynamic>?> erase(String key) async => _memory.remove(key);
+  Future<void> remove(String key) async => _memory.remove(key);
 
-  /// Retrieves the data at [key] or null if there is no data.
+  /// Retrieves a copy of the data at [key] or null if there is no data.
   @override
-  Future<Map<String, dynamic>?> recover(String key) async {
+  Future<Map<String, dynamic>?> value(String key) async {
     final cached = _memory[key];
-    return cached == null ? cached : Map<String, dynamic>.of(cached);
+    return cached == null ? null : Map<String, dynamic>.of(cached);
   }
 }

lib/src/json_cache_mem.dart

@@ -11,21 +11,17 @@ import 'json_cache.dart';
 ///
 /// 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);
+  /// Encapsulates a slower [level2] cache and utilizes a static memory that
+  /// will be shared (without race conditions) among all [JsonCacheMem] objects
+  /// that have been instantiated with this constructor.
+  JsonCacheMem(JsonCache level2) : this.mem(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,
+  /// Cache with custom memory and an optional custom mutex.
+  JsonCacheMem.mem(JsonCache level2, Map<String, Map<String, dynamic>?> mem,
+      [ReadWriteMutex? mutex])
+      : _level2 = level2,
         _memory = mem,
-        _mutex = mutex;
+        _mutex = mutex ?? ReadWriteMutex();
 
   /// Slower cache level.
   final JsonCache _level2;
@@ -70,22 +66,22 @@ class JsonCacheMem implements JsonCache {
     });
   }
 
-  /// Removes data located at [key] from both the level2 cache and in-memory
-  /// cache.
+  /// Removes the value 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);
+  Future<void> remove(String key) async {
+    await _mutex.protectWrite(() async {
+      await _level2.remove(key);
+      _memory.remove(key);
     });
   }
 
-  /// Retrieves the data at [key] or null if there is no data.
+  /// Retrieves the value at [key] or null if there is no data.
   @override
-  Future<Map<String, dynamic>?> recover(String key) async {
+  Future<Map<String, dynamic>?> value(String key) async {
     return _mutex.protectRead(() async {
       if (!_memory.containsKey(key)) {
-        _memory[key] = await _level2.recover(key);
+        _memory[key] = await _level2.value(key);
       }
       final cached = _memory[key];
       return cached == null ? cached : Map<String, dynamic>.of(cached);

lib/src/json_cache_prefs.dart

@@ -0,0 +1,45 @@
+import 'dart:convert';
+
+import 'package:shared_preferences/shared_preferences.dart';
+
+import 'json_cache.dart';
+
+/// Persistent preferences file cache.
+class JsonCachePrefs implements JsonCache {
+  /// [_prefs] a [SharedPreferences] instance.
+  const JsonCachePrefs(this._prefs);
+
+  // The preferences file object.
+  final SharedPreferences _prefs;
+
+  /// Frees up the preferences file space.
+  @override
+  Future<void> clear() async {
+    await _prefs.clear();
+  }
+
+  /// Removes an entry from the preferences file storage at [key].
+  @override
+  Future<void> remove(String key) async {
+    await _prefs.remove(key);
+  }
+
+  /// Writes [value] to the preferences file.
+  ///
+  /// **Note**: [value] must be json encodable — `json.encode()` is called under
+  /// the hood.
+  @override
+  Future<void> refresh(String key, Map<String, dynamic> value) async {
+    await _prefs.setString(key, json.encode(value));
+  }
+
+  /// The value at [key] from the preferences file; it returns null if a cache
+  /// miss occurs.
+  @override
+  Future<Map<String, dynamic>?> value(String key) async {
+    final strJson = _prefs.getString(key);
+    return strJson == null
+        ? null
+        : json.decode(strJson) as Map<String, dynamic>;
+  }
+}

lib/src/json_cache_wrap.dart

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