📝 update docs and examples

Author: BirjuVachhani

packages/hyper_storage/README.md

@@ -281,3 +281,36 @@ final storage = await HyperStorage.initMocked(initialData: {
 ## Contributing
 
 Contributions are welcome! Please feel free to open an issue or submit a pull request.
+
+## License
+
+```
+BSD 3-Clause License
+
+Copyright (c) 2025, Hyperdesigned
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```

packages/hyper_storage/docs/reactivity.md

@@ -86,7 +86,7 @@ void onStorageChanged() {
 storage.removeListener(onStorageChanged);
 ```
 
-You can also listen to all changes in a named container:
+You can also listen to all changes in a container:
 
 ```dart
 
@@ -142,13 +142,22 @@ StreamBuilder<String?>(
 ```
 
 **Note**: Unlike traditional streams, ItemHolder does **not** emit errors during value retrieval. This prevents
-transient failures (like network issues) from being cached and replayed to future listeners. The stream simply
-retains its last valid value and retries on the next update.
+transient failures from being cached and replayed to future listeners. The stream simply retains its last valid 
+value and retries on the next update.
 
 ## Converting Item Holder to a ValueNotifier
 
 You can convert an `ItemHolder` to a `ValueNotifier` for easier integration with Flutter's state management.
 
+For this, you need to import the `hyper_storage_flutter` package:
+
+```yaml
+dependencies:
+  hyper_storage_flutter: ^<latest_version>
+```
+
+Then you can use the `asValueNotifier` extension method:
+
 ```dart
 final itemHolder = storage.itemHolder<String>('status');
 
@@ -218,9 +227,9 @@ StreamBuilder<String?>(
 );
 ```
 
-This means calling `storage.stream('key')` directly in a build method is safe and will not create multiple streams.
+> This means calling `storage.stream('key')` directly in a build method is safe and will not create multiple streams.
 
-If you have an `ItemHolder` for the key, you can use it directly in the `StreamBuilder`. This is the most efficient and clear approach.
+> If you have an `ItemHolder` for the key, you can use it directly in the `StreamBuilder`. This is the most efficient and clear approach.
 
 ```dart
 class _MyWidgetState extends State<MyWidget> {
@@ -270,6 +279,10 @@ final allTodosSubscription = todos.streamAll().listen((items) {
 allTodosSubscription.cancel();
 ```
 
+> Note: Unlike `stream<T>(key)`, the `streamAll()` method does create a new stream instance each time it's called. 
+> It is **NOT SAFE** to call `streamAll()` directly in a build method or frequently. Instead, create the stream once 
+> and reuse it.
+
 You can also stream changes for a specific key in a `SerializableStorageContainer`:
 
 ```dart

packages/hyper_storage_flutter/README.md

@@ -26,76 +26,209 @@ Then, run `flutter pub get`.
 
 ## Usage
 
-This package extends `ItemHolder` with an `asValueNotifier` helper so you can bridge Hyper Storage with Flutter's
-`ValueListenable` APIs.
+# Hyper Storage Flutter Examples
+
+This file provides examples of how to use the `hyper_storage_flutter` package to build reactive user interfaces in
+Flutter.
+
+## Listening to a Single Key
+
+There are multiple ways to listen to a single key in your storage.
+
+- Using `ItemHolder`: ItemHolder is listenable and can be streamed too.
+- Using `ItemHolder.asValueNotifier`: This is a convenient way to get a `ValueNotifier` for a specific key.
+- Using `storage.stream<E>(key)`: This provides a stream of changes for a specific key.
+
+You can use `asValueNotifier` on an `ItemHolder` to obtain a `ValueNotifier` for a specific key. This allows you to
+rebuild your UI automatically whenever the value of that key changes.
+
+### Using `ItemHolder` as `ValueNotifier`.
+
+> Note: `ItemHolder.asValueNotifier` must be called outside of the `build` method, typically in `initState` as it will
+> create a new `ValueNotifier` each time it is called.
 
 ```dart
 import 'package:flutter/material.dart';
 import 'package:hyper_storage/hyper_storage.dart';
 import 'package:hyper_storage_flutter/hyper_storage_flutter.dart';
-import 'package:hyper_storage_shared_preferences/shared_preferences_backend.dart';
-
-void main() async {
-  WidgetsFlutterBinding.ensureInitialized();
-  final storage = await HyperStorage.init(backend: SharedPreferencesBackend());
-  runApp(MyApp(storage: storage));
-}
 
-class MyApp extends StatefulWidget {
+class CounterScreen extends StatefulWidget {
   final HyperStorage storage;
 
-  const MyApp({super.key, required this.storage});
+  const CounterScreen({super.key, required this.storage});
 
   @override
-  State<MyApp> createState() => _MyAppState();
+  State<CounterScreen> createState() => _CounterScreenState();
 }
 
-class _MyAppState extends State<MyApp> {
-  late final ItemHolder<String> _messageHolder;
-  late final ValueNotifier<String?> _messageNotifier;
+class _CounterScreenState extends State<CounterScreen> {
+  late final ItemHolder<int> _counterHolder;
+  late final ValueNotifier<int?> _counterNotifier;
 
   @override
   void initState() {
     super.initState();
-    _messageHolder = widget.storage.itemHolder<String>('message');
-    _messageNotifier = _messageHolder.asValueNotifier();
+    _counterHolder = widget.storage.itemHolder<int>('counter');
+    _counterNotifier = _counterHolder.asValueNotifier();
   }
 
   @override
   void dispose() {
-    _messageNotifier.dispose();
-    _messageHolder.dispose();
+    _counterNotifier.dispose();
+    _counterHolder.dispose();
     super.dispose();
   }
 
   @override
   Widget build(BuildContext context) {
-    return MaterialApp(
-      home: Scaffold(
-        appBar: AppBar(title: const Text('Hyper Storage Flutter')),
-        body: Center(
-          child: ValueListenableBuilder<String?>(
-            valueListenable: _messageNotifier,
-            builder: (context, message, child) {
-              return Text(message ?? 'No message yet');
-            },
-          ),
+    return Scaffold(
+      body: Center(
+        child: ValueListenableBuilder<int?>(
+          valueListenable: _counterNotifier,
+          builder: (context, counter, child) {
+            return Text('Counter: ${counter ?? 0}');
+          },
         ),
-        floatingActionButton: FloatingActionButton(
-          onPressed: () async {
-            final current = await _messageHolder.get() ?? 'Hello';
-            await _messageHolder.set('$current!');
+      ),
+      floatingActionButton: FloatingActionButton(
+        onPressed: () async {
+          final currentCounter = await _counterHolder.get() ?? 0;
+          await _counterHolder.set(currentCounter + 1);
+        },
+        child: const Icon(Icons.add),
+      ),
+    );
+  }
+}
+```
+
+### Using `ItemHolder` with `StreamBuilder`.
+
+> Note: It is safe to reuse the same `ItemHolder` instance multiple times without disposing it, as it manages its own
+> resources. Calling `itemHolder` multiple times with the same key will return the same instance.
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:hyper_storage/hyper_storage.dart';
+import 'package:hyper_storage_flutter/hyper_storage_flutter.dart';
+
+class CounterScreen extends StatefulWidget {
+  final HyperStorage storage;
+
+  const CounterScreen({super.key, required this.storage});
+
+  @override
+  State<CounterScreen> createState() => _CounterScreenState();
+}
+
+class _CounterScreenState extends State<CounterScreen> {
+  late final ItemHolder<int> _counterHolder = widget.storage.itemHolder<int>('counter');
+
+  @override
+  void dispose() {
+    _counterHolder.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: Center(
+        child: StreamBuilder<int?>(
+          stream: _counterHolder,
+          builder: (context, snapshot) {
+            return Text('Counter: ${snapshot.data ?? 0}');
           },
-          child: const Icon(Icons.add),
         ),
       ),
+      floatingActionButton: FloatingActionButton(
+        onPressed: () async {
+          final currentCounter = await _counterHolder.get() ?? 0;
+          await _counterHolder.set(currentCounter + 1);
+        },
+        child: const Icon(Icons.add),
+      ),
     );
   }
 }
 ```
 
-For more detailed examples, please see the [example.md](example.md) file.
+### Using streams with `StreamBuilder`.
+
+> Note: `storage.stream<E>(key)` is safe to call inside the `build` method as it manages the stream internally.
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:hyper_storage/hyper_storage.dart';
+import 'package:hyper_storage_flutter/hyper_storage_flutter.dart';
+
+class CounterScreen extends StatefulWidget {
+  final HyperStorage storage;
+
+  const CounterScreen({super.key, required this.storage});
+
+  @override
+  State<CounterScreen> createState() => _CounterScreenState();
+}
+
+class _CounterScreenState extends State<CounterScreen> {
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: Center(
+        child: StreamBuilder<int?>(
+          stream: widget.storage.stream<int>('counter'),
+          builder: (context, snapshot) {
+            return Text('Counter: ${snapshot.data ?? 0}');
+          },
+        ),
+      ),
+      floatingActionButton: FloatingActionButton(
+        onPressed: () async {
+          final currentCounter = await widget.storage.getInt('counter') ?? 0;
+          await widget.storage.setInt('counter', currentCounter + 1);
+        },
+        child: const Icon(Icons.add),
+      ),
+    );
+  }
+}
+```
 
 ## Contributing
 
 Contributions are welcome! Please feel free to open an issue or submit a pull request.
+
+## License
+
+```
+BSD 3-Clause License
+
+Copyright (c) 2025, Hyperdesigned
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```