♻️ add stream methods for real-time value updates in storage containers and improve documentation

Author: BirjuVachhani

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

@@ -1,6 +1,8 @@
 // Copyright © 2025 Hyperdesigned. All rights reserved.
 // Use of this source code is governed by a BSD license that can be
 // found in the LICENSE file.
+/// @docImport 'storage_container.dart';
+library;
 
 import 'dart:convert';
 
@@ -17,6 +19,7 @@ import 'api.dart';
 /// It includes default implementations for common operations like handling JSON,
 /// lists, and date/time objects, reducing the boilerplate needed when implementing
 /// a new backend.
+/// {@category Backends}
 abstract class StorageBackend with GenericStorageOperationsMixin implements StorageOperationsApi {
   /// Initializes the storage backend.
   ///

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

@@ -232,6 +232,7 @@ mixin ListenableStorage {
 ///
 /// This mixin implements the observer pattern, allowing components to be
 /// notified when data changes.
+/// {@category Reactivity}
 @protected
 mixin BaseListenable {
   /// A storage for keeping registry of listeners;

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

@@ -2,6 +2,7 @@
 // Use of this source code is governed by a BSD license that can be
 // found in the LICENSE file.
 
+import 'dart:async';
 import 'dart:math';
 
 import 'package:meta/meta.dart';
@@ -157,9 +158,6 @@ abstract class SerializableStorageContainer<E> extends StorageContainer implemen
   /// format is up to the implementation (JSON, XML, binary encoding, etc.),
   /// but it must be reversible by the [deserialize] method.
   ///
-  /// The [@protected] annotation indicates this method is for internal use
-  /// by the container and shouldn't be called directly by external code.
-  ///
   /// Parameters:
   ///   * [value] - The object to serialize.
   ///
@@ -179,9 +177,6 @@ abstract class SerializableStorageContainer<E> extends StorageContainer implemen
   /// strings from storage are converted back to objects. The implementation
   /// must be able to reverse the serialization performed by [serialize].
   ///
-  /// The [@protected] annotation indicates this method is for internal use
-  /// by the container and shouldn't be called directly by external code.
-  ///
   /// Parameters:
   ///   * [value] - The string to deserialize, as returned by [serialize].
   ///
@@ -201,9 +196,6 @@ abstract class SerializableStorageContainer<E> extends StorageContainer implemen
   /// number generator. The generated IDs are guaranteed to be valid storage
   /// keys (non-empty and not containing delimiters).
   ///
-  /// The [@protected] annotation indicates this method is for internal use
-  /// by the container and shouldn't be called directly by external code.
-  ///
   /// Returns:
   ///   A newly generated unique ID string.
   ///
@@ -711,4 +703,66 @@ abstract class SerializableStorageContainer<E> extends StorageContainer implemen
     removeAllListeners();
     await backend.close();
   }
+
+  /// Provides a [Stream] of values for the given [key].
+  /// The stream will emit the current value of the key and will update
+  /// whenever the value changes.
+  ///
+  /// It is important to close the stream when it is no longer needed
+  /// to avoid memory leaks.
+  ///
+  /// This can be done by cancelling the subscription to the stream.
+  Stream<E?> stream(String key) async* {
+    final E? itemValue = await get(key);
+    yield itemValue;
+
+    late final void Function() retrieveAndAdd;
+    final controller = StreamController<E?>(
+      onCancel: () => removeKeyListener(key, retrieveAndAdd),
+    );
+
+    retrieveAndAdd = () async {
+      if (controller.isClosed) return;
+      final E? value = await get(key);
+      if (!controller.isClosed) {
+        controller.add(value);
+      }
+    };
+
+    addKeyListener(key, retrieveAndAdd);
+
+    yield* controller.stream;
+    await controller.close();
+  }
+
+  /// Provides a [Stream] of values for all items in the container.
+  /// The stream will emit the current values and will update
+  /// whenever any value changes.
+  ///
+  /// It is important to close the stream when it is no longer needed
+  /// to avoid memory leaks.
+  ///
+  /// This can be done by cancelling the subscription to the stream.
+  Stream<List<E>> streamAll() async* {
+    final List<E> values = await getValues();
+    yield values;
+
+    late final void Function() retrieveAndAdd;
+    final controller = StreamController<List<E>>(
+      onCancel: () => removeListener(retrieveAndAdd),
+    );
+
+    retrieveAndAdd = () async {
+      if (controller.isClosed) return;
+      final List<E> values = await getValues();
+      if (!controller.isClosed) {
+        controller.add(values);
+      }
+    };
+
+    addListener(retrieveAndAdd);
+
+    yield* controller.stream;
+    await controller.close();
+  }
 }

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

@@ -2,6 +2,9 @@
 // Use of this source code is governed by a BSD license that can be
 // found in the LICENSE file.
 
+/// @docImport 'serializable_container.dart';
+library;
+
 import 'package:meta/meta.dart';
 
 import 'api.dart';

packages/hyper_storage/lib/src/hyper_storage.dart

@@ -2,12 +2,12 @@
 // Use of this source code is governed by a BSD license that can be
 // found in the LICENSE file.
 
+import 'dart:async';
 import 'dart:math';
 
 import 'package:meta/meta.dart';
 
 import '../hyper_storage.dart';
-import 'api/api.dart';
 import 'api/backend.dart';
 import 'api/storage_container.dart';
 
@@ -43,6 +43,7 @@ part 'storage_base.dart';
 /// - [JsonStorageContainer] for JSON serialization
 /// - [SerializableStorageContainer] for custom object storage
 /// - [StorageBackend] for implementing custom backends
+/// {@category Getting Started}
 class HyperStorage extends _HyperStorageImpl {
   /// Cache of basic storage containers indexed by name.
   ///
@@ -218,7 +219,7 @@ class HyperStorage extends _HyperStorageImpl {
   ///   * [fromJson] - A function that converts a JSON map back to an object of
   ///     type [E]. This is called when retrieving objects.
   ///   * [idGetter] - Optional. A function that extracts the ID from an object.
-  ///     If provided, this ID is used when adding objects with [add]. If not
+  ///     If provided, this ID is used when adding objects with add methods. If not
   ///     provided, IDs are automatically generated.
   ///   * [random] - Optional. A custom random number generator for ID generation.
   ///     Useful for testing or when specific randomness characteristics are needed.
@@ -380,4 +381,47 @@ class HyperStorage extends _HyperStorageImpl {
     await backend.close();
     await super.close();
   }
+
+  /// Provides a [Stream] of values for the given [key].
+  /// The stream will emit the current value of the key and will update
+  /// whenever the value changes.
+  ///
+  /// It is important to close the stream when it is no longer needed
+  /// to avoid memory leaks.
+  ///
+  /// This can be done by cancelling the subscription to the stream.
+  ///
+  /// Note that only supported types are allowed for [E].
+  /// Supported types are:
+  ///   - String
+  ///   - int
+  ///   - double
+  ///   - bool
+  ///   - List of String
+  ///   - JSON Map
+  ///   - List of JSON Map
+  ///   - DateTime
+  ///   - Duration
+  Stream<E?> stream<E extends Object>(String key) async* {
+    final E? itemValue = await get<E>(key);
+    yield itemValue;
+
+    late final void Function() retrieveAndAdd;
+    final controller = StreamController<E?>(
+      onCancel: () => removeKeyListener(key, retrieveAndAdd),
+    );
+
+    retrieveAndAdd = () async {
+      if (controller.isClosed) return;
+      final E? value = await get<E>(key);
+      if (!controller.isClosed) {
+        controller.add(value);
+      }
+    };
+
+    addKeyListener(key, retrieveAndAdd);
+
+    yield* controller.stream;
+    await controller.close();
+  }
 }

packages/hyper_storage/lib/src/hyper_storage_container.dart

@@ -2,6 +2,7 @@
 // Use of this source code is governed by a BSD license that can be
 // found in the LICENSE file.
 
+import 'dart:async';
 import 'dart:convert';
 
 import 'package:meta/meta.dart' show protected;
@@ -27,14 +28,10 @@ import 'api/storage_container.dart';
 ///
 /// See also:
 /// - [StorageContainer] for the base class and abstract interface
+/// {@category Containers}
 final class HyperStorageContainer extends StorageContainer with ItemHolderMixin, GenericStorageOperationsMixin {
   /// Creates a new [HyperStorageContainer] instance.
   ///
-  /// This constructor is marked [@protected] because containers should
-  /// typically be created through [HyperStorage.container] rather than
-  /// directly instantiated. Direct instantiation bypasses the container
-  /// caching system.
-  ///
   /// Parameters:
   ///   * [backend] - The storage backend that handles actual persistence.
   ///   * [name] - The name of the container, used as a prefix for all keys.
@@ -245,4 +242,47 @@ final class HyperStorageContainer extends StorageContainer with ItemHolderMixin,
     notifyListeners();
     removeAllListeners();
   }
+
+  /// Provides a [Stream] of values for the given [key].
+  /// The stream will emit the current value of the key and will update
+  /// whenever the value changes.
+  ///
+  /// It is important to close the stream when it is no longer needed
+  /// to avoid memory leaks.
+  ///
+  /// This can be done by cancelling the subscription to the stream.
+  ///
+  /// Note that only supported types are allowed for [E].
+  /// Supported types are:
+  ///   - String
+  ///   - int
+  ///   - double
+  ///   - bool
+  ///   - List of String
+  ///   - JSON Map
+  ///   - List of JSON Map
+  ///   - DateTime
+  ///   - Duration
+  Stream<E?> stream<E extends Object>(String key) async* {
+    final E? itemValue = await get<E>(key);
+    yield itemValue;
+
+    late final void Function() retrieveAndAdd;
+    final controller = StreamController<E?>(
+      onCancel: () => removeKeyListener(key, retrieveAndAdd),
+    );
+
+    retrieveAndAdd = () async {
+      if (controller.isClosed) return;
+      final E? value = await get<E>(key);
+      if (!controller.isClosed) {
+        controller.add(value);
+      }
+    };
+
+    addKeyListener(key, retrieveAndAdd);
+
+    yield* controller.stream;
+    await controller.close();
+  }
 }

packages/hyper_storage/lib/src/in_memory_backend.dart

@@ -3,7 +3,6 @@
 // found in the LICENSE file.
 
 import 'api/backend.dart';
-import 'hyper_storage_container.dart';
 
 /// A volatile storage backend that stores all data in memory.
 ///
@@ -40,13 +39,6 @@ class InMemoryBackend extends StorageBackend {
   @override
   Future<InMemoryBackend> init() async => this;
 
-  @override
-  Future<HyperStorageContainer> container(String name) async {
-    final backend = InMemoryBackend();
-    await backend.init();
-    return HyperStorageContainer(backend: backend, name: name);
-  }
-
   @override
   Future<void> setString(String key, String value) async => _data[key] = value;