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.

putAllBy is sugar for the common case where each value already carries its own key, so Map.fromIterables(values.map((v) => v.id), values) at the call site becomes putAllBy(values, key: (v) => v.id). It builds no intermediate map, which measures about 74 ns per entry cheaper (0.94x) than writing the map yourself. DualKeyBox takes the same shape with two extractors (primary: and secondary:), and ListBox has putAllGrouped, which collects a flat iterable into one stored list per key.

Keep putAll for everything else, and that is most cases: the key often isn't derivable from the value at all (primitives, values with no id, keys that come from a grid or a legacy key set), and on ListBox only putAll can store an empty list, since grouping never produces one.

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. ListBox restores the element type at the read boundary and stacks list helpers on top:

final tags = await ListBox.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.
• LazyListBox 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; Codec choice 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.

Some operations are cheap enough that one extra call frame doubles them while costing nothing that matters. A same-slot SingleValueBox.get is ~13 ns of raw hive, so the Option allocation and codec dispatch take it to ~24 ns: that is +89%, and it is also +11 ns. Walking an eager values iterable is +32% and +3 ns.

Quoting those percentages would be a lie by arithmetic, so the table gives nanoseconds wherever the underlying op is that cheap, and percentages only where the denominator is a real disk round-trip. benchmark/python/overhead.py enforces the same split, and refuses to stand behind a run whose median and minimum disagree.

Precision, honestly: repeated passes reproduce the bands above and the ordering, not two significant figures on any single lane. Treat each figure as an order of magnitude.

This surface takes (K1, K2) records, and there is one way to encode them that costs ~25x the others. Eight variants of the same two-part encode, each changing exactly one thing from the one above it:

Records are free. Generics are free. An extra adapter call frame is free. What costs ~350 ns is a record type built from a class's own type parameters, sitting in a checked parameter position: the subtype check resolves through the instantiated type-argument vector and misses AOT's inline subtype-test cache. Widening that parameter to Object and casting inside does not help, because it is the same check written out, and making the record type concrete hides the cost while leaving the trap armed for whoever re-parameterises it next.

So DualKeyBox encodes both parts as separate scalar arguments, which is the free side of that line. benchmark/key_shape_bench.dart prices every variant and its reader asserts each relationship, so this stays measured rather than remembered.

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 (ListBox 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.