xray_hive_inspector 0.1.6

Database inspector for hive_ce boxes in xRay. Pure Dart — works with Flutter and Dart backends.

xray_hive_inspector

Browse and edit Hive boxes in the Database tab of the xRay inspector. Supports hive_ce; the original hive package is not supported, migrate to hive_ce first.

For full documentation and guides, see the xRay docs.

---

Disclaimer: This is a commercial package. To use this package, you need to have either a commercial xRay license or a free xRay Community License. The xRay desktop apps for macOS, Windows and Linux are the authorized UI clients for this library. For more details, please check the LICENSE file.

Setup

Pass the boxes your app already opened:

final settings = await Hive.openBox('settings');
final users = await Hive.openBox<User>('users');

XRayInspectorServerConfig(inspectors: [
  XRayHiveInspector(boxes: [settings, users]),
]);

Each box shows as a collection with a key and a value column. Search matches the key and the JSON of the value. Lazy boxes work too: only the values of the visible page are read, unless a search or a sort by value needs them all. Only the boxes you pass are listed, because Hive cannot list boxes without opening them. The inspector is titled Hive; pass title: to name it yourself, and id: when you register more than one.

Custom objects

Primitives, lists and maps show as JSON and can be edited. A custom object stored through a TypeAdapter shows in one of three ways, and you decide which one fits:

Your model has	xRay shows	Editable
An XRayHiveCodec registered	Its JSON, with field names	Yes
A toJson() method (most models written for an API do)	Its JSON, with field names	No
Neither	Its toString()	No

No setup is needed to see your objects: a model with a toJson() already shows its fields. Register a codec only for the types you want to edit from xRay:

XRayHiveInspector(
  boxes: [users],
  codecs: [
    XRayHiveCodec<User>(
      toJson: (user) => user.toJson(),
      fromJson: User.fromJson,
    ),
  ],
  allowWrites: true,
)

An edited value goes back through fromJson and is stored with your own TypeAdapter. When fromJson throws, the desktop app shows its message and the value is left as it was.

Why not just your TypeAdapter?

Your adapter is still what stores the object; xRay never replaces it. But an adapter writes fields as numbers (field 0, field 1, …): the names only exist in your source code, so xRay could show {"0": "Ada", "1": 36} at best. And hive_ce has no public way to find the adapter registered for a value. toJson() and fromJson speak in field names, which is what you want to read and edit.

Allowing edits

The inspector is read-only by default. Turn on adding, editing and deleting entries with allowWrites:

XRayHiveInspector(boxes: [settings, users], allowWrites: true)

• Edit replaces the whole value. It is decoded with the codec of the value it replaces, or kept as JSON for a primitive, list or map.
• Add takes an int or String key, or none to let Hive pick the next int key as box.add does. A key that exists is refused. A custom object is added through its codec's fromJson.
• Delete removes the selected keys.

One handle, the app's own

xRay never opens a box itself: a second handle on a box file would corrupt it. Its writes go through the put and delete of the boxes you pass, so box.watch() and ValueListenableBuilders fire as for the app's own writes.

Encrypted boxes

Boxes opened with an encryptionCipher work as is: xRay shows the decrypted values and its edits are encrypted by the box, like your app's. xRay never needs the key.