phive_barrel

Ready-to-use PHive hooks package.

Use this package when you want common behaviors like TTL and encryption without writing your own hook classes.

Install

dependencies:
  phive_barrel: ^0.0.1

If you are in this monorepo:

dependencies:
  phive_barrel:
    path: ../phive_barrel

Common Hooks

• TTL(seconds)
• GCMEncrypted()
• AESEncrypted()
• UniversalEncrypted()

These hooks are designed to run inside generated PTypeAdapter<T> code produced by phive_generator.

Quick Start

import 'package:phive/phive.dart';
import 'package:phive_barrel/phive_barrel.dart';

@PHiveType(1)
class Session {
  @PHiveField(0)
  final String id;

  @PHiveField(1, hooks: [GCMEncrypted(), TTL(10)])
  final String token;

  const Session({required this.id, required this.token});
}

Then regenerate adapters with build_runner.

Hook Model

• hooks run through PHiveCtx
• model-level hooks declared on @PHiveType are merged with field-level hooks on @PHiveField
• whole-object hooks can be declared with classHooks and run once around the full model value
• classHooks persist shared metadata through a %PAR%...%PAR% class envelope before field payloads
• shared class metadata is merged into each field context without overwriting field-specific metadata
• encryption hooks may attach metadata such as nonces into the PHive payload envelope
• hooks declare read-side cleanup through PHiveActionException and PHiveActionBehavior
• routers remain responsible for applying storage side effects such as delete or clear

TTL Behavior

The built-in TTL hook detects expiry on read and throws a behavior-driven exception that requests:

• deleteEntry
• returnNull

This keeps expiry detection inside the hook while leaving storage mutation inside the router.

Encryption Seed Setup

Encryption hooks read their key material synchronously at hook runtime, so register and initialize the seed provider before encrypted reads or writes.

import 'package:phive_barrel/phive_barrel.dart';

Future<void> configurePhiveEncryption() async {
  PhiveMetaRegistry.registerSeedProvider(
    SecureStorageSeedProvider(
      seedIds: const ['session-token', 'profile-cache'],
    ),
  );
  await PhiveMetaRegistry.init();
}

Then point hooks at one of those preloaded seed ids:

@PHiveType(2)
class Session {
  @PHiveField(0)
  final String id;

  @PHiveField(1, hooks: [GCMEncrypted(seedId: 'session-token')])
  final String token;

  const Session({required this.id, required this.token});
}

If you use a custom seedId, include it in SecureStorageSeedProvider(seedIds: [...]) before calling PhiveMetaRegistry.init().

Nullable Fields

All barrel hooks are null-safe. TTL skips writing metadata when the field value is null so nullable fields (int?, bool?, etc.) round-trip correctly without payload corruption. Encryption hooks (GCMEncrypted, AESEncrypted, UniversalEncrypted) already skipped non-string values. No special annotation is needed; nullability is handled automatically.

Notes

• Hooks are designed to work with PHive-generated adapters.
• For a working dynamic-router and static-router example, see the monorepo example app.