HakoBuildContextExtension extension

Extension methods on BuildContext for accessing and watching Hako state containers.

This extension provides the primary interface for interacting with Hako instances and their state values from within Flutter widgets. It offers three main capabilities:

Direct Access: Get a Hako instance to call methods without listening for changes using readHako.
Reactive Watching: Subscribe to state changes and automatically rebuild widgets when state values change using watchHakoState.
Filtered Watching: Subscribe to derived/transformed state values with granular rebuild control using filterHakoState.

Usage Patterns

Getting Hako Instances

Use readHako when you need to call methods on a Hako instance or access properties without triggering widget rebuilds:

// In a button's onPressed callback
onPressed: () {
  final counterHako = context.readHako<CounterHako>();
  counterHako.increment(); // Calls method without rebuilding this widget
}

Watching State Changes

Use watchHakoState to create reactive widgets that rebuild when specific state values change:

Widget build(BuildContext context) {
  // Widget rebuilds whenever the counter value changes
  final count = context.watchHakoState<CounterHako, int>();
  return Text('Count: $count');
}

For named state values:

Widget build(BuildContext context) {
  final theme = context.watchHakoState<SettingsHako, String>(name: 'theme');
  final volume = context.watchHakoState<SettingsHako, int>(name: 'volume');
  return Column(
    children: [
      Text('Theme: $theme'),
      Text('Volume: $volume'),
    ],
  );
}

Filtered State Watching

Use filterHakoState when you want to derive values from state and only rebuild when the derived value changes:

Widget build(BuildContext context) {
  // Only rebuilds when the "even/odd" status changes, not on every count change
  final isEven = context.filterHakoState<CounterHako, int, bool>(
    filter: (count) => count % 2 == 0,
  );
  return Text('Count is ${isEven ? 'even' : 'odd'}');
}

Performance Considerations

readHako does not create subscriptions and won't trigger rebuilds
watchHakoState uses hash-based comparison and may rebuild on reference changes even with identical content
filterHakoState uses content-based comparison and provides more granular rebuild control for derived values

Error Handling

All methods throw HakoProviderNotFoundException if no matching HakoProvider is found in the widget tree. watchHakoState and filterHakoState additionally throw ArgumentError if the requested state type and name combination hasn't been registered in the Hako instance.