BoxInterface<K, T> class abstract

The base interface for all HivezBox types, providing a strongly-typed, production-grade abstraction over Hive boxes.

This class defines the contract for all synchronous and asynchronous operations supported by Hivez, including CRUD, query, and box management methods. All HivezBox variants (regular, lazy, isolated, etc.) extend this interface to ensure a consistent API.

Type Parameters:

  • K: The type of the keys used in the box.
  • T: The type of the values stored in the box.
Implementers
Available extensions

Constructors

BoxInterface(String name, {HiveCipher? encryptionCipher, bool crashRecovery = true, String? path, String? collection})
Constructs a BoxInterface with the given name and options.
const

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 setteroverride
isEmpty → Future<bool>
Returns true if 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 true if 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
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<K, T>, provided by the GetTypeOfBoxInterfaceExtension extension

Returns the BoxType of this box instance.
no 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 true if the box contains the given key.
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.
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 item)}) → Future<T?>
Returns the first value whose searchableText contains query, or null.
inherited
firstWhereOrNull(bool condition(T item)) → Future<T?>
Returns the first value matching condition, or null if 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 action for each.
inherited
foreachValue(Future<void> action(K key, T value), {bool breakCondition()?}) → Future<void>
Iterates asynchronously over all key-value pairs, invoking action for each.
inherited
generateBackupCompressed({String keyToString(K key)?, Object? valueToJson(T value)?}) → Future<Uint8List>

Available on BoxInterface<K, T>, provided by the BackupCompressedExtension extension

Generates a compressed binary backup (Uint8List) of all key-value pairs in the box.
generateBackupJson({String keyToString(K key)?, Object? valueToJson(T value)?}) → Future<String>

Available on BoxInterface<K, T>, provided by the BackupJsonExtension extension

Generates a JSON string representing all key-value pairs in the box.
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, or null if 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 item)) → Future<List<T>>
Returns the values for the given condition.
inherited
keyAt(int index) → Future<K?>
Returns the key at the specified index. or null if not found.
inherited
moveKey(K oldKey, K newKey) → Future<bool>
Moves the value from oldKey to newKey, 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<K, T>, provided by the BackupCompressedExtension extension

Restores the box contents from a compressed binary backup (Uint8List).
restoreBackupJson(String json, {required K stringToKey(String key), required T jsonToValue(dynamic json)}) → Future<void>

Available on BoxInterface<K, T>, provided by the BackupJsonExtension extension

Restores the box contents from a JSON string backup.

Available on BoxInterface<K, T>, provided by the SearchExtensionMethod extension

Performs a full-text search, optional multi-criteria sort, and pagination on the box values.
searchKeyOf(T value) → Future<K?>
Returns the key for the given value, or null if 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.
override
valueAt(int index) → Future<T?>
Returns the value at the specified index, or null if not found.
watch(K key) → Stream<BoxEvent>
Watches for changes to the value associated with key.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
override