🍯 Honeycomb #

English | 简体中文

Concise, type-safe, codegen-free state management library for Flutter.

Honeycomb provides clear separation between State and Effect semantics, automatic dependency tracking, and a powerful Scope/Override mechanism.

✨ Features #

• 🎯 No Codegen — Pure Dart, no build_runner required.
• 🔄 Auto Dependency Tracking — Computed automatically tracks dependencies from watch.
• 📡 State vs Effect — Clearly distinguish between replayable state and one-time events.
• 🎭 Scope/Override — Flexible dependency injection and local overrides.
• ⚡ Batch Updates — Reduce unnecessary rebuilds by batching changes.
• 🔒 Type Safe — Full generic support.
• 🧪 Easy to Test — Decouple state logic from UI for easy testing.

📦 Installation #

dependencies:
  honeycomb: ^1.0.0

flutter pub get

🚀 Quick Start #

1. Define State #

import 'package:aegis_honeycomb/honeycomb.dart';

// Read-write state
final counterState = StateRef(0);

// Derived state (auto dependency tracking)
final doubledCounter = Computed((watch) => watch(counterState) * 2);

// Async state
final userProfile = Computed.async((watch) async {
  final userId = watch(currentUserId);
  return await api.fetchUser(userId);
});

// One-time events
final toastEffect = Effect<String>();

2. Provide Container #

void main() {
  runApp(
    HoneycombScope(
      container: HoneycombContainer(),
      child: MyApp(),
    ),
  );
}

3. Use in UI #

class CounterPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return HoneycombConsumer(
      builder: (context, ref, child) {
        final count = ref.watch(counterState);
        final doubled = ref.watch(doubledCounter);

        return Column(
          children: [
            Text('Count: $count'),
            Text('Doubled: $doubled'),
            ElevatedButton(
              onPressed: () {
                final container = HoneycombScope.readOf(context);
                container.write(counterState, count + 1);
              },
              child: Text('Increment'),
            ),
          ],
        );
      },
    );
  }
}

📚 Documentation #

🎯 Core Concepts at a Glance #

State vs Effect #

// State: Replayable, always returns the latest value
final userName = StateRef('Guest');

// Effect: One-time event, no historical storage
final showToast = Effect<String>(strategy: EffectStrategy.drop);

Dependency Tracking #

final fullName = Computed((watch) {
  // Automatically tracks firstName and lastName
  return '${watch(firstName)} ${watch(lastName)}';
});
// fullName recalculates whenever firstName or lastName changes

Scope Override #

// Locally override state (e.g., for testing or theme switching)
HoneycombScope(
  overrides: [
    themeState.overrideWith(ThemeData.dark()),
  ],
  child: DarkModePage(),
)

🧪 Testing #

test('counter increments', () {
  final container = HoneycombContainer();
  
  expect(container.read(counterState), 0);
  
  container.write(counterState, 1);
  
  expect(container.read(counterState), 1);
  expect(container.read(doubledCounter), 2);
});

📊 Comparison #

🤝 Contributing #

Contributions are welcome! Please check CONTRIBUTING.md.

📄 License #

MIT License - See the LICENSE file.