refactor: 'JsonCache' as a Dart interface and implementations as 'final'

Closes #168

Breaking Changes

Author: rafamizes

CHANGELOG.md

@@ -9,17 +9,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Method "keys" for listing all cache keys —
+- Method `keys` for listing all cache keys —
   [152](https://github.com/dartoos-dev/json_cache/issues/152)
 
 ### Changed
 
-- Mehtod "keys" returns an immutable copy of the underlying cache keys —
-  [165](https://github.com/dartoos-dev/json_cache/issues/152)
+- Make `JsonCache` a Dart interface and mark implementations as `final` — **BREAKING CHANGE** —
+  [168](https://github.com/dartoos-dev/json_cache/issues/168).
 
 - Update linting rules —
   [162](https://github.com/dartoos-dev/json_cache/issues/154).
 
+### Fixed
+
+- Mehtod `keys` returns an immutable copy of the underlying cache keys —
+  [165](https://github.com/dartoos-dev/json_cache/issues/152)
+
 ## [3.0.2] - 2024-08-19
 
 ### Changed

lib/src/json_cache.dart

@@ -2,12 +2,12 @@ import 'dart:collection';
 
 /// 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
-///> might be the result of an earlier computation or a copy of data stored
-///> elsewhere.
+///> "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 {
+abstract interface class JsonCache {
   /// Frees up storage space — deletes all keys and values.
   Future<void> clear();
 

lib/src/json_cache_exception.dart

@@ -1,5 +1,5 @@
 /// An exception to indicate cache operation failures.
-class JsonCacheException<T extends Object> implements Exception {
+final class JsonCacheException<T extends Object> implements Exception {
   /// Sets [extra] as the aditional information and [exception] as the original
   /// exception.
   const JsonCacheException({required this.extra, this.exception});

lib/src/json_cache_fake.dart

@@ -7,7 +7,7 @@ import 'package:json_cache/json_cache.dart';
 /// It is intended for unit testing and prototyping.
 ///
 /// **Warning**: do not use it in production code. It is not thread-safe.
-class JsonCacheFake implements JsonCache {
+final class JsonCacheFake implements JsonCache {
   /// Shares a static memory with other instances.
   JsonCacheFake() : this.mem(_shrMem);
 

lib/src/json_cache_flutter_secure_storage.dart

@@ -8,7 +8,7 @@ import 'package:json_cache/json_cache.dart';
 ///
 /// See also:
 /// - [flutter_secure_storage](https://pub.dev/packages/flutter_secure_storage).
-class JsonCacheFlutterSecureStorage implements JsonCache {
+final class JsonCacheFlutterSecureStorage implements JsonCache {
   /// Sets the [FlutterSecureStorage] instance.
   const JsonCacheFlutterSecureStorage(this._storage);
 

lib/src/json_cache_hive.dart

@@ -7,7 +7,7 @@ import 'package:json_cache/json_cache.dart';
 /// Implementation on top of the Hive package.
 ///
 /// See: [hive](https://pub.dev/packages/hive)
-class JsonCacheHive implements JsonCache {
+final class JsonCacheHive implements JsonCache {
   /// Sets the Hive [Box] instance.
   const JsonCacheHive(this._box);
 

lib/src/json_cache_hollow.dart

@@ -16,7 +16,7 @@ import 'package:json_cache/json_cache.dart';
 /// > - Hollow blocks are used because they are lighter
 /// > - a hollow log
 /// > — [Cambridge Dictionary](https://dictionary.cambridge.org/dictionary/english/hollow)
-class JsonCacheHollow implements JsonCache {
+final class JsonCacheHollow implements JsonCache {
   /// This const constructor ensures that there will be only one
   /// [JsonCacheHollow] instance throughout the program.
   const JsonCacheHollow();

lib/src/json_cache_mem.dart

@@ -9,12 +9,16 @@ import 'package:mutex/mutex.dart';
 /// [JsonCacheMem.init] initialization error callback.
 typedef OnInitError = FutureOr<Null> Function(Object, StackTrace);
 
+/// {@template json_cache_mem}
+///
 /// Thread-safe in-memory [JsonCache] decorator.
 ///
 /// It is a kind of _level 1_ cache.
 ///
 /// It encapsulates a slower cache and keeps its own data in-memory.
-class JsonCacheMem implements JsonCache {
+///
+/// {@endtemplate}
+final class JsonCacheMem implements JsonCache {
   /// 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

lib/src/json_cache_safe_local_storage.dart

@@ -8,7 +8,7 @@ import 'package:safe_local_storage/safe_local_storage.dart';
 /// Implementation on top of the SafeLocalStorage package.
 ///
 /// See: [Safe local storage](https://pub.dev/packages/safe_local_storage)
-class JsonCacheSafeLocalStorage implements JsonCache {
+final class JsonCacheSafeLocalStorage implements JsonCache {
   /// Encapsulates a [SafeLocalStorage] instance.
   const JsonCacheSafeLocalStorage(this._localStorage);
 

lib/src/json_cache_shared_preferences.dart

@@ -5,7 +5,7 @@ import 'package:json_cache/json_cache.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
 /// Persistent preferences file cache.
-class JsonCacheSharedPreferences implements JsonCache {
+final class JsonCacheSharedPreferences implements JsonCache {
   /// Sets the [SharedPreferences] instance.
   const JsonCacheSharedPreferences(this._sharedPreferences);
 

lib/src/json_cache_try.dart

@@ -4,7 +4,7 @@ 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 {
+final class JsonCacheTry implements JsonCache {
   /// Sets [wrapped] as the instance to which this object will forward all
   /// method calls.
   ///