feat: 'keys' method to list all cache keys (#164)

Closes #152

Author: rafamizes

lib/src/json_cache.dart

@@ -1,3 +1,5 @@
+import 'dart:collection';
+
 /// Represents cached data in json format.
 ///
 ///> Cache is a hardware or software component that stores data so that future
@@ -25,4 +27,9 @@ abstract class JsonCache {
  ///
  /// Returns `true` if there is cached data at [key]; `false` otherwise.
  Future<bool> contains(String key);
+
+ /// Lists all keys.
+ ///
+ /// Returns an **unmodifiable** list of cache keys without duplicates.
+ Future<UnmodifiableListView<String>> keys();
 }

lib/src/json_cache_exception.dart

@@ -11,7 +11,7 @@ class JsonCacheException<T extends Object> implements Exception {
 
  /// The original exception that indicated the failure of the caching
  /// operation.
- final Exception? exception;
+ final Object? exception;
 
  /// Returns [extra] along with the original exception message.
  @override

lib/src/json_cache_fake.dart

@@ -1,3 +1,5 @@
+import 'dart:collection';
+
 import 'package:json_cache/json_cache.dart';
 
 /// In-memory cache without synchronization.
@@ -50,4 +52,9 @@ class JsonCacheFake implements JsonCache {
  Future<bool> contains(String key) async {
  return _memory.containsKey(key);
  }
+
+ @override
+ Future<UnmodifiableListView<String>> keys() async {
+ return UnmodifiableListView(_memory.keys);
+ }
 }

lib/src/json_cache_flutter_secure_storage.dart

@@ -1,3 +1,4 @@
+import 'dart:collection';
 import 'dart:convert';
 
 import 'package:flutter_secure_storage/flutter_secure_storage.dart';
@@ -39,6 +40,11 @@ class JsonCacheFlutterSecureStorage implements JsonCache {
 
  @override
  Future<bool> contains(String key) async {
- return _storage.containsKey(key: key);
+ return await _storage.containsKey(key: key);
+ }
+
+ @override
+ Future<UnmodifiableListView<String>> keys() async {
+ return UnmodifiableListView((await _storage.readAll()).keys);
  }
 }

lib/src/json_cache_hive.dart

@@ -1,3 +1,4 @@
+import 'dart:collection';
 import 'dart:convert';
 
 import 'package:hive/hive.dart';
@@ -37,4 +38,9 @@ class JsonCacheHive implements JsonCache {
  Future<bool> contains(String key) async {
  return _box.containsKey(key);
  }
+
+ @override
+ Future<UnmodifiableListView<String>> keys() async {
+ return UnmodifiableListView(_box.keys.map((k) => k as String));
+ }
 }

lib/src/json_cache_hollow.dart

@@ -1,3 +1,5 @@
+import 'dart:collection';
+
 import 'package:json_cache/json_cache.dart';
 
 /// Hollow (empty) [JsonCache] — It is intended to serve as a placeholder for
@@ -38,4 +40,9 @@ class JsonCacheHollow implements JsonCache {
  /// Always returns `false`.
  @override
  Future<bool> contains(String key) async => false;
+
+ /// An empty list of keys.
+ @override
+ Future<UnmodifiableListView<String>> keys() async =>
+ UnmodifiableListView(const []);
 }

lib/src/json_cache_local_storage.dart

@@ -1,3 +1,4 @@
+import 'dart:collection';
 import 'dart:convert';
 
 import 'package:json_cache/json_cache.dart';
@@ -44,4 +45,15 @@ final class JsonCacheLocalStorage implements JsonCache {
 
  @override
  Future<bool> contains(String key) async => _storage.getItem(key) != null;
+
+ @override
+ Future<UnmodifiableListView<String>> keys() async {
+ return UnmodifiableListView(
+ List.generate(
+ _storage.length,
+ (int i) => _storage.key(i)!,
+ growable: false,
+ ),
+ );
+ }
 }

lib/src/json_cache_mem.dart

@@ -1,4 +1,5 @@
 import 'dart:async';
+import 'dart:collection';
 
 import 'package:json_cache/json_cache.dart';
 import 'package:mutex/mutex.dart';
@@ -93,8 +94,6 @@ 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 {
@@ -105,8 +104,6 @@ class JsonCacheMem implements JsonCache {
 
  /// 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
@@ -160,4 +157,11 @@ class JsonCacheMem implements JsonCache {
  return foundInMemory ? foundInMemory : await _level2.contains(key);
  });
  }
+
+ @override
+ Future<UnmodifiableListView<String>> keys() {
+ return _mutex.protectRead(() async {
+ return UnmodifiableListView(_memory.keys);
+ });
+ }
 }

lib/src/json_cache_safe_local_storage.dart

@@ -1,5 +1,7 @@
 // ignore_for_file: avoid_dynamic_calls
 
+import 'dart:collection';
+
 import 'package:json_cache/json_cache.dart';
 import 'package:safe_local_storage/safe_local_storage.dart';
 
@@ -43,6 +45,14 @@ class JsonCacheSafeLocalStorage implements JsonCache {
  return (await _cachedData)[key] as Map<String, dynamic>?;
  }
 
+ @override
+ Future<UnmodifiableListView<String>> keys() async {
+ final data = await _cachedData;
+ return UnmodifiableListView(
+ data.keys.map((k) => k as String),
+ );
+ }
+
  /// Gets the cached data stored in the local storage file.
  Future<Map<dynamic, dynamic>> get _cachedData async {
  return await _localStorage.read() as Map<dynamic, dynamic>;

lib/src/json_cache_shared_preferences.dart

@@ -1,3 +1,4 @@
+import 'dart:collection';
 import 'dart:convert';
 
 import 'package:json_cache/json_cache.dart';
@@ -47,4 +48,9 @@ class JsonCacheSharedPreferences implements JsonCache {
  Future<bool> contains(String key) async {
  return _sharedPreferences.containsKey(key);
  }
+
+ @override
+ Future<UnmodifiableListView<String>> keys() async {
+ return UnmodifiableListView(_sharedPreferences.getKeys());
+ }
 }