✨ enhance get and stream methods to support enum types with validation

Author: BirjuVachhani

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

@@ -184,18 +184,23 @@ mixin GenericStorageOperationsMixin implements StorageOperationsApi {
 
   @override
   Future<E?> get<E extends Object>(String key, {List<Enum>? enumValues}) async {
-    if (E == String) return await getString(key) as E?;
-    if (E == int) return await getInt(key) as E?;
-    if (E == double) return await getDouble(key) as E?;
-    if (E == bool) return await getBool(key) as E?;
-    if (E == DateTime) return await getDateTime(key) as E?;
-    if (E == Duration) return await getDuration(key) as E?;
-    if (E == List<String>) return await getStringList(key) as E?;
-    if (E == Map<String, dynamic>) return await getJson(key) as E?;
-    if (E == List<Map<String, dynamic>>) return await getJsonList(key) as E?;
-    if (enumValues != null) return await getEnum(key, enumValues) as E?;
-
-    throw UnsupportedError('Type $E is not supported');
+    return switch (E) {
+      const (String) => await getString(key) as E?,
+      const (int) => await getInt(key) as E?,
+      const (double) => await getDouble(key) as E?,
+      const (num) => await getDouble(key) as E?,
+      const (bool) => await getBool(key) as E?,
+      const (DateTime) => await getDateTime(key) as E?,
+      const (Duration) => await getDuration(key) as E?,
+      const (List<String>) => await getStringList(key) as E?,
+      const (Map<String, dynamic>) => await getJson(key) as E?,
+      const (List<Map<String, dynamic>>) => await getJsonList(key) as E?,
+      _ when enumValues != null => () {
+        checkEnumType<E>(enumValues);
+        return getEnum(key, enumValues.cast<Enum>()) as E?;
+      }(),
+      _ => throw UnsupportedError('Type $E is not supported. If this is an enum, provide the enumValues parameter.'),
+    };
   }
 
   @override

packages/hyper_storage/lib/src/hyper_storage.dart

@@ -10,6 +10,7 @@ import 'package:meta/meta.dart';
 import '../hyper_storage.dart';
 import 'api/backend.dart';
 import 'api/storage_container.dart';
+import 'utils.dart';
 
 part 'storage_base.dart';
 
@@ -403,8 +404,10 @@ class HyperStorage extends _HyperStorageImpl {
   ///   - List of JSON Map
   ///   - DateTime
   ///   - Duration
-  Stream<E?> stream<E extends Object>(String key) async* {
-    final E? itemValue = await get<E>(key);
+  ///   - Enum (requires providing [enumValues])
+  Stream<E?> stream<E extends Object>(String key, {List<Enum>? enumValues}) async* {
+    if(enumValues != null) checkEnumType<E>(enumValues);
+    final E? itemValue = await get<E>(key, enumValues: enumValues);
     yield itemValue;
 
     late final void Function() retrieveAndAdd;
@@ -414,7 +417,7 @@ class HyperStorage extends _HyperStorageImpl {
 
     retrieveAndAdd = () async {
       if (controller.isClosed) return;
-      final E? value = await get<E>(key);
+      final E? value = await get<E>(key, enumValues: enumValues);
       if (!controller.isClosed) {
         controller.add(value);
       }
@@ -423,6 +426,8 @@ class HyperStorage extends _HyperStorageImpl {
     addKeyListener(key, retrieveAndAdd);
 
     yield* controller.stream;
+
+    // Defensive close call. Almost never reached because the stream is closed on cancel.
     await controller.close(); // coverage:ignore-line
   }
 }

packages/hyper_storage/lib/src/hyper_storage_container.dart

@@ -10,6 +10,7 @@ import 'package:meta/meta.dart' show protected;
 import '../hyper_storage.dart';
 import 'api/backend.dart';
 import 'api/storage_container.dart';
+import 'utils.dart';
 
 /// A concrete implementation of [StorageContainer] for storing key-value pairs.
 ///
@@ -281,8 +282,10 @@ final class HyperStorageContainer extends StorageContainer with ItemHolderMixin,
   ///   - List of JSON Map
   ///   - DateTime
   ///   - Duration
-  Stream<E?> stream<E extends Object>(String key) async* {
-    final E? itemValue = await get<E>(key);
+  ///   - Enum (requires providing [enumValues])
+  Stream<E?> stream<E extends Object>(String key, {List<Enum>? enumValues}) async* {
+    if(enumValues != null) checkEnumType<E>(enumValues);
+    final E? itemValue = await get<E>(key, enumValues: enumValues);
     yield itemValue;
 
     late final void Function() retrieveAndAdd;
@@ -292,15 +295,14 @@ final class HyperStorageContainer extends StorageContainer with ItemHolderMixin,
 
     retrieveAndAdd = () async {
       if (controller.isClosed) return;
-      final E? value = await get<E>(key);
-      if (!controller.isClosed) {
-        controller.add(value);
-      }
+      final E? value = await get<E>(key, enumValues: enumValues);
+      if (!controller.isClosed) controller.add(value);
     };
 
     addKeyListener(key, retrieveAndAdd);
 
     yield* controller.stream;
+    // Defensive close call. Almost never reached because the stream is closed on cancel.
     await controller.close(); // coverage:ignore-line
   }
 }

packages/hyper_storage/lib/src/item_holder.dart

@@ -11,6 +11,7 @@ import 'dart:convert';
 import 'package:meta/meta.dart';
 
 import '../hyper_storage.dart';
+import 'utils.dart';
 
 /// Function type definition for getting an item from the storage backend.
 typedef ItemGetter<E extends Object> = Future<E?> Function(StorageBackend backend, String key);
@@ -31,6 +32,8 @@ class ItemHolder<E extends Object> with Stream<E?> implements BaseListenable, It
 
   bool _isClosed = false;
 
+  final List<Enum>? _enumValues;
+
   /// The key associated with this item holder.
   @internal
   bool get isClosed => _isClosed;
@@ -56,7 +59,13 @@ class ItemHolder<E extends Object> with Stream<E?> implements BaseListenable, It
   final StreamController<E?> _streamController = StreamController<E?>.broadcast();
 
   /// Creates a new [ItemHolder] instance.
-  ItemHolder(BaseStorage this._parent, this._key, {this.getter, this.setter});
+  ItemHolder(
+    BaseStorage this._parent,
+    this._key, {
+    this.getter,
+    this.setter,
+    List<Enum>? enumValues,
+  }) : _enumValues = enumValues;
 
   @override
   Future<bool> get exists => _parent?.backend.containsKey(_key) ?? Future.value(false);
@@ -65,7 +74,7 @@ class ItemHolder<E extends Object> with Stream<E?> implements BaseListenable, It
   Future<E?> get() async {
     if (_parent case BaseStorage(:final backend)) {
       if (getter case var getter?) return getter(backend, _key);
-      final E? value = await backend.get(_key);
+      final E? value = await backend.get<E>(_key, enumValues: _enumValues);
       return value;
     }
     return Future.value(null);
@@ -399,6 +408,7 @@ mixin ItemHolderMixin on BaseStorage {
   /// - List of String
   /// - JSON Map
   /// - List of JSON Maps
+  /// - Enum (requires providing [enumValues] unless custom getter/setter supplied)
   ///
   /// Parameters:
   ///   - [key]: The key under which to store the item. Must be non-empty and not only whitespace.
@@ -407,6 +417,8 @@ mixin ItemHolderMixin on BaseStorage {
   ///   to retrieve the item instead of the default backend method.
   ///   - [set]: Optional custom setter function. If provided, this function will be used
   ///   to store the item instead of the default backend method.
+  ///   - [enumValues]: Optional list of all enum values when using an enum type with the
+  ///   default getter/setter. Required if [E] is an enum and you are not supplying custom accessors.
   ///
   /// Returns:
   ///   A [ItemHolder] configured to manage the item at the specified key.
@@ -417,13 +429,25 @@ mixin ItemHolderMixin on BaseStorage {
   /// See also:
   ///   - [jsonItemHolder] for JSON-specific serialization.
   ///   - [serializableItemHolder] for generic/other serialization.
-  ItemHolder<E> itemHolder<E extends Object>(String key, {ItemGetter<E>? get, ItemSetter<E>? set}) {
+  ItemHolder<E> itemHolder<E extends Object>(
+    String key, {
+    ItemGetter<E>? get,
+    ItemSetter<E>? set,
+    List<Enum>? enumValues,
+  }) {
     validateKey(key);
     if ((get == null && set != null) || (get != null && set == null)) {
       throw ArgumentError('Both getter and setter must be provided together, or neither.');
     }
     // Only run generic type validation if custom getter/setter are not provided.
-    if (set == null || get == null) _validateGenericType<E>();
+    final hasCustomAccessors = get != null && set != null;
+    if (!hasCustomAccessors) {
+      if (enumValues == null) {
+        _validateGenericType<E>();
+      } else {
+        checkEnumType<E>(enumValues);
+      }
+    }
     var existing = _holders[key];
     if (existing != null && existing.isClosed) {
       _holders.remove(key);
@@ -439,7 +463,13 @@ mixin ItemHolderMixin on BaseStorage {
       }
     }
 
-    final holder = ItemHolder<E>(this, encodeKey(key), setter: set, getter: get);
+    final holder = ItemHolder<E>(
+      this,
+      encodeKey(key),
+      setter: set,
+      getter: get,
+      enumValues: enumValues,
+    );
     _holders[key] = holder;
     return holder;
   }

packages/hyper_storage/lib/src/utils.dart

@@ -18,3 +18,17 @@ Object? tryJsonDecode(String value) {
     return null;
   }
 }
+
+@internal
+void checkEnumType<E extends Object>(List<Enum> enumValues) {
+  if (enumValues is List<E>) {
+    if (enumValues.isEmpty) {
+      throw ArgumentError('The enumValues parameter cannot be empty.');
+    }
+    if (enumValues.first.runtimeType != E) {
+      throw ArgumentError('The enumValues parameter must be of type $E. Found: ${enumValues.first.runtimeType}.');
+    }
+  } else {
+    throw ArgumentError('The enumValues parameter must be of type List<$E>. Found: ${enumValues.runtimeType}.');
+  }
+}