feat: JsoCacheLocalStorage

Closes #29

Author: rafamizes

CHANGELOG.md

@@ -7,17 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- JsonCacheLocalStorage: implementation on top of the localstorage package —
+  [29](https://github.com/dartoos-dev/json_cache/issues/29).
+
+### Added
+
+- Improvements in README file and documentation in general.
+
 ## [0.2.0] - 2021-08-22
 
 ### Added
 
-- JsonCachePrefs, a implementation on top of the shared_preferences package —
+- JsonCachePrefs: 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**.
+- renaming of JsonCache's methods. Method `erase` renamed to `remove`; method
+  `recovery`, to `value`. **BREAKING CHANGES**.
 
 ## [0.1.0] - 2021-08-22
 

README.md

@@ -21,6 +21,10 @@ Rultor.com](https://www.rultor.com/b/dartoos-dev/json_cache)](https://www.rultor
 
 - [Overview](#overview)
 - [Getting Started](#getting-started)
+- [List of JsonCache implementations](#list-of-jsoncache-implementations)
+  - [JsonCacheMem — Thread-safe In-memory cache](#jsoncachemem)
+  - [JsonCachePrefs — SharedPreferences](#jsoncacheprefs)
+  - [JsonCacheLocalStorage — LocalStorage](#jsoncachelocalstorage)
 - [Demo application](#demo-application)
 - [References](#references)
 
@@ -90,17 +94,29 @@ 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.
 
+## List of JsonCache Implementations
+
+The library
+[JsonCache](https://pub.dev/documentation/json_cache/latest/json_cache/json_cache-library.html)
+contains all the classes that implement the
+[JsonCache](https://pub.dev/documentation/json_cache/latest/json_cache/JsonCache-class.html)
+interface with more in-depth details.
+
+The following sections are an overview of each implementation.
+
 ### JsonCacheMem
 
-It is a thread-safe, in-memory implementation of the `JsonCache` interface.
+[JsonCacheMem](https://pub.dev/documentation/json_cache/latest/json_cache/JsonCacheMem-class.html)
+is 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
+#### Typical Usage
 
 Due to the fact that `JsonCacheMem` is a decorator, you should always pass
-another `JsonCache` instance when you instantiates it. For example:
+another `JsonCache` instance to it whenever you instantiates a `JsonCacheMem`
+object. For example:
 
 ```dart
   …
@@ -109,6 +125,32 @@ another `JsonCache` instance when you instantiates it. For example:
   …
 ```
 
+### JsonCachePrefs
+
+[JsonCachePrefs](https://pub.dev/documentation/json_cache/latest/json_cache/JsonCachePrefs-class.html)
+is an implementation on top of the
+[shared_preferences](https://pub.dev/packages/shared_preferences) package.
+
+```dart
+  …
+  final prefs = await SharedPreferences.getInstance();
+  final JsonCache jsonCache = JsonCacheMem(JsonCachePrefs(prefs));
+  …
+```
+
+### JsonCacheLocalStorage
+
+[JsonCacheLocalStorage](https://pub.dev/documentation/json_cache/latest/json_cache/JsonCacheLocalStorage-class.html)
+is an implementation on top of the
+[shared_preferences](https://pub.dev/packages/shared_preferences) package.
+
+```dart
+  …
+  final LocalStorage storage = LocalStorage('my_data');
+  final JsonCache jsonCache = JsonCacheMem(JsonCacheLocalStorage(storage));
+  …
+```
+
 ## Demo application
 
 The demo application provides a fully working example, focused on demonstrating

lib/json_cache.dart

@@ -3,6 +3,7 @@ library json_cache;
 
 export 'src/json_cache.dart';
 export 'src/json_cache_fake.dart';
+export 'src/json_cache_local_storage.dart';
 export 'src/json_cache_mem.dart';
 export 'src/json_cache_prefs.dart';
 export 'src/json_cache_wrap.dart';

lib/src/json_cache_local_storage.dart

@@ -0,0 +1,39 @@
+import 'package:localstorage/localstorage.dart';
+
+import 'json_cache.dart';
+
+/// Implementation on top of the LocalStorage package.
+///
+/// See: [local storage](https://pub.dev/packages/localstorage)
+class JsonCacheLocalStorage implements JsonCache {
+  /// Encapsulates a [LocalStorage] instance.
+  JsonCacheLocalStorage(this._storage);
+
+  final LocalStorage _storage;
+
+  Future<bool> get _getReady => _storage.ready;
+
+  @override
+  Future<void> clear() async {
+    await _getReady;
+    await _storage.clear();
+  }
+
+  @override
+  Future<void> refresh(String key, Map<String, dynamic> value) async {
+    await _getReady;
+    await _storage.setItem(key, value);
+  }
+
+  @override
+  Future<void> remove(String key) async {
+    await _getReady;
+    await _storage.deleteItem(key);
+  }
+
+  @override
+  Future<Map<String, dynamic>?> value(String key) async {
+    await _getReady;
+    return await _storage.getItem(key) as Map<String, dynamic>?;
+  }
+}

lib/src/json_cache_mem.dart

@@ -2,7 +2,7 @@ import 'package:mutex/mutex.dart';
 
 import 'json_cache.dart';
 
-/// Thread-safe, in-memory [JsonCache] decorator.
+/// Thread-safe in-memory [JsonCache] decorator.
 ///
 /// It is a kind of level 1 cache.
 ///

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:
@@ -93,6 +93,13 @@ packages:
       url: "https://pub.dartlang.org"
     source: hosted
     version: "1.6.0"
+  localstorage:
+    dependency: "direct main"
+    description:
+      name: localstorage
+      url: "https://pub.dartlang.org"
+    source: hosted
+    version: "4.0.0+1"
   matcher:
     dependency: transitive
     description:
@@ -106,7 +113,7 @@ packages:
       name: meta
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.3.0"
+    version: "1.7.0"
   mutex:
     dependency: "direct main"
     description:
@@ -121,13 +128,27 @@ packages:
       url: "https://pub.dartlang.org"
     source: hosted
     version: "1.8.0"
+  path_provider:
+    dependency: transitive
+    description:
+      name: path_provider
+      url: "https://pub.dartlang.org"
+    source: hosted
+    version: "2.0.2"
   path_provider_linux:
     dependency: transitive
     description:
       name: path_provider_linux
       url: "https://pub.dartlang.org"
     source: hosted
     version: "2.0.2"
+  path_provider_macos:
+    dependency: transitive
+    description:
+      name: path_provider_macos
+      url: "https://pub.dartlang.org"
+    source: hosted
+    version: "2.0.2"
   path_provider_platform_interface:
     dependency: transitive
     description:
@@ -251,7 +272,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:

pubspec.yaml

@@ -11,6 +11,7 @@ environment:
 dependencies:
   flutter:
     sdk: flutter
+  localstorage: ^4.0.0+1
   mutex: ^3.0.0
   shared_preferences: ^2.0.6
 

test/json_cache_local_storage_test.dart

@@ -0,0 +1,49 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:json_cache/json_cache.dart';
+import 'package:localstorage/localstorage.dart';
+
+void main() {
+  final LocalStorage storage =
+      LocalStorage('json_cache_local_storage_unit_test');
+  group('JsonCacheLocalStorage', () {
+    test('clear, recover and refresh', () async {
+      const profKey = 'profile';
+      const profData = <String, Object>{'id': 1, 'name': 'John Due'};
+      final JsonCacheLocalStorage localStorageCache =
+          JsonCacheLocalStorage(storage);
+      await localStorageCache.refresh(profKey, profData);
+      var prof = await localStorageCache.value(profKey);
+      expect(prof, profData);
+      await localStorageCache.clear();
+      prof = await localStorageCache.value(profKey);
+      expect(prof, isNull);
+    });
+
+    test('remove', () async {
+      const profKey = 'profile';
+      const prefKey = 'preferences';
+      final profData = <String, Object>{'id': 1, 'name': 'John Due'};
+      final prefData = <String, Object>{
+        'theme': 'dark',
+        'notifications': {'enabled': true}
+      };
+      final JsonCacheLocalStorage localStorageCache =
+          JsonCacheLocalStorage(storage);
+      await localStorageCache.refresh(profKey, profData);
+      await localStorageCache.refresh(prefKey, prefData);
+
+      var prof = await localStorageCache.value(profKey);
+      expect(prof, profData);
+
+      await localStorageCache.remove(profKey);
+      prof = await localStorageCache.value(profKey);
+      expect(prof, isNull);
+
+      var pref = await localStorageCache.value(prefKey);
+      expect(pref, prefData);
+      await localStorageCache.remove(prefKey);
+      pref = await localStorageCache.value(prefKey);
+      expect(pref, isNull);
+    });
+  });
+}