BaseHivezBox<K, T> class abstract

Base class for all HivezBox implementations, providing core logic for initialization, locking, logging, and high-level box operations.

This abstract class implements BoxInterface and _BoxInterfaceHelpers, and is intended to be extended by concrete HivezBox types (regular, lazy, isolated, etc.). It manages the lifecycle of the underlying Hive box, provides thread-safe access via locks, and supports custom logging.

Type Parameters:

  • K: The type of the keys used in the box.
  • T: The type of the values stored in the box.
  • B: The concrete type of the underlying Hive box (e.g., Box, LazyBox, etc.).

Features:

  • Ensures the box is initialized before any operation.
  • Provides thread-safe read/write operations using Lock.
  • Supports custom logging via LogHandler.
  • Implements common query, iteration, and utility methods.
  • Handles error propagation and debug logging.
  • Used as the foundation for all HivezBox variants.

Example:

class MyBox extends BaseHivezBox<String, MyModel, Box<MyModel>> { ... }
Inheritance
Implementers
Available extensions

Constructors

BaseHivezBox(String name, {HiveCipher? encryptionCipher, bool crashRecovery = true, String? path, String? collection, LogHandler? logger, BoxType type = BoxType.regular})
Creates a new BaseHivezBox instance.

Properties

boxType → BoxType
The type of the native Hive box managed by this class.
no setter
hashCode → int
The hash code for this object.
no setterinherited
isEmpty → Future<bool>
Returns true if the box contains no elements.
no setter
isInitialized → bool
Whether the box has been initialized and is ready for operations.
no setter
isIsolated → bool
Whether this box is running in an isolated (background) context.
no setter
isLazy → bool
Whether this box is a lazy box (values loaded on demand).
no setter
isNotEmpty → Future<bool>
Returns true if the box contains at least one element.
no setter
isOpen → bool
Whether the underlying Hive box is currently open.
no setter
length → Future<int>
The number of key-value pairs in the box.
no setter
name → String
finalinherited
path → String?
The resolved storage path for this box, if set.
no setter
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).
addAll(Iterable<T> values) → Future<Iterable<int>>
Adds multiple values to the box using auto-incremented keys (if supported).
clear() → Future<void>
Removes all key-value pairs from the box.
closeBox() → Future<void>
Closes the box, releasing all resources.
compactBox() → Future<void>
Compacts the box, removing unused space.
containsKey(K key) → Future<bool>
Returns true if the box contains the given key.
delete(K key) → Future<void>
Deletes the value associated with the given key.
deleteAll(Iterable<K> keys) → Future<void>
Deletes the values associated with the given keys.
deleteAt(int index) → Future<void>
Deletes the value at the specified index.
deleteFromDisk() → Future<void>
Deletes the box from disk.
ensureInitialized() → Future<void>
Ensures the box is initialized and ready for use.
override
estimateSizeBytes() → Future<int>
Returns approximate in-memory size (in bytes) of the entire box content.
firstKeyWhere(bool condition(K key, T value)) → Future<K?>
Returns the first key for the given condition.
firstValueWhere(bool condition(K key, T value)) → Future<T?>
Returns the first value for the given condition.
firstWhereContains(String query, {required String searchableText(T item)}) → Future<T?>
Returns the first value whose searchableText contains query, or null.
firstWhereOrNull(bool condition(T item)) → Future<T?>
Returns the first value matching condition, or null if none found.
flushBox() → Future<void>
Flushes any pending changes to disk.
foreachKey(Future<void> action(K key), {bool breakCondition()?}) → Future<void>
Iterates asynchronously over all keys, invoking action for each.
foreachValue(Future<void> action(K key, T value), {bool breakCondition()?}) → Future<void>
Iterates asynchronously over all key-value pairs, invoking action for each.
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.
getAllKeys() → Future<Iterable<K>>
Returns all keys in the box.
getAllValues() → Future<Iterable<T>>
Returns all values in the box.
getAt(int index) → Future<T?>
Returns the value at the specified index, or null if not found.
getKeysWhere(bool condition(K key, T value)) → Future<List<K>>
Returns the keys for the given condition.
getMany(Iterable<K> keys) → Future<List<T>>
Returns the values for the given keys.
getValuesWhere(bool condition(T item)) → Future<List<T>>
Returns the values for the given condition.
keyAt(int index) → Future<K?>
Returns the key at the specified index. or null if not found.
moveKey(K oldKey, K newKey) → Future<bool>
Moves the value from oldKey to newKey, replacing any existing value.
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.
putAll(Map<K, T> entries) → Future<void>
Inserts multiple key-value pairs into the box.
putAt(int index, T value) → Future<void>
Inserts a new key-value pair into the box at the specified index.
replaceAll(Map<K, T> entries) → Future<void>
Replaces all data in the box with the given entries.
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.
toMap() → Future<Map<K, T>>
Returns a map containing all key-value pairs in the box.
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.
override
watch(K key) → Stream<BoxEvent>
Watches for changes to the value associated with key.

Operators

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