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:

Inheritance
Implemented types

Properties

hashCode → int
The hash code for this object.
no setterinherited
hasListeners → bool
Returns true if there are any listeners registered (global or keyed).
no setterinherited
isEmpty → Future<bool>
Returns true if the storage contains no key-value pairs.
no setterinherited
isNotEmpty → Future<bool>
Returns true if 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 key changes.
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 true if a value with the given key exists 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 E by its key.
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 E by its key.
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 true if there are any listeners registered for the given key.
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 E with the given key.
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 E with the given key.
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<String, dynamic>> value) → Future<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.