easy_state_m 1.2.1

Easy State Framework is a lightweight, high-performance, strongly-typed state management micro-framework for Flutter.

easy_state_m

A lightweight, performance-optimized state management framework for Flutter.

English | 中文

---

English

Overview

easy_state_m is built around three ideas:

1. Localized state — each feature owns its state in an EasyController, scoped to a widget subtree via EasyScope. No global singletons, no accidental cross-feature pollution.
2. Surgical UI refresh — EasyConsumer widgets subscribe directly to a synchronous notifier. Pass an id to rebuild only the exact widget that changed, leaving everything else untouched.
3. Typed cross-controller messaging — sibling scopes communicate through named channels. The sender specifies the target controller type as a generic parameter; the channel bus routes the message with O(1) HashMap lookups. No shared state, no tight coupling.

---

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                           Widget Tree                                │
│                                                                      │
│  EasyMultiScope                                                      │
│  ├─ EasyScope<AuthController>   (owned — manages lifecycle)          │
│  └─ EasyScope<CartController>   (shared — external lifecycle)        │
│         │                              │                             │
│         │  InheritedWidget lookup      │  refresh(ids: ['badge'])    │
│         ▼                              │  (synchronous, zero alloc)  │
│  EasyConsumer<CartController>          │                             │
│  id: 'badge'  ◄────────────────────────┘                            │
└──────────────────────────────────────────────────────────────────────┘
                         ▲
      emit<CartController>('item_added', product)
      (@protected — only callable from EasyController subclasses)
                         │
         ┌───────────────┴────────────────┐
         │        ProductController        │
         │        (EasyController)         │
         └───────────────┬────────────────┘
                         │
                         ▼
         ┌───────────────────────────────┐
         │          EasyChannel          │  Global channel bus
         │  (controllerType →            │  O(1) two-level HashMap
         │   channelName → handlers)     │  Type-namespaced routing
         └───────────────────────────────┘
                         │
                         ▼
         ┌───────────────────────────────┐
         │        CartController         │
         │  channelBindings:             │
         │  EasyChannelBinding<Product>  │
         │  ('item_added', _onItem)      │
         └───────────────────────────────┘

Data flow

Step	What happens
EasyScope mounts	Creates controller, calls initialize(), registers channel bindings
EasyConsumer mounts	Subscribes setState callback to _RefreshNotifier (synchronous, no Stream)
Controller calls refresh()	_RefreshNotifier dispatches callbacks in-place — setState fires in the same call stack
Controller calls emit<C>(channel, data)	EasyChannel routes to all C instances that declared a binding for that channel
EasyScope unmounts	Calls dispose(), unregisters channel bindings, cancels debounce timers

---

Performance Notes

Local refresh — zero allocation on the hot path

_RefreshNotifier uses an iteration-depth + null-mark strategy (modelled after Flutter's own ChangeNotifier):

• No List.of() copy is made on every notify() call.
• If a callback is removed during notification, the slot is null-marked and skipped inline.
• Compaction (removing null slots) runs once after the outermost notify returns.
• The common case — no structural changes during notification — is fully allocation-free.

Cross-controller messaging — O(1) routing

_ChannelBus uses a two-level HashMap:

controllerType  →  channelName  →  List<handler>

Dispatching a message requires exactly two HashMap lookups regardless of how many controllers or channels exist in the app. Unrelated controllers are never woken up.

---

Installation

dependencies:
  easy_state_m: ^1.2.1

---

Quick Start

1. Define a controller

class CounterController extends EasyController {
  int count = 0;

  void increment() {
    count++;
    refresh();                        // rebuilds all consumers
  }

  void incrementHeader() {
    count++;
    refresh(ids: ['header']);         // rebuilds only EasyConsumer(id: 'header')
  }

  void incrementDebounced() {
    count++;
    refresh(debounce: Duration(milliseconds: 16)); // coalesces rapid calls
  }
}

2. Provide it with EasyScope

EasyScope<CounterController>(
  create: () => CounterController(),   // owned — scope manages lifecycle
  builder: (context, controller) {
    return Scaffold(
      body: EasyConsumer<CounterController>(
        builder: (context, ctrl) => Text('${ctrl.count}'),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: controller.increment,
        child: const Icon(Icons.add),
      ),
    );
  },
);

3. Look up the controller anywhere in the subtree

// Throws if not found — use when the scope is guaranteed to exist.
final ctrl = EasyScope.of<CounterController>(context);

// Returns null if not found — use for optional dependencies.
final ctrl = EasyScope.maybeOf<CounterController>(context);

Async safety — store the controller reference before any await. After the async gap the widget may have unmounted and the context is no longer valid:

Future<void> load() async {
  final ctrl = EasyScope.of<MyController>(context); // before await ✓
  final data = await fetchData();
  ctrl.update(data);                                // no context needed ✓
}

---

Targeted Rebuild

Give each EasyConsumer a unique id and call refresh(ids: [...]) to rebuild only the matching widgets. All other consumers are untouched, no matter how many there are.

// Controller
void updateRow(int index) {
  items[index].value++;
  refresh(ids: ['row_$index']);   // only the tapped row rebuilds
}

// Widget
ListView.builder(
  itemBuilder: (context, index) => EasyConsumer<ListController>(
    id: 'row_$index',
    builder: (context, ctrl) => ListTile(title: Text('${ctrl.items[index].value}')),
  ),
);

---

Cross-Controller Messaging

Controllers in sibling scopes communicate through named channels. Channels are automatically namespaced by the target controller's runtimeType, so the same channel name in different controllers never collides.

// Receiver — CartController
class CartController extends EasyController {
  int itemCount = 0;

  @override
  List<EasyChannelBinding> get channelBindings => [
    EasyChannelBinding<String>('item_added', _onItemAdded),
  ];

  void _onItemAdded(String productName) {
    itemCount++;
    refresh();
  }
}

// Sender — ProductController (no import of CartController's internals)
class ProductController extends EasyController {
  void addToCart(String productName) {
    emit<CartController>('item_added', productName);
    //   ^^^^^^^^^^^^^^^ target type  ^^^^^^^^^^^^^ channel name
  }
}

Rules:

• Always specify the type parameter on EasyChannelBinding<T> and emit<C>. Omitting either triggers an AssertionError in debug mode.
• emit is @protected — only callable from within an EasyController subclass. This enforces the constraint that channels are strictly for controller-to-controller communication.

---

Multi-Scope Injection

Use EasyMultiScope to nest multiple scopes without deeply indented code. Entries are ordered outermost-first: entries[0] is the highest ancestor and is accessible to all controllers declared after it.

// main.dart
final authController = AuthController()..initialize();

EasyMultiScope(
  entries: [
    EasyScopeProvide.value(value: authController),   // shared — lifecycle managed externally
    EasyScopeProvide(create: () => ThemeController()), // owned — disposed with the scope
  ],
  child: const MyApp(),
);

---

Shared Scope

Use EasyScope.value to inject an already-initialized controller across Navigator barriers or into children that should not own the lifecycle.

// Parent creates and owns the controller.
final controller = MyController()..initialize();

// Pass it into a new route.
Navigator.of(context).push(MaterialPageRoute(
  builder: (_) => EasyScope<MyController>.value(
    value: controller,
    child: const ChildPage(),
  ),
));

EasyScope.value does not call dispose() when unmounted.

---

Testing

Replace the channel bus with a mock in setUp and restore it in tearDown:

class MockChannelBus implements EasyChannelBus {
  final List<String> log = [];

  @override void listen(Type ct, String ch, void Function(dynamic) h) {}
  @override void cancel(Type ct, String ch, void Function(dynamic) h) {}
  @override void emit(Type t, String ch, dynamic d) => log.add('$t/$ch/$d');
  @override void dispose() {}
}

setUp(() => EasyChannel.override(MockChannelBus()));
tearDown(() => EasyChannel.reset());

---

API Reference

Class	Role
EasyController	Base class for business logic. Override channelBindings, call refresh() and emit<C>().
EasyScope<T>	Provides T to a widget subtree via InheritedWidget. Owns or shares the lifecycle.
EasyConsumer<T>	Rebuilds when the controller calls refresh(). Optionally scoped by id.
EasyMultiScope	Nests multiple EasyScope instances without deep indentation.
EasyScopeProvide<T>	An EasyMultiScope entry. Use .value(value: ...) for shared instances.
EasyChannelBinding<T>	Declares a channel subscription with a typed payload.
EasyChannelBus	Abstract interface for the channel bus. Implement to provide test doubles.
EasyChannel	Global registry. Use override / reset in tests.

---

Common Pitfalls

Mistake	What happens	Fix
Nesting two EasyScope<T> of the same type	FlutterError thrown in debug mode	Make scopes siblings, or subclass T
Omitting <T> on EasyChannelBinding	AssertionError in debug mode	EasyChannelBinding<MyType>(...)
Omitting <C> on emit	AssertionError in debug mode	emit<TargetController>(...)
Injecting an uninitialized shared controller	AssertionError in debug mode	Call initialize() before passing to EasyScope.value
Calling EasyScope.of(context) after await	Potential context invalidation	Store the controller before the async gap

---

License

MIT

---

---

中文

概述

easy_state_m 围绕三个核心思想构建：

1. 状态局部化 — 每个功能模块的状态收敛到一个 EasyController，通过 EasyScope 挂载到 Widget 子树。没有全局单例，没有跨模块意外污染。
2. 精准 UI 刷新 — EasyConsumer 直接订阅同步通知器。传入 id 可只重建那一个 Widget，其余所有组件保持静止。
3. 类型化跨控制器通信 — 平级 Scope 之间通过命名频道通信。发送方用泛型参数指定目标 Controller 类型，Channel Bus 以 O(1) 的 HashMap 查找完成路由。无共享状态，无紧耦合。

---

架构图

┌──────────────────────────────────────────────────────────────────────┐
│                           Widget Tree                                │
│                                                                      │
│  EasyMultiScope                                                      │
│  ├─ EasyScope<AuthController>   (owned — 管理生命周期)                │
│  └─ EasyScope<CartController>   (shared — 外部管理生命周期)            │
│         │                              │                             │
│         │  InheritedWidget 查找         │  refresh(ids: ['badge'])   │
│         ▼                              │  (同步派发，零分配)           │
│  EasyConsumer<CartController>          │                             │
│  id: 'badge'  ◄────────────────────────┘                            │
└──────────────────────────────────────────────────────────────────────┘
                         ▲
      emit<CartController>('item_added', product)
      (@protected — 只能在 EasyController 子类内部调用)
                         │
         ┌───────────────┴────────────────┐
         │        ProductController        │
         │        (EasyController)         │
         └───────────────┬────────────────┘
                         │
                         ▼
         ┌───────────────────────────────┐
         │          EasyChannel          │  全局频道总线
         │  (controllerType →            │  O(1) 双层 HashMap
         │   channelName → handlers)     │  类型自动命名空间
         └───────────────────────────────┘
                         │
                         ▼
         ┌───────────────────────────────┐
         │        CartController         │
         │  channelBindings:             │
         │  EasyChannelBinding<Product>  │
         │  ('item_added', _onItem)      │
         └───────────────────────────────┘

数据流

步骤	发生了什么
EasyScope 挂载	创建 Controller，调用 initialize()，注册频道绑定
EasyConsumer 挂载	将 setState 回调订阅到 _RefreshNotifier（同步，无 Stream）
Controller 调用 refresh()	_RefreshNotifier 就地派发回调，setState 在同一调用栈内触发
Controller 调用 emit<C>(channel, data)	EasyChannel 路由到所有声明了该频道绑定的 C 实例
EasyScope 卸载	调用 dispose()，注销频道绑定，取消去抖 Timer

---

性能说明

本地刷新 — 热路径零分配

_RefreshNotifier 采用 迭代深度计数 + null 标记策略（参考 Flutter 内置 ChangeNotifier）：

• notify() 不再每次调用 List.of() 创建副本。
• 通知过程中若有回调被移除，对应槽位标为 null，迭代时跳过。
• 紧凑化（清理 null 槽）在最外层 notify 返回后统一执行。
• 正常路径（通知期间无结构变更）完全零分配。

跨控制器通信 — O(1) 路由

_ChannelBus 采用双层 HashMap：

controllerType  →  channelName  →  List<handler>

派发一条消息只需恰好两次 HashMap 查找，与应用中 Controller 的数量、频道数量无关。无关 Controller 完全不被唤醒。

---

安装

dependencies:
  easy_state_m: ^1.2.1

---

快速上手

1. 定义 Controller

class CounterController extends EasyController {
  int count = 0;

  void increment() {
    count++;
    refresh();                         // 刷新所有消费者
  }

  void incrementHeader() {
    count++;
    refresh(ids: ['header']);          // 只刷新 EasyConsumer(id: 'header')
  }

  void incrementDebounced() {
    count++;
    refresh(debounce: Duration(milliseconds: 16)); // 合并高频调用
  }
}

2. 用 EasyScope 提供 Controller

EasyScope<CounterController>(
  create: () => CounterController(),   // owned — Scope 管理生命周期
  builder: (context, controller) {
    return Scaffold(
      body: EasyConsumer<CounterController>(
        builder: (context, ctrl) => Text('计数: ${ctrl.count}'),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: controller.increment,
        child: const Icon(Icons.add),
      ),
    );
  },
);

3. 在子树任意位置查找 Controller

// 找不到时抛出 FlutterError（适用于有保证的子树内）
final ctrl = EasyScope.of<CounterController>(context);

// 找不到时返回 null（适用于可选依赖）
final ctrl = EasyScope.maybeOf<CounterController>(context);

异步安全 — 在任何 await 之前存储 Controller 引用。异步间隙之后 Widget 可能已卸载，context 不再有效：

Future<void> load() async {
  final ctrl = EasyScope.of<MyController>(context); // await 之前 ✓
  final data = await fetchData();
  ctrl.update(data);                                // 不再依赖 context ✓
}

---

精准局部刷新

给每个 EasyConsumer 设置唯一 id，配合 refresh(ids: [...]) 只重建匹配的 Widget，无论页面上有多少个 Consumer，其余全部静止不动。

// Controller
void updateRow(int index) {
  items[index].value++;
  refresh(ids: ['row_$index']);   // 只有被点击的那一行重建
}

// Widget
ListView.builder(
  itemBuilder: (context, index) => EasyConsumer<ListController>(
    id: 'row_$index',
    builder: (context, ctrl) => ListTile(
      title: Text('${ctrl.items[index].value}'),
    ),
  ),
);

---

跨控制器通信（Channel）

平级 Scope 下的 Controller 通过命名频道通信。频道以目标 Controller 的 runtimeType 为命名空间自动隔离，不同 Controller 中的同名频道绝不互相干扰。

// 接收方 — CartController
class CartController extends EasyController {
  int itemCount = 0;

  @override
  List<EasyChannelBinding> get channelBindings => [
    EasyChannelBinding<String>('item_added', _onItemAdded),
  ];

  void _onItemAdded(String productName) {
    itemCount++;
    refresh();
  }
}

// 发送方 — ProductController（无需 import CartController 内部实现）
class ProductController extends EasyController {
  void addToCart(String productName) {
    emit<CartController>('item_added', productName);
    //   ^^^^^^^^^^^^^^  目标类型     ^^^^^^^^^^^^^ 频道名
  }
}

使用规则：

• EasyChannelBinding<T> 和 emit<C> 都必须显式指定泛型。省略任一个都会在 Debug 模式下触发 AssertionError。
• emit 是 @protected 方法，只能在 EasyController 子类内部调用，框架层面强制约束"频道只用于 Controller 之间通信"。

---

多 Scope 注入

用 EasyMultiScope 嵌套多个 Scope，避免深层缩进。entries 按由外到内顺序排列：entries[0] 是最外层祖先，可被所有后续 Controller 访问。

// main.dart
final authController = AuthController()..initialize();

EasyMultiScope(
  entries: [
    EasyScopeProvide.value(value: authController),    // shared — 外部管理生命周期
    EasyScopeProvide(create: () => ThemeController()), // owned  — 随 Scope 销毁
  ],
  child: const MyApp(),
);

---

共享 Scope

跨路由共享同一个 Controller 实例时，用 EasyScope.value 注入，Scope 卸载时不会调用 dispose()。

// 外部创建并持有 Controller
final controller = MyController()..initialize();

// 注入到新路由
Navigator.of(context).push(MaterialPageRoute(
  builder: (_) => EasyScope<MyController>.value(
    value: controller,
    child: const ChildPage(),
  ),
));

---

测试

在 setUp 中替换 Channel Bus，在 tearDown 中还原：

class MockChannelBus implements EasyChannelBus {
  final List<String> log = [];

  @override void listen(Type ct, String ch, void Function(dynamic) h) {}
  @override void cancel(Type ct, String ch, void Function(dynamic) h) {}
  @override void emit(Type t, String ch, dynamic d) => log.add('$t/$ch/$d');
  @override void dispose() {}
}

setUp(() => EasyChannel.override(MockChannelBus()));
tearDown(() => EasyChannel.reset());

---

API 一览

类	职责
EasyController	业务逻辑基类。覆写 channelBindings，调用 refresh() 和 emit<C>()。
EasyScope<T>	通过 InheritedWidget 向子树提供 T。支持 owned / shared 两种模式。
EasyConsumer<T>	Controller 调用 refresh() 时重建。可通过 id 限定为精准刷新。
EasyMultiScope	无嵌套缩进地注入多个 EasyScope。
EasyScopeProvide<T>	EasyMultiScope 的条目。.value(value: ...) 用于共享实例。
EasyChannelBinding<T>	声明一个带类型载荷的频道订阅。
EasyChannelBus	频道总线抽象接口，实现它以提供测试替身。
EasyChannel	全局注册表。测试中用 override / reset 替换实现。

---

常见错误

错误	后果	修正
嵌套两个同类型 EasyScope<T>	Debug 模式抛出 FlutterError	改为兄弟节点，或将 T 子类化
EasyChannelBinding 省略 <T>	Debug 模式抛出 AssertionError	显式写 EasyChannelBinding<MyType>(...)
emit 省略 <C>	Debug 模式抛出 AssertionError	显式写 emit<TargetController>(...)
注入未初始化的共享 Controller	Debug 模式抛出 AssertionError	传入前调用 initialize()
await 后调用 EasyScope.of(context)	context 可能已失效	在 await 之前存储 Controller 引用

---

开源协议

MIT