✨ update documentation and examples to reflect changes in item holder and container usage

Author: BirjuVachhani

packages/hyper_storage/README.md

@@ -69,13 +69,14 @@ Then, run `flutter pub get` or `dart pub get`.
 
 ## Usage
 
-Initialize the storage with a backend of your choice.
+Initialize the storage with the backend you want to use.
 
 ```dart
 import 'package:hyper_storage/hyper_storage.dart';
+import 'package:hyper_storage_shared_preferences/shared_preferences_backend.dart';
 
 void main() async {
-  // Initialize the storage with InMemoryBackend
+  // Initialize the storage with SharedPreferences
   final storage = await HyperStorage.init(backend: SharedPreferencesBackend());
 
   // Set a value
@@ -116,26 +117,24 @@ More backends are available in separate packages:
 
 ## Initialization
 
-You can initialize `hyper_storage` with a specific backend. If no backend is provided, it defaults to `InMemoryBackend`.
+You can initialize `hyper_storage` with any storage backend that implements the `StorageBackend` interface. Always pass
+the backend you want to use to `HyperStorage.init`.
 
-### Default (In-Memory)
+### In-memory (for tests or ephemeral data)
 
 ```dart
 import 'package:hyper_storage/hyper_storage.dart';
 
 final storage = await HyperStorage.init(backend: InMemoryBackend());
 ```
 
-### Using Other Backends
+### Using other backends
 
-To use other backends, you need to add the respective package to your `pubspec.yaml` and then provide the backend instance to the `init` method.
-
-For example, to use the Hive backend:
+Add the desired backend package to your dependencies and provide the backend instance to `init`:
 
 ```dart
-// Make sure to add hyper_storage_hive to your dependencies
-import 'package:hyper_storage_hive/hyper_storage_hive.dart';
 import 'package:hyper_storage/hyper_storage.dart';
+import 'package:hyper_storage_hive/hyper_storage_hive.dart';
 
 final storage = await HyperStorage.init(backend: HiveBackend());
 ```
@@ -213,7 +212,7 @@ final List<Map<String, dynamic>>? items = await storage.getJsonList('items');
 You can use named containers to organize your data.
 
 ```dart
-final container = await HyperStorage.container('account');
+final container = await storage.container('account');
 await container.setString('username', 'john_doe');
 final String? username = await container.getString('username');
 ```
@@ -224,30 +223,29 @@ You can store and retrieve custom objects by providing `toJson` and `fromJson` f
 
 ```dart
 class User {
+  final String id;
   final String name;
-  final int age;
 
-  User({required this.name, required this.age});
+  User({required this.id, required this.name});
 
-  factory User.fromJson(Map<String, dynamic> json) {
-    return User(name: json['name'], age: json['age']);
-  }
+  factory User.fromJson(Map<String, dynamic> json) => User(
+        id: json['id'] as String,
+        name: json['name'] as String,
+      );
 
-  Map<String, dynamic> toJson() {
-    return {'name': name, 'age': age};
-  }
+  Map<String, dynamic> toJson() => {'id': id, 'name': name};
 }
 
-final storage = await HyperStorage.objectContainer<User>(
+final users = await storage.jsonSerializableContainer<User>(
   'users',
-  toJson: (user) => user.toJson(),
   fromJson: User.fromJson,
+  toJson: (user) => user.toJson(),
+  idGetter: (user) => user.id,
 );
 
-await storage.set('user1', User(name: 'John', age: 23));
-final User? user = await storage.get('user1');
-final List<User> users = await storage.getValues();
-final Map<String, User> allUsers = await storage.getAll();
+await users.add(User(id: 'user1', name: 'John'));
+final User? user = await users.get('user1');
+final List<User> allUsers = await users.getValues();
 ```
 
 ## Checking for Keys
@@ -285,4 +283,4 @@ final storage = await HyperStorage.initMocked(initialData: {
 
 ## Contributing
 
-Contributions are welcome! Please feel free to open an issue or submit a pull request.
+Contributions are welcome! Please feel free to open an issue or submit a pull request.

packages/hyper_storage/docs/backends.md

@@ -36,7 +36,7 @@ live activities, native runners, etc.
 
 ```dart
 import 'package:hyper_storage/hyper_storage.dart';
-import 'package:hyper_storage_shared_preferences/hyper_storage_shared_preferences.dart';
+import 'package:hyper_storage_shared_preferences/shared_preferences_backend.dart';
 
 void main() async {
   final storage = await HyperStorage.init(backend: SharedPreferencesBackend());
@@ -108,7 +108,7 @@ void main() async {
   );
 
   final storage = await HyperStorage.init(
-    backend: SecureStorageBackend(secureStorage: secureStorage),
+    backend: SecureStorageBackend(storage: secureStorage),
   );
 }
 ```
@@ -143,7 +143,7 @@ You can also use multiple backends in your application by creating separate `Hyp
 
 ```dart
 import 'package:hyper_storage/hyper_storage.dart';
-import 'package:hyper_storage_shared_preferences/hyper_storage_shared_preferences.dart';
+import 'package:hyper_storage_shared_preferences/shared_preferences_backend.dart';
 import 'package:hyper_storage_hive/hyper_storage_hive.dart';
 
 void main() async {
@@ -156,4 +156,4 @@ void main() async {
   // Use hiveStorage for app data
   await hiveStorage.setString('user_data', 'some complex data');
 }
-```
+```

packages/hyper_storage/docs/containers.md

@@ -28,6 +28,7 @@ returned.
 
 ```dart
 import 'package:hyper_storage/hyper_storage.dart';
+import 'package:hyper_storage_shared_preferences/shared_preferences_backend.dart';
 
 void main() async {
     final storage = await HyperStorage.init(backend: SharedPreferencesBackend());
@@ -61,11 +62,15 @@ Containers also support storing and retrieving JSON serializable objects. You ca
 store complex data structures in a structured way. For example, storing a list of Todo items with `Todo` class.
 
 ```dart
-final todoContainer = await storage.jsonContainer<Todo>('todos');
+final todos = await storage.jsonSerializableContainer<Todo>(
+  'todos',
+  fromJson: Todo.fromJson,
+  toJson: (todo) => todo.toJson(),
+);
 
-await todoContainer.set('task1', Todo(id: 'task1', title: 'Buy groceries', isCompleted: false));
-final todo = await todoContainer.get('task1');
-await todoContainer.remove('task1');
+await todos.set('task1', Todo(id: 'task1', title: 'Buy groceries', isCompleted: false));
+final todo = await todos.get('task1');
+await todos.remove('task1');
 ```
 
 ### Providing a custom ID
@@ -74,14 +79,16 @@ By default, serializable containers would generate a unique String ID for each o
 also provide a custom ID by providing a `idGetter` function when creating the container.
 
 ```dart
-final todoContainer = await storage.jsonContainer<Todo>(
+final todos = await storage.jsonSerializableContainer<Todo>(
   'todos',
+  fromJson: Todo.fromJson,
+  toJson: (todo) => todo.toJson(),
   idGetter: (todo) => todo.id,
 );
 
-await todoContainer.add(Todo(id: 't1', title: 'Buy groceries', isCompleted: false));
-await todoContainer.get('t1');
-await todoContainer.remove('t1');
+await todos.add(Todo(id: 't1', title: 'Buy groceries', isCompleted: false));
+await todos.get('t1');
+await todos.remove('t1');
 ```
 
 ## Custom Serializable Containers
@@ -92,34 +99,55 @@ and deserialization logic.
 
 ```dart
 class XmlSerializableContainer<E extends Object> extends SerializableStorageContainer<E> {
-  XmlSerializableContainer({super.backend, super.name});
+  XmlSerializableContainer({
+    required super.backend,
+    required super.name,
+    super.delimiter,
+  });
 
   @override
   E deserialize(String value) {
-    // Implement your XML deserialization logic here
-    // For example, using an XML parsing library to convert XML string to object
-    throw UnimplementedError();
+    // Convert the stored XML string back into your object type
+    return parseXml<E>(value);
   }
 
   @override
   String serialize(E value) {
-    // Implement your XML serialization logic here
-    // For example, using an XML building library to convert object to XML string
-    throw UnimplementedError();
+    // Convert your object into an XML string for storage
+    return toXml(value);
   }
 }
+
+// Helper functions that convert between your XML representation and the Dart object.
+E parseXml<E>(String xml) => throw UnimplementedError();
+String toXml(Object value) => throw UnimplementedError();
+
+// Register the custom container with Hyper Storage
+final posts = await storage.objectContainer<Post, XmlSerializableContainer<Post>>(
+  'posts',
+  factory: () => XmlSerializableContainer<Post>(
+    backend: storage.backend,
+    name: 'posts',
+  ),
+);
+
+// storage.backend exposes the underlying backend instance that Hyper Storage uses internally.
 ```
 
 ## Container Delimiter
 
 The way containers are implemented is by prefixing the keys with the container name followed by a delimiter. 
-By default, the delimiter is a dot (`___`). For example, if you have a container named `settings` and you store a key
+By default, the delimiter is a triple underscore (`___`). For example, if you have a container named `settings` and you store a key
 `theme` with value `dark`, the actual key stored in the backend would be `settings___theme`.
 
 This is done to isolate the keys into a namespace, preventing key collisions between different containers. You can
-change the delimiter by providing a custom delimiter when initializing Hyper Storage.
+change the delimiter for serializable containers by providing the `delimiter` argument when creating them.
 
 ```dart
-// Create a storage instance with a custom delimiter.
-final storage = await storage.container('todos', delimiter: '--');
-```
+final todos = await storage.jsonSerializableContainer<Todo>(
+  'todos',
+  fromJson: Todo.fromJson,
+  toJson: (todo) => todo.toJson(),
+  delimiter: '--',
+);
+```

packages/hyper_storage/docs/enums.md

@@ -59,15 +59,18 @@ final brightness = await container.getEnum<Brightness>('brightness', Brightness.
 You can also use the generic `get` method to retrieve enums:
 
 ```dart
-final role = await storage.get<Role>('role', Role.values);
+final role = await storage.get<Role>('role', enumValues: 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);
+final roleHolder = storage.itemHolder<Role>(
+  'role',
+  enumValues: Role.values,
+);
 
 // Set the enum value
 await roleHolder.set(Role.user);
@@ -81,7 +84,7 @@ final role = await roleHolder.get();
 You can stream changes to enum values using the `stream` method. Here's an example:
 
 ```dart
-final roleStream = storage.stream<Role>('role', Role.values);
+final roleStream = storage.stream<Role>('role', enumValues: Role.values);
 
 roleStream.listen((role) {
   print('Role changed to: $role');
@@ -93,10 +96,12 @@ With containers:
 ```dart
 final container = await storage.container('settings');
 
-final brightnessStream = container.stream<Brightness>('brightness', Brightness.values);
+final brightnessStream = container.stream<Brightness>(
+  'brightness',
+  enumValues: Brightness.values,
+);
 
 brightnessStream.listen((brightness) {
   print('Brightness changed to: $brightness');
 });
 ```
-