✨ add documentation for enum support, including storing, retrieving, and streaming enums

Author: BirjuVachhani

packages/hyper_storage/dartdoc_options.yaml

@@ -18,11 +18,15 @@ dartdoc:
     Reactivity:
       markdown: docs/reactivity.md
       displayName: Reactivity
+    Enums:
+      markdown: docs/enums.md
+      displayName: Enums
   categoryOrder:
     - "Introduction"
     - "Getting Started"
     - "Backends"
     - "Containers"
     - "Item Holders"
     - "Reactivity"
+    - "Enums"
   showUndocumentedCategories: true

packages/hyper_storage/docs/enums.md

@@ -0,0 +1,102 @@
+
+Hyper Storage supports enums out of the box. Enums are a treated as special kind of data type as it is such data type
+in Dart language.
+
+> For any `Enum` related operations where a value needs to be read from underlying storage, you need to provide a
+> list of all possible enum values. This is due to limitations of Dart language and Flutter, which does not support
+> reflection at runtime (e.g. `Role.values`).
+
+# Table of Contents
+
+- [Storing Enums](#storing-enums)
+- [Retrieving Enums](#retrieving-enums)
+- [Using ItemHolder with Enums](#using-itemholder-with-enums)
+- [Streaming Enums](#streaming-enums)
+
+## Storing Enums
+
+Storing enums is as simple as storing any other data type. You can store enums in a document like this:
+
+```dart
+await storage.setEnum('role', Role.guest);
+```
+Under the hood, Hyper Storage stores enums as their string representation. For example, the enum value `Role.guest`
+is stored as the string `"guest"`.
+
+Storing enums in a container is also supported:
+
+```dart
+final container = await storage.container('settings');
+await container.setEnum('brightness', Brightness.dark);
+```
+
+You can also use the generic `set` method to store enums:
+
+```dart
+await storage.set('role', Role.admin);
+```
+
+
+## Retrieving Enums
+
+Due to limitations of Dart, retrieving enums requires you to provide a list all possible enum values. 
+This is necessary because Dart does not support reflection, and thus cannot determine the enum type at runtime.
+
+You can retrieve enums like this:
+
+```dart
+final role = await storage.getEnum<Role>('role', Role.values);
+```
+
+If the stored value does not match any of the provided enum values, `null` is returned. The API for the container is
+also the same:
+
+```dart
+final container = await storage.container('settings');
+final brightness = await container.getEnum<Brightness>('brightness', Brightness.values);
+```
+
+You can also use the generic `get` method to retrieve enums:
+
+```dart
+final role = await storage.get<Role>('role', Role.values);
+```
+
+## Using ItemHolder with Enums
+
+You can also use `ItemHolder` to store and retrieve enums. Here's an example:
+
+```dart
+final roleHolder = storage.itemHolder<Role>('role', Role.values);
+
+// Set the enum value
+await roleHolder.set(Role.user);
+
+// Get the enum value
+final role = await roleHolder.get();
+```
+
+## Streaming Enums
+
+You can stream changes to enum values using the `stream` method. Here's an example:
+
+```dart
+final roleStream = storage.stream<Role>('role', Role.values);
+
+roleStream.listen((role) {
+  print('Role changed to: $role');
+});
+```
+
+With containers:
+
+```dart
+final container = await storage.container('settings');
+
+final brightnessStream = container.stream<Brightness>('brightness', Brightness.values);
+
+brightnessStream.listen((brightness) {
+  print('Brightness changed to: $brightness');
+});
+```
+

packages/hyper_storage/docs/item_holders.md

@@ -50,19 +50,8 @@ The type `E` must be one of the supported types:
 
 Optionally, you can pass getter and setter functions to provide custom read/write logic for underlying storage.
 
-Example: Storing an `Enum` object as an `String` value.
 
-```dart
-enum UserRole { admin, user, guest }
-
-final ItemHolder<MyEnum> lastLoginHolder = storage.holder<UserRole>(
-  'role',
-  getter: (storage, key) async => UserRole.values.byName(await storage.getString(key) ?? 'guest'),
-  setter: (storage, key, value) async => storage.setString(key, value.name),
-);
-```
-
-Calling `storage.holder` multiple times with the same key will return the same instance of `ItemHolder`. Hyper Storage
+Calling `storage.itemHolder` multiple times with the same key will return the same instance of `ItemHolder`. Hyper Storage
 internally caches the created item holders.
 
 > If an item holder with given key already exists with a different type, an exception will be thrown.

packages/hyper_storage/lib/src/item_holder.dart

@@ -26,6 +26,7 @@ typedef ItemSetter<E extends Object> = Future<void> Function(StorageBackend back
 /// to handle the specific type [E]. This is useful for types that do not
 /// require complex serialization, or when you want to manage the serialization
 /// {@category Item Holders}
+/// {@category Enums}
 class ItemHolder<E extends Object> with Stream<E?> implements BaseListenable, ItemHolderApi<E> {
   BaseStorage? _parent;
   final String _key;