feat: 'JsonCacheException' and 'JsonCacheTry' (#101)

Author: rafamizes

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- JsonCacheTry: an implementation that throws a `JsonCacheException` when a
+  cache failure occurs —
+  [100](https://github.com/dartoos-dev/json_cache/issues/100).
+
+- JsonCacheException: an exception that conveys enhanced diagnostic messages
+  about cache operation failures —
+  [100](https://github.com/dartoos-dev/json_cache/issues/100).
+
+### Changed
+
+- Improvements to the README file.
+
 ## [1.3.1] - 2022-08-25
 
 ### Changed

README.md

@@ -27,6 +27,7 @@ Rultor.com](https://www.rultor.com/b/dartoos-dev/json_cache)](https://www.rultor
   - [Suggested Dependency Relationship](#suggested-dependency-relationship)
 - [Implementations](#implementations)
   - [JsonCacheMem — Thread-safe In-memory cache](#jsoncachemem)
+  - [JsonCacheTry — Enhanced Diagnostic Messages](#jsoncachetry)
   - [JsonCachePrefs — SharedPreferences](#jsoncacheprefs)
   - [JsonCacheEncPrefs — EncryptedSharedPreferences](#jsoncacheencprefs)
   - [JsonCacheLocalStorage — LocalStorage](#jsoncachelocalstorage)
@@ -194,9 +195,10 @@ device.
 
 #### Typical Usage
 
-Due to the fact that `JsonCacheMem` is a [Decorator](https://en.wikipedia.org/wiki/Decorator_pattern),
-you should normally pass another `JsonCache` instance to it whenever you instantiate a `JsonCacheMem`
-object. For example:
+Since `JsonCacheMem` is a
+[Decorator](https://en.wikipedia.org/wiki/Decorator_pattern), you should
+normally pass another `JsonCache` instance to it whenever you instantiate a
+`JsonCacheMem` object. For example:
 
 ```dart
   …
@@ -232,11 +234,34 @@ the internal in-memory cache and the level2 cache.
 ```dart
   …
   final LocalStorage storage = LocalStorage('my_data');
-  final Map<String, Map<String, dynamic>?> initData = await fetchInfo();
+  final Map<String, Map<String, dynamic>?> initData = await fetchData();
   final JsonCacheMem jsonCache = JsonCacheMem.init(initData, level2:JsonCacheLocalStorage(storage));
   …
 ```
 
+### JsonCacheTry
+
+[JsonCacheTry](https://pub.dev/documentation/json_cache/latest/json_cache/JsonCacheTry-class.html)
+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](https://pub.dev/documentation/json_cache/latest/json_cache/JsonCacheException-class.html)
+exception.
+
+Since `JsonCacheTry` is a
+[Decorator](https://en.wikipedia.org/wiki/Decorator_pattern), you must pass
+another `JsonCache` instance to it whenever you instantiate a `JsonCacheTry`
+object. For example:
+
+```dart
+  …
+  // 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](https://pub.dev/documentation/json_cache/latest/json_cache/JsonCachePrefs-class.html)

lib/json_cache.dart

@@ -4,6 +4,7 @@ library json_cache;
 export 'src/json_cache.dart';
 export 'src/json_cache_cross_local_storage.dart';
 export 'src/json_cache_enc_prefs.dart';
+export 'src/json_cache_exception.dart';
 export 'src/json_cache_fake.dart';
 export 'src/json_cache_hive.dart';
 export 'src/json_cache_hollow.dart';

lib/src/json_cache.dart

@@ -9,10 +9,10 @@ abstract class JsonCache {
   /// Frees up storage space — deletes all keys and values.
   Future<void> clear();
 
-  /// Removes cached data located at [key].
+  /// Removes the cached data located at [key].
   Future<void> remove(String key);
 
-  /// Retrieves cached data located at [key] or `null` if a cache miss occurs.
+  /// Retrieves the 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
@@ -21,7 +21,7 @@ abstract class JsonCache {
   /// **Note**: [value] must be json encodable.
   Future<void> refresh(String key, Map<String, dynamic> value);
 
-  /// Checks for cached data located at [key].
+  /// Checks for cached data at [key].
   ///
   /// Returns `true` if there is cached data at [key]; `false` otherwise.
   Future<bool> contains(String key);

lib/src/json_cache_exception.dart

@@ -0,0 +1,26 @@
+/// An exception to indicate cache operation failures.
+class JsonCacheException<T extends Object> implements Exception {
+  /// Sets [extra] as aditional information and [exception] as the original
+  /// exception.
+  const JsonCacheException({required this.extra, this.exception});
+
+  /// Additional information about cache operation failure.
+  ///
+  /// Its `toString` method will be part of this exception's error message.
+  final T extra;
+
+  /// The original exception that indicated the failure of the caching
+  /// operation.
+  final Exception? exception;
+
+  /// Returns [extra] along with the original exception message.
+  @override
+  String toString() => '$extra$_separator$_originalExceptionMessage';
+
+  /// Returns '\n' if [exception] is set; otherwise, the empty string ''.
+  String get _separator => exception != null ? '\n' : '';
+
+  /// Returns the exception message if [exception] is set; otherwise, the empty
+  /// string ''.
+  String get _originalExceptionMessage => exception?.toString() ?? '';
+}

lib/src/json_cache_mem.dart

@@ -10,51 +10,51 @@ typedef OnInitError = FutureOr<Null> Function(Object, StackTrace);
 
 /// Thread-safe in-memory [JsonCache] decorator.
 ///
-/// It is a kind of level 1 cache.
+/// It is a kind of _level 1_ cache.
 ///
 /// It encapsulates a slower cache and keeps its own data in-memory.
 class JsonCacheMem implements JsonCache {
-  /// In-memory level1 cache with an optional level2 instance.
+  /// In-memory _level 1_ cache with an optional _level 2_ instance.
   ///
   /// **Note**: if you do not pass an object to the parameter [level2], the data
   /// will remain cached in-memory only; that is, no data will be persited to
-  /// the user's device's local storage area. Indeed, not persisting data on the
+  /// the local storage of the user's device. Indeed, not persisting data on the
   /// user's device might be the desired behavior if you are at the prototyping
   /// or mocking phase. However, its unlikely to be the right behavior in
   /// production code.
   JsonCacheMem([JsonCache? level2])
       : this.mem(_shrMem, level2: level2, mutex: _shrMutex);
 
-  /// Initializes both the level1 (internal memory) and level2 (user's device's
-  /// local storage area) caches with data.
+  /// Initializes both the internal memory (level 1 cache) and the local storage
+  /// of the user's device (level 2 cache — [level2]) with the contents of
+  /// [initData].
   ///
-  /// It also provides a type of transaction guarantee whereby, if an error
-  /// 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].
+  /// This method also provides a kind of transaction guarantee whereby if an
+  /// error occurs while copying [initData] to the cache, it will attempt to
+  /// revert the cache [level2] to its previous state before rethrowing the
+  /// exception that signaled the error. Finally, after reverting the cached
+  /// data, it will invoke [onInitError].
   JsonCacheMem.init(
-    Map<String, Map<String, dynamic>?> init, {
+    Map<String, Map<String, dynamic>?> initData, {
     JsonCache? level2,
     OnInitError? onInitError,
   })  : _level2 = level2 ?? const JsonCacheHollow(),
         _memory = _shrMem,
         _mutex = _shrMutex {
-    final copy = Map<String, Map<String, dynamic>?>.of(init);
     final initFut = _mutex.protectWrite(() async {
-      final writes = <String>[]; // the list of written keys.
-      for (final entry in copy.entries) {
+      final cachedKeys = <String>[];
+      for (final entry in initData.entries) {
         final key = entry.key;
         final value = entry.value;
         if (value != null) {
-          writes.add(key);
+          cachedKeys.add(key);
           try {
             await _level2.refresh(key, value);
             _memory[key] = value;
           } catch (error) {
-            for (final write in writes) {
-              await _level2.remove(write);
-              _memory.remove(write);
+            for (final key in cachedKeys) {
+              await _level2.remove(key);
+              _memory.remove(key);
             }
             rethrow;
           }
@@ -77,7 +77,7 @@ class JsonCacheMem implements JsonCache {
         _level2 = level2 ?? const JsonCacheHollow(),
         _mutex = mutex ?? ReadWriteMutex();
 
-  /// Slower cache level.
+  /// Slower level 2 cache.
   final JsonCache _level2;
 
   /// In-memory storage.
@@ -93,6 +93,8 @@ class JsonCacheMem implements JsonCache {
   static final _shrMutex = ReadWriteMutex();
 
   /// Frees up storage space in both the level2 cache and in-memory cache.
+  ///
+  /// Throws [JsonCacheException] to indicate operation failure.
   @override
   Future<void> clear() async {
     await _mutex.protectWrite(() async {
@@ -101,15 +103,17 @@ class JsonCacheMem implements JsonCache {
     });
   }
 
-  /// Updates data located at [key] in both the level2 cache and in-memory
-  /// cache.
+  /// Updates the data located at [key] in both the _level 2_ cache and
+  /// in-memory cache.
+  ///
+  /// Throws [JsonCacheException] to indicate operation failure.
   @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.
+    // there's a high chance of having the level 2 cache and this object with
+    // different contents.
     //
     // In Dart, synchronous code cannot be interrupted, so there is no need to
     // protect it using mutual exclusion.
@@ -120,8 +124,8 @@ class JsonCacheMem implements JsonCache {
     });
   }
 
-  /// Removes the value located at [key] from both the level2 cache and
-  /// in-memory cache.
+  /// Removes the cached value located at [key] from both the _level 2 cache_
+  /// and _in-memory cache_.
   @override
   Future<void> remove(String key) async {
     await _mutex.protectWrite(() async {
@@ -130,33 +134,30 @@ class JsonCacheMem implements JsonCache {
     });
   }
 
-  /// Retrieves the value 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>?> value(String key) {
     return _mutex.protectRead(() async {
-      final cachedL1 = _memory[key];
-      if (cachedL1 != null) {
-        return Map<String, dynamic>.of(cachedL1);
+      final inMemoryValue = _memory[key];
+      if (inMemoryValue != null) {
+        return Map<String, dynamic>.of(inMemoryValue);
       }
-      final cachedL2 = await _level2.value(key);
-      if (cachedL2 != null) {
-        _memory[key] = cachedL2;
-        return Map<String, dynamic>.of(cachedL2);
+      final localStorageValue = await _level2.value(key);
+      if (localStorageValue != null) {
+        _memory[key] = localStorageValue;
+        return Map<String, dynamic>.of(localStorageValue);
       }
       return null;
     });
   }
 
-  /// Checks whether the in-memory or the level2 chache contains cached data at
-  /// [key].
+  /// Checks whether the _in-memory_ or the _level 2 cache_ contains cached data
+  /// at [key].
   @override
   Future<bool> contains(String key) {
     return _mutex.protectRead(() async {
-      bool found = _memory.containsKey(key);
-      if (!found) {
-        found = await _level2.contains(key);
-      }
-      return found;
+      final bool foundInMemory = _memory.containsKey(key);
+      return foundInMemory ? foundInMemory : await _level2.contains(key);
     });
   }
 }

lib/src/json_cache_try.dart

@@ -0,0 +1,91 @@
+import 'package:json_cache/json_cache.dart';
+
+/// A [JsonCache] decorator that provides improved information about
+/// cache-related failures by throwing [JsonCacheException].
+class JsonCacheTry implements JsonCache {
+  /// Sets [wrapped] as the instance to which this object will forward all
+  /// method calls.
+  ///
+  /// **Precondition**: the type of [wrapped] must not be `JsonCacheTry`.
+  const JsonCacheTry(JsonCache wrapped)
+      : assert(wrapped is! JsonCacheTry),
+        _wrapped = wrapped;
+
+  /// The JsonCache instance to which this object will forward all method calls.
+  final JsonCache _wrapped;
+
+  /// Frees up storage space by clearing cached data.
+  ///
+  /// Throws [JsonCacheException] to indicate operation failure.
+  @override
+  Future<void> clear() async {
+    try {
+      await _wrapped.clear();
+    } on Exception catch (ex) {
+      throw JsonCacheException(
+        extra: 'Error clearing cached data.',
+        exception: ex,
+      );
+    }
+  }
+
+  /// Updates the data located at [key].
+  ///
+  /// Throws [JsonCacheException] to indicate operation failure.
+  @override
+  Future<void> refresh(String key, Map<String, dynamic> value) async {
+    try {
+      await _wrapped.refresh(key, value);
+    } on Exception catch (ex) {
+      throw JsonCacheException(
+        extra: "Error refreshing cached data at index '$key'.",
+        exception: ex,
+      );
+    }
+  }
+
+  /// Removes the cached data located at [key].
+  ///
+  /// Throws [JsonCacheException] to indicate operation failure.
+  @override
+  Future<void> remove(String key) async {
+    try {
+      await _wrapped.remove(key);
+    } on Exception catch (ex) {
+      throw JsonCacheException(
+        extra: "Error removing cached data at index '$key'.",
+        exception: ex,
+      );
+    }
+  }
+
+  /// Retrieves the value located at [key] or `null` if there is no data.
+  ///
+  /// Throws [JsonCacheException] to indicate operation failure.
+  @override
+  Future<Map<String, dynamic>?> value(String key) async {
+    try {
+      return await _wrapped.value(key);
+    } on Exception catch (ex) {
+      throw JsonCacheException(
+        extra: "Error retrieving cached data at index '$key'.",
+        exception: ex,
+      );
+    }
+  }
+
+  /// Checks for cached data at [key].
+  ///
+  /// Throws [JsonCacheException] to indicate operation failure.
+  @override
+  Future<bool> contains(String key) async {
+    try {
+      return await _wrapped.contains(key);
+    } on Exception catch (ex) {
+      throw JsonCacheException(
+        extra: "Error checking for cached data at index '$key'.",
+        exception: ex,
+      );
+    }
+  }
+}