HyperStorage class Introduction Getting Started
The main entry point for the HyperStorage library, providing centralized storage management with a singleton pattern.
HyperStorage serves as the primary interface for all storage operations, managing containers and providing direct access to storage functionality. It implements a singleton pattern to ensure consistent access to storage across your application while supporting multiple storage backends.
Before using HyperStorage, you must initialize it with a backend.
Container-Based Storage: Containers provide namespaced storage for better organization:
JSON Serializable Containers: Store custom objects with automatic JSON serialization:
Supports Custom Serializable Containers: For advanced use cases, create custom container implementations.
HyperStorage uses a singleton pattern which is safe for concurrent access within a single isolate. For multi-isolate access, ensure your backend supports it or implement proper synchronization.
Container Caching
Containers are cached by name. Requesting the same container multiple times returns the same instance.
See also:
StorageContainerfor basic container functionality- JsonStorageContainer for JSON serialization
- SerializableStorageContainer for custom object storage
- StorageBackend for implementing custom backends
- Inheritance
-
- Object
- BaseStorage
- HyperStorage
- Implemented types
Properties
- hashCode → int
-
The hash code for this object.
no setterinherited
- hasListeners → bool
-
Returns
trueif there are any listeners registered (global or keyed).no setterinherited -
isEmpty
→ Future<
bool> -
Returns
trueif the storage contains no key-value pairs.no setterinherited -
isNotEmpty
→ Future<
bool> -
Returns
trueif the storage contains one or more key-value pairs.no setterinherited - runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
addKeyListener(
String key, ListenableCallback listener) → void -
Registers a listener to be called when data for a specific
keychanges.inherited -
addListener(
ListenableCallback listener) → void -
Registers a global listener to be called when any data in the storage
changes.
inherited
-
clear(
) → Future< void> -
Destroys the HyperStorage instance and deletes all stored data.
override
-
close(
) → Future< void> -
Closes the HyperStorage instance and releases all resources.
override
-
container(
String name) → Future< HyperStorageContainer> - Retrieves or creates a basic storage container with the specified name.
-
containsKey(
String key) → Future< bool> -
Returns
trueif a value with the givenkeyexists in the storage.inherited -
customItemHolder<
H extends ItemHolder< (E> , E extends Object>String key, {required H create(StorageBackend backend, String key)}) → H -
Creates a custom item holder using the provided factory function.
inherited
-
get<
E extends Object> (String key, {List< Enum> ? enumValues}) → Future<E?> -
Retrieves a value of type
Eby itskey.inherited -
getAll(
[Iterable< String> ? allowList]) → Future<Map< String, dynamic> > -
Retrieves all key-value pairs from the storage.
inherited
-
getBool(
String key) → Future< bool?> -
Retrieves a bool value by its
key.inherited -
getBytes(
String key) → Future< Uint8List?> -
Retrieves a byte array by its
key.inherited -
getDateTime(
String key, {bool isUtc = false}) → Future< DateTime?> -
Retrieves a DateTime value by its
key.inherited -
getDouble(
String key) → Future< double?> -
Retrieves a double value by its
key.inherited -
getDuration(
String key) → Future< Duration?> -
Retrieves a Duration value by its
key.inherited -
getEnum<
E extends Enum> (String key, List< E> values) → Future<E?> -
Retrieves an enum value of type
Eby itskey.inherited -
getInt(
String key) → Future< int?> -
Retrieves an int value by its
key.inherited -
getJson(
String key) → Future< Map< String, dynamic> ?> -
Retrieves a JSON object by its
key.inherited -
getJsonList(
String key) → Future< List< Map< ?>String, dynamic> > -
Retrieves a list of JSON objects by its
key.inherited -
getKeys(
) → Future< Set< String> > -
Returns a set of all keys currently stored in the storage.
inherited
-
getString(
String key) → Future< String?> -
Retrieves a String value by its
key.inherited -
getStringList(
String key) → Future< List< String> ?> -
Retrieves a list of strings by its
key.inherited -
hasKeyListeners(
String key) → bool -
Returns
trueif there are any listeners registered for the givenkey.inherited -
itemHolder<
E extends Object> (String key, {ItemGetter< E> ? get, ItemSetter<E> ? set, List<Enum> ? enumValues}) → ItemHolder<E> -
Creates an item holder for storing a single primitive value at the specified key.
inherited
-
jsonContainer<
E extends Object> (String name, {required ToJson< E> toJson, required FromJson<E> fromJson, IdGetter<E> ? idGetter, Random? random, int? seed, String? delimiter}) → Future<JsonStorageContainer< E> > - Creates or retrieves a JSON-serializable storage container for custom objects.
-
jsonItemHolder<
E extends Object> (String key, {required FromJson< E> fromJson, required ToJson<E> toJson}) → JsonItemHolder<E> -
Creates an item holder for storing a single serializable object at the specified key.
inherited
-
jsonStream<
E extends Object> (String key, {required FromJson< E> fromJson, required ToJson<E> toJson}) → Stream<E?> -
Provides a Stream of JSON-serializable objects for the given
key. -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
notifyListeners(
[String? key]) → void -
Notifies all registered listeners of a change.
inherited
-
objectContainer<
E extends Object, F extends SerializableStorageContainer< (E> >String name, {required F factory()}) → Future< F> - Creates or retrieves a custom serializable storage container.
-
remove(
String key) → Future< void> -
Removes a value by its
key.inherited -
removeAll(
Iterable< String> keys) → Future<void> -
Removes multiple values by their keys in a single operation.
inherited
-
removeAllKeyListeners(
String key) → void -
Removes all listeners registered for a specific
key.inherited -
removeAllListeners(
) → void -
Removes all registered listeners, both global and key-specific.
inherited
-
removeKeyListener(
String key, ListenableCallback listener) → void -
Removes a previously registered key-specific listener.
inherited
-
removeListener(
ListenableCallback listener) → void -
Removes a previously registered global listener.
inherited
-
serializableItemHolder<
E extends Object> (String key, {required SerializeCallback< E> serialize, required DeserializeCallback<E> deserialize}) → SerializableItemHolder<E> -
Creates an item holder for storing a single serializable object at the specified key.
inherited
-
serializableStream<
E extends Object> (String key, {required SerializeCallback< E> serialize, required DeserializeCallback<E> deserialize}) → Stream<E?> -
Provides a Stream of custom-serializable objects for the given
key. -
set<
E extends Object> (String key, E value) → Future< void> -
Saves a value of type
Ewith the givenkey.inherited -
setAll(
Map< String, dynamic> values) → Future<void> -
Saves multiple key-value pairs from a Map in a single operation.
inherited
-
setBool(
String key, bool value) → Future< void> -
Saves a bool value with the given
key.inherited -
setBytes(
String key, Uint8List bytes) → Future< void> -
Saves a byte array with the given
key.inherited -
setDateTime(
String key, DateTime value) → Future< void> -
Saves a DateTime value with the given
key.inherited -
setDouble(
String key, double value) → Future< void> -
Saves a double value with the given
key.inherited -
setDuration(
String key, Duration value) → Future< void> -
Saves a Duration value with the given
key.inherited -
setEnum<
E extends Enum> (String key, E value) → Future< void> -
Saves an enum value of type
Ewith the givenkey.inherited -
setInt(
String key, int value) → Future< void> -
Saves an int value with the given
key.inherited -
setJson(
String key, Map< String, dynamic> value) → Future<void> -
Saves a JSON object (Map) with the given
key.inherited -
setJsonList(
String key, List< Map< value) → Future<String, dynamic> >void> -
Saves a list of JSON objects with the given
key.inherited -
setString(
String key, String value) → Future< void> -
Saves a String value with the given
key.inherited -
setStringList(
String key, List< String> value) → Future<void> -
Saves a list of strings with the given
key.inherited -
stream<
E extends Object> (String key, {List< Enum> ? enumValues}) → Stream<E?> -
Provides a Stream of values for the given
key. -
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Properties
- instance → HyperStorage
-
Returns the singleton instance of HyperStorage.
no setter
Static Methods
-
init(
{required StorageBackend backend}) → Future< HyperStorage> - Initializes the HyperStorage singleton with the specified backend.
-
initMocked(
{Map< String, dynamic> ? initialData}) → Future<HyperStorage> - Initializes HyperStorage with an in-memory backend for testing purposes.
-
newInstance(
{required StorageBackend backend}) → Future< HyperStorage> - Creates a new instance of HyperStorage with the specified backend.