✨ optimize setAll method for batch writes and improve documentation

Author: BirjuVachhani

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

@@ -73,9 +73,11 @@ abstract class StorageBackend with GenericStorageOperationsMixin implements Stor
 
   @override
   Future<void> setAll(Map<String, dynamic> values) async {
-    for (final MapEntry(:key, :value) in values.entries) {
-      set(key, value);
-    }
+    if (values.isEmpty) return;
+    final List<Future<void>> writes = <Future<void>>[
+      for (final MapEntry(:key, :value) in values.entries) set(key, value),
+    ];
+    await Future.wait(writes);
   }
 
   @override

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

@@ -63,8 +63,9 @@ abstract class StorageContainer extends BaseStorage {
   /// The default delimiter to use if one is not provided.
   ///
   /// When creating a container without specifying a delimiter, this default
-  /// value ("___") is used. The dot character is chosen as it's commonly used
-  /// for namespacing and is unlikely to appear in most keys.
+  /// value ("___") is used. The triple-underscore sequence is chosen because it
+  /// is unlikely to appear in user-provided keys or container names, providing a
+  /// safe namespace separator.
   static const defaultDelimiter = '___';
 
   /// A regular expression that matches all allowed delimiter characters.

packages/hyper_storage/lib/src/hyper_storage.dart

@@ -406,6 +406,7 @@ class HyperStorage extends _HyperStorageImpl {
   ///   - List of JSON Map
   ///   - DateTime
   ///   - Duration
+  ///   - Uint8List
   ///   - Enum (requires providing [enumValues])
   Stream<E?> stream<E extends Object>(String key, {List<Enum>? enumValues}) async* {
     if (enumValues != null) checkEnumType<E>(enumValues);

packages/hyper_storage/lib/src/hyper_storage_container.dart

@@ -278,6 +278,7 @@ final class HyperStorageContainer extends StorageContainer with ItemHolderMixin,
   ///   - List of JSON Map
   ///   - DateTime
   ///   - Duration
+  ///   - Uint8List
   ///   - Enum (requires providing [enumValues])
   Stream<E?> stream<E extends Object>(String key, {List<Enum>? enumValues}) async* {
     if (enumValues != null) checkEnumType<E>(enumValues);

packages/hyper_storage/lib/src/item_holder.dart

@@ -45,17 +45,19 @@ class ItemHolder<E extends Object> with Stream<E?> implements BaseListenable, It
   /// If not provided, the default backend's get method will be used.
   /// This allows for flexibility in how items are retrieved.
   ///
-  /// If either getter or setter is provided, both must be provided.
-  /// This ensures that the item can be both retrieved and stored correctly.
+  /// When overriding access behaviour, provide both getter and setter so the
+  /// holder can read and write symmetrically. If either callback is omitted,
+  /// the corresponding backend default will be used.
   final ItemGetter<E>? getter;
 
   /// Custom setter function to store the item in the backend.
   ///
   /// If not provided, the default backend's set method will be used.
   /// This allows for flexibility in how items are stored.
   ///
-  /// If either getter or setter is provided, both must be provided.
-  /// This ensures that the item can be both retrieved and stored correctly.
+  /// When overriding access behaviour, provide both getter and setter so the
+  /// holder can read and write symmetrically. If either callback is omitted,
+  /// the corresponding backend default will be used.
   final ItemSetter<E>? setter;
 
   final StreamController<E?> _streamController = StreamController<E?>.broadcast();
@@ -305,8 +307,7 @@ mixin ItemHolderMixin on BaseStorage {
   ///     map. This is called when storing the object.
   ///
   /// Returns:
-  ///   A [Future] that completes with a [JsonItemHolder] configured to
-  ///   manage the object at the specified key.
+  ///   A [JsonItemHolder] configured to manage the object at the specified key.
   ///
   /// Throws:
   ///   * [ArgumentError] if the key is invalid (empty or only whitespace)
@@ -409,6 +410,7 @@ mixin ItemHolderMixin on BaseStorage {
   /// - List of String
   /// - JSON Map
   /// - List of JSON Maps
+  /// - Uint8List
   /// - Enum (requires providing [enumValues] unless custom getter/setter supplied)
   ///
   /// Parameters:

packages/hyper_storage_hive/lib/src/lazy_backend.dart

@@ -17,7 +17,7 @@ class LazyHiveBackend extends StorageBackend {
   /// The underlying Hive box instance, or null if not yet initialized.
   LazyBox? _box;
 
-  /// The active Hive [Box] instance used for storage operations.
+  /// The active Hive [LazyBox] instance used for storage operations.
   LazyBox get box => _box ?? (throw StateError('HiveBackend not initialized. Call init() first.'));
 
   /// Creates a new [LazyHiveBackend] instance with optional named box support.

packages/hyper_storage_shared_preferences/lib/src/backend.dart

@@ -23,7 +23,8 @@ class SharedPreferencesBackend extends StorageBackend {
   /// Optionally accepts an existing [SharedPreferencesAsync] instance for
   /// dependency injection or custom configuration.
   ///
-  /// If none is provided, a new instance will be created during [init].
+  /// If none is provided, a new instance is created immediately, so additional
+  /// initialization is not required before use.
   SharedPreferencesBackend([SharedPreferencesAsync? prefs]) : _prefs = prefs ?? SharedPreferencesAsync();
 
   @override