cell #

Reactive state for Dart. A cell holds a value or relays a signal. A pulse is the immutable message that moves a change. Operators (Cell.state, Cell.observe, …) wire cells together.

Validation, deputies, provenance, and timing control are available when you need them. Defaults are pass-through and allow-all — you can ship a counter without learning Nucleus.

This is the foundation package of the Cell Framework (Mitosis). Sibling packages add collections, relations, stream combinators, persistence, and codegen.

When it fits #

Cell is a good match if you want:

• Persistent reactive state with an explicit update path
• Events (clicks, sockets, sensors) entering the same graph as state
• Validation that is a gate, not a callback you remember to call
• Restricted views of the same data without copying it (deputy, unmodifiable)
• Multi-cell commits (transaction) or staged commands with undo (txApply)
• Debounce / throttle / batch as library behavior rather than ad-hoc Timers

It is more machinery than you need for a couple of flags, a basic form, or a single Future. For Rx-style combinators (merge, zip, scan, windows), use cell_flow.

Install #

The package is on pub.flutter-io.cn. From this monorepo:

dependencies:
  cell: ^1.0.0-rc.4

From git:

dependencies:
  cell:
    git:
      url: https://github.com/simon-m-lee/cell.git
      path: packages/cell

Requires Dart >=3.5.0 <4.0.0.

import 'package:cell/cell.dart';

Quick example #

import 'package:cell/cell.dart';

void main() {
  final counter = Cell.state<int>(
    initial: 0,
    evolve: (host, input) {
      final delta = input.payload as int? ?? 1;
      return Pulse(host.value + delta);
    },
  );

  final observer = Cell.observe(
    source: counter.cell,
    effect: (pulse) => print('Counter: ${pulse.payload}'),
  );

  counter.update(5); // prints: Counter: 5
  observer.stop();
}

evolve returning null rejects the update. Omit evolve to treat update as a direct assignment.

Runnable demos live in example/. Start with example/state_demo.dart.

Core operators #

You can build most application graphs from these factories. None of them require configuring Receptor, TestCell, Context, or Synapses.

Also implemented, outside that numbered set: Cell.valve (predicate gate). Fan-in of several sources is Cell.synthesis (or combinators in cell_flow).

Learning order: get data in → hold state → react → shape streams → go async → combine → isolate writes. Operators 1–4 are enough for a first app.

How much you need to know #

Layers are optional, not a reading list.

1. Operators — intended default for application code.
2. Pipelines and propagation — custom Receptor / Instruction, and Synapses + PropagationPolicy, when a factory’s default is not enough.
3. Validation and authority — TestCell and Context. Off by default (TestCell.allowAll, Context.system).
4. Internals — Nucleus, Cell.governed, Cell.fromNucleus, lifecycle policies. For extending the framework or high-integrity nodes.

A deputy is a proxy, not a copy: cell == cell.deputy() is true. Rules on a deputy can only narrow what the principal already allows.

See ARCHITECTURE.md for the design rationale.

Documentation #

Guides use HowTo-*.md (hyphens). Generate API docs with dart doc . and open doc/api/index.html.

If a guide and the source disagree, the source is current.

Ecosystem #

Flutter has no dedicated widgets here. Bind with Cell.observe (or an adapter) and drive setState or your existing state library.

Status #

RC (Mitosis 1.0.0-rc.4, Release Candidate). Public APIs for cells, pulses, operators, and transactions are exercised by a passing unit-test suite. Breaking changes remain possible before a versioned 1.0 stable.

A fuller developer list is in KNOWN_ISSUES.md. Known limits, so this page does not over-promise:

• Published to pub.flutter-io.cn.
• Context, PulseContext, and Sensitivity let you attach classification, actor, and purpose. They do not implement or certify GDPR, HIPAA, PCI-DSS, or any other regulation. Context.describe('…') stores text; it is not a legal basis or an audit log.

Feedback and issues are useful at this stage.

dart analyze lib
# Files are test_*.dart — bare `dart test` finds nothing. See TEST_VERIFICATION.md.
dart test @(Get-ChildItem test/test_*.dart | ForEach-Object { "test/$($_.Name)" })
dart format .
dart doc .

License #

MIT or Apache-2.0. See LICENSE.

Authors #

Lee Man Hoi Simon. See AUTHORS for copyright holders.