🎨 enhance container method to accept optional delimiter and update documentation

Author: BirjuVachhani

packages/hyper_storage/.gitignore

@@ -7,3 +7,5 @@
 pubspec.lock
 
 .idea/
+
+doc/

packages/hyper_storage/README.md

@@ -1,18 +1,20 @@
 # hyper_storage
 
 [![pub version](https://img.shields.io/pub/v/hyper_storage.svg)](https://pub.dev/packages/hyper_storage)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-A simple and flexible key-value storage for Dart and Flutter applications, supporting multiple backends.
+A simple and unified key-value storage for Dart and Flutter applications, supporting multiple backends.
 
 ## Features
 
--   ✅ **Simple API:** Easy to use API for storing and retrieving data.
--   ✅ **Multiple Backends:** Supports different backends like `InMemory`, with more to come.
--   ✅ **Typed Storage:** Store and retrieve data with type safety.
--   ✅ **JSON Serialization:** Store and retrieve custom objects by providing `toJson` and `fromJson` functions.
--   ✅ **Named Containers:** Organize your data into named containers.
--   ✅ **Mockable:** Easy to mock for testing purposes.
+- ✅ **Simple API:** Easy to use API for storing and retrieving data.
+- ✅ **Multiple Backends:** Supports different backends like `InMemory`, `hive`, `shared_preferences`, and `secure_storage` (via separate packages).
+- ✅ **Typed Storage:** Store and retrieve data with type safety.
+- ✅ **JSON Serialization:** Store and retrieve custom objects by providing `toJson` and `fromJson` functions.
+- ✅ **Named Containers:** Organize your data into named containers for better structure.
+- ✅ **Asynchronous:** All operations are asynchronous, making it suitable for Flutter applications.
+- ✅ **Cross-Platform:** Works on mobile, web, and desktop platforms.
+- ✅ **Fully Tested:** Comprehensive test coverage to ensure reliability.
+- ✅ **Mockable:** Easy to mock for testing purposes.
 
 ## Getting started
 
@@ -21,20 +23,27 @@ Add `hyper_storage` to your `pubspec.yaml` dependencies:
 ```yaml
 dependencies:
   hyper_storage: ^0.1.0 # Replace with the latest version
+
+  hyper_storage_flutter: ^0.1.0 # Add this if you're using Flutter.
+
+  # Add one of the available backends of your choice:
+  hyper_storage_hive: ^0.1.0
+  hyper_storage_shared_preferences: ^0.1.0
+  hyper_secure_storage: ^0.1.0
 ```
 
 Then, run `flutter pub get` or `dart pub get`.
 
 ## Usage
 
-Initialize the storage with a backend. The `InMemoryBackend` is included by default for temporary storage.
+Initialize the storage with a backend of your choice.
 
 ```dart
 import 'package:hyper_storage/hyper_storage.dart';
 
 void main() async {
   // Initialize the storage with InMemoryBackend
-  final storage = await HyperStorage.init(backend: InMemoryBackend());
+  final storage = await HyperStorage.init(backend: SharedPreferencesBackend());
 
   // Set a value
   await storage.setString('name', 'Hyper Storage');
@@ -60,6 +69,185 @@ More backends are available in separate packages:
 -   [hyper_storage_shared_preferences](https://pub.dev/packages/hyper_storage_shared_preferences): SharedPreferences backend for persistent storage.
 -   [hyper_secure_storage](https://pub.dev/packages/hyper_secure_storage): Secure storage backend for sensitive data.
 
+## Contents
+
+-   [Initialization](#initialization)
+-   [Basic Operations](#basic-operations)
+-   [Typed Data](#typed-data)
+-   [JSON Data](#json-data)
+-   [Named Containers](#named-containers)
+-   [Object Containers](#object-containers)
+-   [Checking for Keys](#checking-for-keys)
+-   [Closing the Storage](#closing-the-storage)
+-   [Mocking for Tests](#mocking-for-tests)
+
+## Initialization
+
+You can initialize `hyper_storage` with a specific backend. If no backend is provided, it defaults to `InMemoryBackend`.
+
+### Default (In-Memory)
+
+```dart
+import 'package:hyper_storage/hyper_storage.dart';
+
+final storage = await HyperStorage.init(backend: InMemoryBackend());
+```
+
+### 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:
+
+```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';
+
+final storage = await HyperStorage.init(backend: HiveBackend());
+```
+
+## Basic Operations
+
+You can use the `set` and `get` methods to store and retrieve data.
+
+```dart
+// Set a value
+await storage.set('name', 'Hyper Storage');
+
+// Get a value
+final name = await storage.get('name');
+print(name); // Output: Hyper Storage
+```
+
+## Typed Data
+
+`hyper_storage` provides typed methods to store and retrieve data with type safety.
+
+### Storing Data
+
+```dart
+await storage.setString('name', 'John');
+await storage.setInt('age', 30);
+await storage.setBool('isDeveloper', true);
+await storage.setDouble('height', 1.75);
+await storage.setStringList('skills', ['Dart', 'Flutter', 'JavaScript']);
+```
+
+### Getting Data
+
+```dart
+final String? name = await storage.getString('name');
+final int? age = await storage.getInt('age');
+final bool? isDeveloper = await storage.getBool('isDeveloper');
+final double? height = await storage.getDouble('height');
+final List<String>? skills = await storage.getStringList('skills');
+```
+
+## JSON Data
+
+You can store and retrieve JSON data (`Map<String, dynamic>`) and lists of JSON data (`List<Map<String, dynamic>>`).
+
+### Storing JSON
+
+```dart
+await storage.setJson('profile', {
+    'name': 'John Doe',
+    'age': 30,
+    'isDeveloper': true,
+    'height': 1.75,
+    'skills': ['Dart', 'Flutter', 'JavaScript'],
+});
+
+await storage.setJsonList('items', [
+    {'id': 1, 'name': 'Item 1'},
+    {'id': 2, 'name': 'Item 2'},
+    {'id': 3, 'name': 'Item 3'},
+]);
+```
+
+### Getting JSON
+
+```dart
+final Map<String, dynamic>? profile = await storage.getJson('profile');
+final List<Map<String, dynamic>>? items = await storage.getJsonList('items');
+```
+
+## Named Containers
+
+You can use named containers to organize your data.
+
+```dart
+final container = await HyperStorage.container('account');
+await container.setString('username', 'john_doe');
+final String? username = await container.getString('username');
+```
+
+## Object Containers
+
+You can store and retrieve custom objects by providing `toJson` and `fromJson` functions.
+
+```dart
+class User {
+  final String name;
+  final int age;
+
+  User({required this.name, required this.age});
+
+  factory User.fromJson(Map<String, dynamic> json) {
+    return User(name: json['name'], age: json['age']);
+  }
+
+  Map<String, dynamic> toJson() {
+    return {'name': name, 'age': age};
+  }
+}
+
+final storage = await HyperStorage.objectContainer<User>(
+  'users',
+  toJson: (user) => user.toJson(),
+  fromJson: User.fromJson,
+);
+
+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();
+```
+
+## Checking for Keys
+
+You can check if a key exists in the storage.
+
+```dart
+final bool containsName = await storage.containsKey('name');
+```
+
+## Closing the Storage
+
+It's important to close the storage when it's no longer needed to release resources.
+
+```dart
+await storage.close(); // closes all containers.
+```
+
+## Mocking for Tests
+
+For testing, you can use a mocked version of the storage.
+
+```dart
+final storage = await HyperStorage.initMocked();
+```
+
+You can also provide initial data to the mocked storage.
+
+```dart
+final storage = await HyperStorage.initMocked(initialData: {
+  'name': 'Test',
+  'age': 25,
+});
+```
+
 ## Contributing
 
 Contributions are welcome! Please feel free to open an issue or submit a pull request.

packages/hyper_storage/analysis_options.yaml

@@ -11,6 +11,7 @@ linter:
     use_super_parameters: true
     prefer_relative_imports: true
     public_member_api_docs: true
+    comment_references: true
 
 formatter:
   page_width: 120

packages/hyper_storage/example.md packages/hyper_storage/example/example.mdpackages/hyper_storage/example.md renamed to packages/hyper_storage/example/example.md

@@ -3,6 +3,7 @@
 // found in the LICENSE file.
 library;
 
+export 'src/api/api.dart';
 export 'src/api/backend.dart' hide GenericStorageOperationsMixin;
 export 'src/api/listenable.dart' hide ListenableStorage;
 export 'src/api/serializable_container.dart';

packages/hyper_storage/lib/hyper_storage.dart

@@ -38,16 +38,22 @@ abstract class StorageBackend with GenericStorageOperationsMixin implements Stor
   /// you to organize data into logical groups without key collisions.
   ///
   /// Parameters:
-  /// * [name] - The unique name for the container. This is used to namespace
+  /// - [name] - The unique name for the container. This is used to namespace
   ///   all keys within the container.
+  /// - [delimiter] - Optional. The character(s) used to separate the container name.
+  ///  If not provided, the default delimiter defined in [StorageContainer.defaultDelimiter]
   ///
   /// Returns a [Future] that completes with a new [HyperStorageContainer]
   /// instance configured to use this backend.
   ///
   /// Throws:
   /// * [ArgumentError] if the name is empty, contains only whitespace, or
   ///   contains invalid characters.
-  Future<HyperStorageContainer> container(String name) async => HyperStorageContainer(backend: this, name: name);
+  Future<HyperStorageContainer> container(String name, {String? delimiter}) async => HyperStorageContainer(
+    backend: this,
+    name: name,
+    delimiter: delimiter,
+  );
 
   @override
   Future<bool> get isEmpty async {

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

@@ -46,10 +46,10 @@ class HiveBackend extends StorageBackend {
   Future<void> init() async => _box ??= await Hive.openBox(name);
 
   @override
-  Future<HyperStorageContainer> container(String name) async {
+  Future<HyperStorageContainer> container(String name, {String? delimiter}) async {
     final backend = HiveBackend(boxName: name);
     await backend.init();
-    return HyperStorageContainer(backend: backend, name: name);
+    return HyperStorageContainer(backend: backend, name: name, delimiter: delimiter);
   }
 
   @override

packages/hyper_storage_hive/lib/src/backend.dart

@@ -47,10 +47,10 @@ class LazyHiveBackend extends StorageBackend {
   ///
   /// This method creates a new box with the given [name] and initializes it.
   @override
-  Future<HyperStorageContainer> container(String name) async {
+  Future<HyperStorageContainer> container(String name, {String? delimiter}) async {
     final backend = LazyHiveBackend(boxName: name);
     await backend.init();
-    return HyperStorageContainer(backend: backend, name: name);
+    return HyperStorageContainer(backend: backend, name: name, delimiter: delimiter);
   }
 
   @override

packages/hyper_storage_hive/lib/src/lazy_backend.dart

@@ -13,4 +13,7 @@ test:
   - cd packages/hyper_secure_storage && flutter test
   - cd packages/hyper_storage_flutter && flutter test
 
+doc:
+  - cd packages/hyper_storage && rm -rf doc && dart doc
+
 format: dart format --fix .