Box<K, T> class
The Box class provides a convenient, type-safe, and composable API for working with Hive boxes in Dart and Flutter applications. It acts as a decorator over the underlying BoxInterface, allowing you to easily configure, open, and interact with boxes of various types (regular, lazy, isolated, isolated lazy) using a unified interface.
Type Parameters:
K: The type of keys used in the box.T: The type of values stored in the box.
Example usage:
// Create a regular box
final box = Box<String, MyModel>.regular('myBox');
await box.put('key', MyModel(...));
final value = await box.get('key');
// Create a lazy box
final lazyBox = Box<String, MyModel>.lazy('myLazyBox');
// Create from config
final config = BoxConfig('myBox', type: BoxType.isolated);
final boxFromConfig = Box<String, MyModel>.fromConfig(config);
See also:
- Inheritance
-
- Object
- BoxInterface<
K, T> - Box
- Implementers
- Available extensions
Constructors
- Box(String name, {BoxType type = BoxType.regular, HiveCipher? encryptionCipher, bool crashRecovery = true, String? path, String? collection, LogHandler? logger})
- Creates a new Box instance with the given configuration.
- Box.fromConfig(BoxConfig config)
-
Creates a Box from a BoxConfig instance.
factory
- Box.isolated(String name, {HiveCipher? encryptionCipher, bool crashRecovery = true, String? path, String? collection, LogHandler? logger})
-
Creates a strongly-typed, non-lazy, isolated Box.
factory
- Box.isolatedLazy(String name, {HiveCipher? encryptionCipher, bool crashRecovery = true, String? path, String? collection, LogHandler? logger})
-
Creates a strongly-typed, lazy, isolated Box.
factory
- Box.lazy(String name, {HiveCipher? encryptionCipher, bool crashRecovery = true, String? path, String? collection, LogHandler? logger})
-
Creates a strongly-typed, lazy Box.
factory
- Box.regular(String name, {HiveCipher? encryptionCipher, bool crashRecovery = true, String? path, String? collection, LogHandler? logger})
-
Creates a strongly-typed, non-lazy, non-isolated Box.
factory
Properties
- boxType → BoxType
-
The type of the native Hive box managed by this class.
no setterinherited
- hashCode → int
-
The hash code for this object.
no setterinherited
-
isEmpty
→ Future<
bool> -
Returns
trueif the box contains no elements.no setterinherited - isInitialized → bool
-
Whether the box has been initialized and is ready for operations.
no setterinherited
- isIsolated → bool
-
Whether this box is running in an isolated (background) context.
no setterinherited
- isLazy → bool
-
Whether this box is a lazy box (values loaded on demand).
no setterinherited
-
isNotEmpty
→ Future<
bool> -
Returns
trueif the box contains at least one element.no setterinherited - isOpen → bool
-
Whether the underlying Hive box is currently open.
no setterinherited
-
length
→ Future<
int> -
The number of key-value pairs in the box.
no setterinherited
- logger → LogHandler?
-
Optional logger for capturing diagnostic and error information.
final
- name → String
-
finalinherited
- path → String?
-
The resolved storage path for this box, if set.
no setterinherited
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- type → BoxType
-
Available on BoxInterface<
Returns the BoxType of this box instance.K, T> , provided by the GetTypeOfBoxInterfaceExtension extensionno setter
Methods
-
add(
T value) → Future< int> -
Adds a value to the box using an auto-incremented key (if supported).
inherited
-
addAll(
Iterable< T> values) → Future<Iterable< int> > -
Adds multiple values to the box using auto-incremented keys (if supported).
inherited
-
clear(
) → Future< void> -
Removes all key-value pairs from the box.
inherited
-
closeBox(
) → Future< void> -
Closes the box, releasing all resources.
inherited
-
compactBox(
) → Future< void> -
Compacts the box, removing unused space.
inherited
-
containsKey(
K key) → Future< bool> -
Returns
trueif the box contains the givenkey.inherited -
delete(
K key) → Future< void> -
Deletes the value associated with the given
key.inherited -
deleteAll(
Iterable< K> keys) → Future<void> -
Deletes the values associated with the given
keys.inherited -
deleteAt(
int index) → Future< void> -
Deletes the value at the specified
index.inherited -
deleteFromDisk(
) → Future< void> -
Deletes the box from disk.
inherited
-
ensureInitialized(
) → Future< void> -
Ensures the box is initialized and ready for use.
inherited
-
estimateSizeBytes(
) → Future< int> -
Returns approximate in-memory size (in bytes) of the entire box content.
inherited
-
firstKeyWhere(
bool condition(K key, T value)) → Future< K?> -
Returns the first key for the given
condition.inherited -
firstValueWhere(
bool condition(K key, T value)) → Future< T?> -
Returns the first value for the given
condition.inherited -
firstWhereContains(
String query, {required String searchableText(T)}) → Future< T?> -
Returns the first value whose
searchableTextcontainsquery, ornull.inherited -
firstWhereOrNull(
bool condition(T)) → Future< T?> -
Returns the first value matching
condition, ornullif none found.inherited -
flushBox(
) → Future< void> -
Flushes any pending changes to disk.
inherited
-
foreachKey(
Future< void> action(K key), {bool breakCondition()?}) → Future<void> -
Iterates asynchronously over all keys, invoking
actionfor each.inherited -
foreachValue(
Future< void> action(K, T), {bool breakCondition()?}) → Future<void> -
Iterates asynchronously over all key-value pairs, invoking
actionfor each.inherited -
generateBackupCompressed(
{String keyToString(K key)?, Object? valueToJson(T value)?}) → Future< Uint8List> -
Available on BoxInterface<
Generates a compressed binary backup (Uint8List) of all key-value pairs in the box.K, T> , provided by the BackupCompressedExtension extension -
generateBackupJson(
{String keyToString(K key)?, Object? valueToJson(T value)?}) → Future< String> -
Available on BoxInterface<
Generates a JSON string representing all key-value pairs in the box.K, T> , provided by the BackupJsonExtension extension -
get(
K key, {T? defaultValue}) → Future< T?> -
Returns the value for the given
key, or null if not found.inherited -
getAllKeys(
) → Future< Iterable< K> > -
Returns all keys in the box.
inherited
-
getAllValues(
) → Future< Iterable< T> > -
Returns all values in the box.
inherited
-
getAt(
int index) → Future< T?> -
Returns the value at the specified
index, ornullif not found.inherited -
getKeysWhere(
bool condition(K key, T value)) → Future< List< K> > -
Returns the keys for the given
condition.inherited -
getMany(
Iterable< K> keys) → Future<List< T> > -
Returns the values for the given
keys.inherited -
getValuesWhere(
bool condition(T)) → Future< List< T> > -
Returns the values for the given
condition.inherited -
keyAt(
int index) → Future< K?> -
Returns the key at the specified
index. ornullif not found.inherited -
moveKey(
K oldKey, K newKey) → Future< bool> -
Moves the value from
oldKeytonewKey, replacing any existing value.inherited -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
put(
K key, T value) → Future< void> -
Inserts a new key-value pair into the box.
inherited
-
putAll(
Map< K, T> entries) → Future<void> -
Inserts multiple key-value pairs into the box.
inherited
-
putAt(
int index, T value) → Future< void> -
Inserts a new key-value pair into the box at the specified
index.inherited -
replaceAll(
Map< K, T> entries) → Future<void> -
Replaces all data in the box with the given
entries.inherited -
restoreBackupCompressed(
Uint8List data, {required K stringToKey(String key), required T jsonToValue(dynamic json)}) → Future< void> -
Available on BoxInterface<
Restores the box contents from a compressed binary backup (Uint8List).K, T> , provided by the BackupCompressedExtension extension -
restoreBackupJson(
String json, {required K stringToKey(String key), required T jsonToValue(dynamic json)}) → Future< void> -
Available on BoxInterface<
Restores the box contents from a JSON string backup.K, T> , provided by the BackupJsonExtension extension -
search(
{required String query, required String searchableText(T item), int? page, int pageSize = 20, List< SortCriterion< ? sortBy}) → Future<T> >List< T> > -
Available on BoxInterface<
Performs a full-text search, optional multi-criteria sort, and pagination on the box values.K, T> , provided by the SearchExtensionMethod extension -
searchKeyOf(
T value) → Future< K?> -
Returns the key for the given
value, ornullif not found.inherited -
toMap(
) → Future< Map< K, T> > -
Returns a map containing all key-value pairs in the box.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
-
valueAt(
int index) → Future< T?> -
Returns the value at the specified
index, ornullif not found.inherited -
watch(
K key) → Stream< BoxEvent> -
Watches for changes to the value associated with
key.inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited