IndexedBox<K, T> class

A Box implementation that provides full-text search and secondary indexing.

IndexedBox maintains a secondary index for fast text search and token-based lookups. It automatically keeps the index in sync with the main data, and supports rebuilding the index if the schema or data changes out-of-band.

Type parameters:

  • K: The key type (e.g., int, String).
  • T: The value type (your data model).

Example usage:

final box = IndexedBox<int, MyModel>(
  'myBox',
  searchableText: (m) => m.title,
);
final results = await box.search('query');
Inheritance
Available extensions

Constructors

IndexedBox(String name, {required String searchableText(T), BoxType type = BoxType.regular, Analyzer analyzer = Analyzer.prefix, HiveCipher? encryptionCipher, bool crashRecovery = true, String? path, String? collection, LogHandler? logger, bool matchAllTokens = true, int tokenCacheCapacity = 512, bool verifyMatches = false, int keyComparator(K a, K b)?, TextAnalyzer<T>? overrideAnalyzer})
Creates an IndexedBox with the given configuration.
IndexedBox.fromConfig(BoxConfig config, {Analyzer analyzer = Analyzer.prefix, required String searchableText(T), TextAnalyzer<T>? overrideAnalyzer, bool matchAllTokens = true, int tokenCacheCapacity = 512, bool verifyMatches = false, int keyComparator(K a, K b)?})
Creates an IndexedBox from a BoxConfig.
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 setter
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 setter
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
logger → LogHandler?
Optional logger for capturing diagnostic and error information.
finalinherited
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 and returns its generated key, updating the index.
addAll(Iterable<T> values) → Future<Iterable<int>>
Adds multiple values, updating the index.
clear() → Future<void>
Clears all values and index data.
closeBox() → Future<void>
Closes the box and all associated index/journal resources.
compactBox() → Future<void>
Compacts the box and its index/journal to reclaim disk space.
containsKey(K key) → Future<bool>
Returns true if the box contains the given key.
inherited
countMatching(String query) → Future<int>
Counts the number of values matching the query without fetching them.
delete(K key) → Future<void>
Deletes the value for the given key, updating the index.
deleteAll(Iterable<K> keys) → Future<void>
Deletes all values for the given keys, updating the index.
deleteAt(int index) → Future<void>
Deletes the value at the given index, updating the index.
deleteFromDisk() → Future<void>
Deletes the box and all index/journal data from disk.
ensureInitialized() → Future<void>
Ensures the box, index, and journal are initialized and up-to-date.
estimateSizeBytes() → Future<int>
Estimates the total size in bytes of the box, index, and journal.
firstKeyWhere(bool condition(K key, T value)) → Future<K?>
Returns the first key for the given condition.
inherited
firstMatchOrNull(String query) → Future<T?>
Returns the first value matching query, or null if none.
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 searchableText contains query, or null.
inherited
firstWhereOrNull(bool condition(T)) → Future<T?>
Returns the first value matching condition, or null if none found.
inherited
flushBox() → Future<void>
Flushes all data and index changes to disk.
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, T), {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)) → 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
markIndexDirty() → Future<void>
Marks the index as dirty to trigger rebuild on next init.
moveKey(K oldKey, K newKey) → Future<bool>
Moves a value from oldKey to newKey, updating the index.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
put(K key, T value) → Future<void>
Inserts or updates a value for the given key, updating the index.
putAll(Map<K, T> entries) → Future<void>
Inserts or updates multiple entries, updating the index.
putAt(int index, T value) → Future<void>
Updates the value at the given index, updating the index.
rebuildIndex({bool bypassInit = true}) → Future<void>
Rebuilds the entire index from the current box contents.
replaceAll(Map<K, T> entries) → Future<void>
Replaces all data in the box with the given entries.
resetRuntimeState() → Future<void>
Clears runtime caches and resets the journal.
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.
Searches for values matching the query string.

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.
searchFiltered(String query, {bool filter(T value)?, int sortBy(T a, T b)?, int? limit, int offset = 0}) → Future<List<T>>

Available on IndexedBox<K, T>, provided by the IndexedBoxSearchExtensions extension

Performs a full-text search with optional filtering and sorting.
searchKeyOf(T value) → Future<K?>
Returns the key for the given value, or null if not found.
inherited
searchKeys(String query, {int? limit, int offset = 0}) → Future<List<K>>
Searches for keys of values matching the query string.
searchKeysStream(String query) → Stream<K>
Returns a stream of keys matching the query string.
searchPaginated(String query, {bool filter(T value)?, int sortBy(T a, T b)?, int page = 0, int pageSize = 20, bool prePaginate = false}) → Future<List<T>>

Available on IndexedBox<K, T>, provided by the IndexedBoxSearchExtensions extension

Performs a full-text search with optional filtering, sorting, and pagination.
searchPairs(String query, {int? limit, int offset = 0}) → Future<Map<K, T>>
Returns key–value pairs matching the query.
searchStream(String query) → Stream<T>
Returns a stream of values matching the query string.
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.
valueAt(int index) → Future<T?>
Returns the value at the specified index, or null if 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.