style: pub dev fixes

* refactor! rename JsonCacheMem.mem to JsonCacheMem.ext

* refactor!: revert JsonCacheMem.mem constructor

* style: pub dev fixes

* style: run flutter format

* refactor: more efficient refresh impl.

Author: rafamizes

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- several fixes and improvements to documentation.
+- run flutter format.
+
 ## [0.3.0] - 2021-08-25
 
 ### Added

README.md

@@ -44,8 +44,8 @@ It can also be thought of as a layer on top of Flutter's local storage packages
 like the [sharable_preferences](https://pub.dev/packages/shared_preferences) and
 [localstorage](https://pub.dev/packages/localstorage) packages.
 
-The ultimate goal of this package is to unify Flutter's main local caching
-packages into an elegant caching API.
+Therefore, this package aims to unify most of Flutter's local caching packages
+into an elegant caching API.
 
 **Why Json?**
 
@@ -64,22 +64,22 @@ requirements.
 cached data. It is defined as:
 
 ```dart
-/// Represents data cached in json.
+/// Represents cached data in json format.
 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
+  /// 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
   /// 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);
 }
 ```
 
@@ -95,6 +95,15 @@ 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.
 
+A typical code for saving the previous _profile_ and _preferences_ data is:
+
+```dart
+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}});
+```
+
 ## List of JsonCache Implementations
 
 The library
@@ -121,9 +130,26 @@ object. For example:
 
 ```dart
   …
+  /// 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': '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);
+  }
 ```
 
 In addition, `JsonCacheMem` has the `JsonCacheMem.init` constructor whose

lib/src/json_cache.dart

@@ -1,4 +1,4 @@
-/// Represents data cached in json.
+/// Represents cached data in json format.
 ///
 ///> 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
@@ -9,15 +9,15 @@ abstract class JsonCache {
   /// Frees up storage space.
   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 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].
+  /// previous data at [key], creates a new cache line 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);
 }

lib/src/json_cache_mem.dart

@@ -28,22 +28,16 @@ class JsonCacheMem implements JsonCache {
   /// prototyping or mocking phase. However, its unlikely to be the right
   /// behavior in production code.
   JsonCacheMem([JsonCache? level2])
-<<<<<<< HEAD
-      : this.ext(_shrMem, level2: level2, mutex: _shrMutex);
-=======
       : this.mem(_shrMem, level2: level2, mutex: _shrMutex);
->>>>>>> 32
 
-  /// Cache with initial data.
-  ///
-  /// Besides copying data from [init] to its internal shared memory, it
-  /// encapsulates a [level2] cache that is supposed to persist data to the
-  /// user's device's local storage area.
+  /// Initializes both the level1 (internal memory) and level2 (user's device's
+  /// local storage area) caches with data.
   ///
   /// It also provides a type of transaction guarantee whereby, if an error
-  /// occurs while copying [init] to the cache, it tries to revert the cached
-  /// data to its previous state before rethrowing the exception. Finally, after
-  /// reverting the cached data, it invokes [onInitError].
+  /// occurs while copying [init] to cache, it will try to revert the cached
+  /// data to its previous state before rethrowing the exception that signaled
+  /// the error. Finally, after reverting the cached data, it invokes
+  /// [onInitError].
   JsonCacheMem.init(
     Map<String, Map<String, dynamic>?> init, {
     JsonCache? level2,
@@ -80,11 +74,7 @@ class JsonCacheMem implements JsonCache {
   /// Cache with an external memory and an optional custom mutex.
   ///
   /// **Note**: the memory [mem] will **not** be copied deeply.
-<<<<<<< HEAD
-  JsonCacheMem.ext(
-=======
   JsonCacheMem.mem(
->>>>>>> 32
     Map<String, Map<String, dynamic>?> mem, {
     JsonCache? level2,
     ReadWriteMutex? mutex,
@@ -147,7 +137,7 @@ class JsonCacheMem implements JsonCache {
 
   /// Retrieves the value at [key] or null if there is no data.
   @override
-  Future<Map<String, dynamic>?> value(String key) async {
+  Future<Map<String, dynamic>?> value(String key) {
     return _mutex.protectRead(() async {
       final cachedL1 = _memory[key];
       if (cachedL1 != null) return Map<String, dynamic>.of(cachedL1);
@@ -157,7 +147,6 @@ class JsonCacheMem implements JsonCache {
         _memory[key] = cachedL2;
         return Map<String, dynamic>.of(cachedL2);
       }
-
       return null;
     });
   }

pubspec.lock

@@ -7,7 +7,7 @@ packages:
       name: async
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "2.6.1"
+    version: "2.8.1"
   boolean_selector:
     dependency: transitive
     description:
@@ -28,7 +28,7 @@ packages:
       name: charcode
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.2.0"
+    version: "1.3.1"
   clock:
     dependency: transitive
     description:
@@ -120,7 +120,7 @@ packages:
       name: meta
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.3.0"
+    version: "1.7.0"
   mutex:
     dependency: "direct main"
     description:
@@ -279,7 +279,7 @@ packages:
       name: test_api
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "0.3.0"
+    version: "0.4.2"
   typed_data:
     dependency: transitive
     description:

test/json_cache_fake_test.dart

@@ -38,23 +38,13 @@ void main() {
       });
       test('mem ctor', () async {
         final copy = Map<String, Map<String, dynamic>?>.of(data);
-<<<<<<< HEAD
-        final JsonCacheFake memMemCache = JsonCacheFake.mem(copy);
-        await memMemCache.clear();
-
-        final cachedProf = await memMemCache.value(profKey);
-        expect(cachedProf, isNull);
-
-        final cachedPref = await memMemCache.value(prefKey);
-=======
         final JsonCacheFake memCache = JsonCacheFake.mem(copy);
         await memCache.clear();
 
         final cachedProf = await memCache.value(profKey);
         expect(cachedProf, isNull);
 
         final cachedPref = await memCache.value(prefKey);
->>>>>>> 32
         expect(cachedPref, isNull);
 
         expect(copy.isEmpty, true);