Watch is typed on both axes: an eager delete event still carries the value that was removed; a lazy event carries an Option<T> that's None on deletes, because a lazy box holds no value to hand back.

Eager keeps every value in memory once the box opens, so reads are synchronous:

final todos = await KeyedBox.open<Todo, int>('todos').run();

await todos.put(1, Todo('write the README')).run();
final found = todos.get(1); // Option<Todo>

Lazy constructs synchronously and opens itself on the first effect. Values come off disk per read, so reads are effects too:

final archive = LazyKeyedBox<Todo, String>('archive');

await archive.put('2025-w1', Todo('ship 1.0')).run(); // first effect auto-opens
final found = await archive.get('2025-w1').run(); // TaskOption<Todo>
await archive.ensureInitialised().run(); // optional explicit warm-up

final session = await SingleValueBox.open<String>('session_token').run();

await session.set('abc123').run();
final token = session.get(); // Option<String>
await session.clear().run(); // the one unset; the next get() is None

session.watch().listen((token) => print(token)); // Some on set, None on clear

The value sits under a fixed internal slot, the same one 0.0.x single boxes used, so that data reads in place. LazySingleValueBox is the same surface on the lazy axis. update mirrors Map.update, and getOr(fallback) reads with a default.

Hive reads collections back as List<dynamic> no matter what you wrote (issue #150), so a plain Box<List<Person>> opens fine and then throws on the first read after a restart. IterableBox restores the element type at the read boundary and stacks list helpers on top:

final tags = await IterableBox.open<String, int>('post_tags').run();

await tags.put(1, ['flutter', 'dart']).run(); // any Iterable; stored as a private copy
await tags.add(1, 'hive').run(); // append; an absent key becomes [value]
await tags.remove(1, 'dart').run(); // first occurrence; an absent key is a no-op

final postTags = tags.getOr(1); // List<String>: unmodifiable view, empty when absent
final maybe = tags.get(1); // Option<List<String>>: None = absent, Some([]) = stored empty

Worth knowing:

• Lists you read out are unmodifiable views; lists you put in are copied. Mutating your original afterwards never leaks into the box. add / addAll / remove are read-modify-writes, O(n) in the stored list.
• Absent isn't the same as empty. get keeps them apart; getOr folds both to [] on purpose.
• List semantics only: order preserved, duplicates allowed. Sets, maps, and nested collections of custom types stay out (the read-boundary cast can't fix inner reification). Model richer shapes as adapter-registered value types instead.
• LazyIterableBox is the same surface on the lazy axis.

final events = await DualKeyBox.open<Event, int, int>('user_events').run();

await events.put(userId, dayIndex, event).run();

final one = events.get(userId, dayIndex); // Option<Event>: exact lookups stay O(1)
final usersWeek = events.queryByPrimary(userId); // List<Event>: everything for this user
final everyoneToday = events.queryBySecondary(dayIndex); // List<Event>: everyone, this day

Queries hand back a plain (possibly empty) list, and in 1.0 they're an honest O(K) scan over the live key set: free until you call one, exact when you do, documented instead of hidden. Where a whole key is needed (keys, putAll, watch events) it travels as a (primary, secondary) record. LazyDualKeyBox matches the surface on the lazy axis (queries return Task<List<T>>).

Both parts round-trip through one DualKeyCodec. (int, int) defaults to the safe StringCompositeDualCodec (full-range parts, negatives included, no ceilings). If both parts fit in 16 bits and the numbers matter to you, opt into PackedIntDualCodec (codec: const PackedIntDualCodec()). It packs both parts into a single u32 key and is bit-identical to the old 0.0.x .bitShift scheme, so those boxes read in place. The two codecs trade off measurably; Performance has the head-to-head. Rolling your own part types? Implement DualKeyCodec<K1, K2> and keep the encoding bijective, or reverse queries will lie to you.

int and String work out of the box. Anything else brings a codec:

final class DateKeyCodec implements KeyCodec<DateTime> {
  const DateKeyCodec();

  @override
  Object encode(DateTime key) => key.toIso8601String();

  @override
  DateTime decode(Object rawKey) => DateTime.parse(rawKey as String);
}

final byDay = await KeyedBox.open<Todo, DateTime>(
  'by_day',
  codec: const DateKeyCodec(),
).run();

encode has to produce an int in 0..0xFFFFFFFF or a String of at most 255 UTF-8 bytes. That's hive's raw key domain, and staying inside it is what keeps your data safe (more on that just below).

Pass an observer and you'll hear every semantic event. Pass none and dispatch costs nothing:

final todos = await KeyedBox.open<Todo, int>(
  'todos',
  observer: const PrintingBoxObserver(), // dart:developer log, DevTools-filterable
).run();

Extend BoxObserver and override only the events you care about; PrintingBoxObserver is the ready-made sink. Two notes on the engine side: hive_ce's own warnings stay on its global logging channel (its logging options filter them), and the Hive Inspector DevTools extension is handy for eyeballing box contents while your observer reports what the code did to them.

Additive candidates for 1.x, in no committed order:

• Indexed reverse queries for very large (>100K) datasets: an inverted-index strategy on LazyDualKeyBox, swapping out the O(K) scan behind the same query methods.
• IsolatedHive support behind the box-acquisition seam (hive_ce itself recommends it for multi-isolate apps), plus BoxCollection wrapping if there's demand.
• A migration helper API (1.0 documents recipes in MIGRATION.md for now).
• Sets, maps, and nested collections on the value-codec seam (IterableBox is list-only today).
• A consumer fakes package (in-memory façades for app tests) and Flutter companions (a ValueListenable adapter), as separate packages so the core stays pure Dart.

Deliberately never wrapped, because they fight the typed, codec-addressed key model: auto-increment add / addAll, index-based getAt / putAt / deleteAt / keyAt, toMap, and valuesBetween. Reach for a raw hive_ce box where those genuinely fit.