🎨 improve key validation logic and enhance stream functionality in storage containers

Author: BirjuVachhani

packages/hyper_storage/lib/src/api/serializable_container.dart

@@ -732,7 +732,7 @@ abstract class SerializableStorageContainer<E> extends StorageContainer implemen
     addKeyListener(key, retrieveAndAdd);
 
     yield* controller.stream;
-    await controller.close();
+    await controller.close(); // coverage:ignore-line
   }
 
   /// Provides a [Stream] of values for all items in the container.
@@ -763,6 +763,6 @@ abstract class SerializableStorageContainer<E> extends StorageContainer implemen
     addListener(retrieveAndAdd);
 
     yield* controller.stream;
-    await controller.close();
+    await controller.close(); // coverage:ignore-line
   }
 }

packages/hyper_storage/lib/src/hyper_storage.dart

@@ -423,6 +423,6 @@ class HyperStorage extends _HyperStorageImpl {
     addKeyListener(key, retrieveAndAdd);
 
     yield* controller.stream;
-    await controller.close();
+    await controller.close(); // coverage:ignore-line
   }
 }

packages/hyper_storage/lib/src/hyper_storage_container.dart

@@ -283,6 +283,6 @@ final class HyperStorageContainer extends StorageContainer with ItemHolderMixin,
     addKeyListener(key, retrieveAndAdd);
 
     yield* controller.stream;
-    await controller.close();
+    await controller.close(); // coverage:ignore-line
   }
 }

packages/hyper_storage/lib/src/item_holder.dart

@@ -248,9 +248,26 @@ mixin ItemHolderMixin on BaseStorage {
   @visibleForTesting
   String encodeKey(String key);
 
-  /// Validates a key before use. This method should be implemented by the class
-  /// using this mixin if key validation is required (e.g., for containers).
-  /// The default implementation does nothing.
+  /// Validates that a single key is acceptable for storage operations.
+  ///
+  /// This method checks that the key meets basic requirements for storage:
+  /// - Must not be empty
+  /// - Must not consist only of whitespace characters
+  ///
+  /// Parameters:
+  ///   * [key] - The key to validate.
+  ///
+  /// Throws:
+  ///   * [ArgumentError] if the key is empty.
+  ///   * [ArgumentError] if the key contains only whitespace.
+  ///
+  /// Example:
+  /// ```dart
+  /// validateKey('validKey');      // OK
+  /// validateKey('');              // Throws ArgumentError: Key cannot be empty
+  /// validateKey('   ');           // Throws ArgumentError: Key cannot be only whitespace
+  /// validateKey(' key ');         // OK - has non-whitespace content
+  /// ```
   @internal
   @protected
   @visibleForTesting

packages/hyper_storage/lib/src/storage_base.dart

@@ -21,31 +21,6 @@ abstract class _HyperStorageImpl extends BaseStorage
   ///     backend should already be initialized before creating this instance.
   _HyperStorageImpl({required super.backend});
 
-  /// Validates that a single key is acceptable for storage operations.
-  ///
-  /// This method checks that the key meets basic requirements for storage:
-  /// - Must not be empty
-  /// - Must not consist only of whitespace characters
-  ///
-  /// Parameters:
-  ///   * [key] - The key to validate.
-  ///
-  /// Throws:
-  ///   * [ArgumentError] if the key is empty.
-  ///   * [ArgumentError] if the key contains only whitespace.
-  ///
-  /// Example:
-  /// ```dart
-  /// _validateKey('validKey');      // OK
-  /// _validateKey('');              // Throws ArgumentError: Key cannot be empty
-  /// _validateKey('   ');           // Throws ArgumentError: Key cannot be only whitespace
-  /// _validateKey(' key ');         // OK - has non-whitespace content
-  /// ```
-  void _validateKey(String key) {
-    if (key.isEmpty) throw ArgumentError('Key cannot be empty');
-    if (key.trim().isEmpty) throw ArgumentError('Key cannot be only whitespace');
-  }
-
   /// Validates that all keys in a collection are acceptable for storage operations.
   ///
   /// This method validates multiple keys using [_validateKey]. If the iterable
@@ -69,7 +44,7 @@ abstract class _HyperStorageImpl extends BaseStorage
   void _validateKeys(Iterable<String>? keys) {
     if (keys == null || keys.isEmpty) return;
     for (final key in keys) {
-      _validateKey(key);
+      validateKey(key);
     }
   }
 
@@ -81,11 +56,14 @@ abstract class _HyperStorageImpl extends BaseStorage
   @override
   @internal
   @protected
-  void validateKey(String key) => _validateKey(key);
+  void validateKey(String key) {
+    if (key.isEmpty) throw ArgumentError('Key cannot be empty');
+    if (key.trim().isEmpty) throw ArgumentError('Key cannot be only whitespace');
+  }
 
   @override
   Future<bool> containsKey(String key) {
-    _validateKey(key);
+    validateKey(key);
     return backend.containsKey(key);
   }
 
@@ -98,43 +76,43 @@ abstract class _HyperStorageImpl extends BaseStorage
 
   @override
   Future<bool?> getBool(String key) {
-    _validateKey(key);
+    validateKey(key);
     return backend.getBool(key);
   }
 
   @override
   Future<DateTime?> getDateTime(String key, {bool isUtc = false}) {
-    _validateKey(key);
+    validateKey(key);
     return backend.getDateTime(key, isUtc: isUtc);
   }
 
   @override
   Future<double?> getDouble(String key) {
-    _validateKey(key);
+    validateKey(key);
     return backend.getDouble(key);
   }
 
   @override
   Future<Duration?> getDuration(String key) {
-    _validateKey(key);
+    validateKey(key);
     return backend.getDuration(key);
   }
 
   @override
   Future<int?> getInt(String key) {
-    _validateKey(key);
+    validateKey(key);
     return backend.getInt(key);
   }
 
   @override
   Future<Map<String, dynamic>?> getJson(String key) {
-    _validateKey(key);
+    validateKey(key);
     return backend.getJson(key);
   }
 
   @override
   Future<List<Map<String, dynamic>>?> getJsonList(String key) {
-    _validateKey(key);
+    validateKey(key);
     return backend.getJsonList(key);
   }
 
@@ -143,13 +121,13 @@ abstract class _HyperStorageImpl extends BaseStorage
 
   @override
   Future<String?> getString(String key) {
-    _validateKey(key);
+    validateKey(key);
     return backend.getString(key);
   }
 
   @override
   Future<List<String>?> getStringList(String key) {
-    _validateKey(key);
+    validateKey(key);
     return backend.getStringList(key);
   }
 
@@ -161,7 +139,7 @@ abstract class _HyperStorageImpl extends BaseStorage
 
   @override
   Future<void> remove(String key) async {
-    _validateKey(key);
+    validateKey(key);
     await backend.remove(key);
     notifyListeners(key);
   }
@@ -188,63 +166,63 @@ abstract class _HyperStorageImpl extends BaseStorage
 
   @override
   Future<void> setBool(String key, bool value) async {
-    _validateKey(key);
+    validateKey(key);
     await backend.setBool(key, value);
     notifyListeners(key);
   }
 
   @override
   Future<void> setDateTime(String key, DateTime value) async {
-    _validateKey(key);
+    validateKey(key);
     await backend.setDateTime(key, value);
     notifyListeners(key);
   }
 
   @override
   Future<void> setDouble(String key, double value) async {
-    _validateKey(key);
+    validateKey(key);
     await backend.setDouble(key, value);
     notifyListeners(key);
   }
 
   @override
   Future<void> setDuration(String key, Duration value) async {
-    _validateKey(key);
+    validateKey(key);
     await backend.setDuration(key, value);
     notifyListeners(key);
   }
 
   @override
   Future<void> setInt(String key, int value) async {
-    _validateKey(key);
+    validateKey(key);
     await backend.setInt(key, value);
     notifyListeners(key);
   }
 
   @override
   Future<void> setJson(String key, Map<String, dynamic> value) async {
-    _validateKey(key);
+    validateKey(key);
     await backend.setJson(key, value);
     notifyListeners(key);
   }
 
   @override
   Future<void> setJsonList(String key, List<Map<String, dynamic>> value) async {
-    _validateKey(key);
+    validateKey(key);
     await backend.setJsonList(key, value);
     notifyListeners(key);
   }
 
   @override
   Future<void> setString(String key, String value) async {
-    _validateKey(key);
+    validateKey(key);
     await backend.setString(key, value);
     notifyListeners(key);
   }
 
   @override
   Future<void> setStringList(String key, List<String> value) async {
-    _validateKey(key);
+    validateKey(key);
     await backend.setStringList(key, value);
     notifyListeners(key);
   }