cell
Install and import
dart pub add cell cell_flow cell_tissue
import 'package:cell/cell.dart'; // Cell layer only
import 'package:cell_flow/cell_flow.dart'; // re-exports package:cell
import 'package:cell_tissue/cell_tissue.dart';
AI agents start here
Read this before opening any other page.
cell is designed with AI coding agents in mind. Every top public symbol
carries a machine-readable ### AI Agent Guide block, and the surfaces below
let an agent reliably pick the right factory and generate code that compiles
against the live API.
- Version pin:
cell 1.1.0,cell_flow 1.0.0,cell_tissue 1.0.0. - Preflight:
dart run tool/ai_preflight.dart— prints the resolved versions and any stale pins. - API chooser:
lib/doc/api_chooser.dart(generated from the### AI Agent Guidedoc blocks). - Layer guides:
guide/HowTo-Mitose-Cell.md— Cell factory choicesguide/HowTo-Mitose-Flow.md— Flow operator choicesguide/HowTo-Mitose-Tissue.md— Tissue collection choices
- The seam sentence: The instruction decides, the chain assembles, the observer glues.
If you have a BRD sentence that says…
| BRD sentence | First factory | Do NOT |
|---|---|---|
| "capture X" / "record X entering" | Cell.ingress |
create a custom Cell |
| "record every Y" (history) | Cell.observe + TissueList |
put in instruction |
| "reserve N units" | TissueValue + invariant |
use Cell.state<int> |
| "flag when Y happens" | FlowInstructionBase subclass in Flow |
put in Cell.observe |
| "two facts move together" | Cell.txApply on Tissue |
Cell.transaction |
| "wait for silence" | Debounce in cell_flow |
roll your own Timer |
(The full matrix lives in lib/doc/api_chooser.dart; this is the 6-row elevator version.)
Reactive State for Dart — transaction-ready, observable, validated, synchronized, auditable, and zero-copy deputy-able cells, pulses, and operators. Plain Dart state, plus a governance contract.
This is the foundation package of the Cell Framework (Mitosis). Sibling packages add collections, relations, stream combinators, persistence, and codegen.
Mitose pipeline — the umbrella feature. The root repository ships an AI-executable pipeline that turns a business requirement into a working Cell + Flow + Tissue solution with its BRD, WalkThrough, Demo, ARCHITECTURE, and FEATURES documents. An AI prompt agent follows
guide/HowTo-Mitose.md; this package supplies the Cell layer rules viaguide/HowTo-Mitose-Cell.md. See the root README.
Overview
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 into a reactive graph — and that graph is governed:
- Transaction ready, built into the foundation —
Cell.txApply(staged commands with Saga compensation and rollback) andCell.transaction(buffered multi-cell atomic commits) are core factories of thecellpackage itself — an integral part of the reactive graph, not an add-on layer. Every mutation request is a first-class, auditable command (apply+ApplyCommand→ sealedApplyOutcome). Plain Dart state — and most reactive frameworks — have no equivalent: a multi-step update that throws halfway through leaves permanent, partial state; here it rolls back through recorded compensation. - Observable — every change emits a typed
Pulsethat downstream cells react to; plain Dart requires hand-rolled listener orStreamplumbing. - Validated — a
TestCellgate runs on every write, so validation is enforced by the framework instead of being anifyou remember to call. - Deputy-able — hand out zero-copy read-only views (
.unmodifiable) or restricted proxies (.deputy()); a deputy is the principal (cell == cell.deputy()istrue) and its rules can only narrow what the principal already allows. - Auditable —
ApplyReceiptforensics, causal trace, and provenance metadata ride every pulse;Cell.sanitizedredacts before egress. - Synchronized — transactional writes serialize through the ledger, and governed cells carry synchronization locks for high-integrity paths.
- Timing control —
debounce,throttle, anddistinctare library behavior, not ad-hocTimers. - Composable — 16 core operators cover state, events, projection,
fan-in, async mapping (
asyncMapwith concurrency control), routing (hub), and switching (switchMap);fromFuture/fromStreambridgedart:async. - Extensible —
Receptor/Instructiontransform pipelines,Synapses+PropagationPolicycontrol delivery,Contextcarries authority, andNucleus/Cell.governedunlock high-integrity nodes.
Where plain Dart gives you a field, cell gives you a field with a
governance contract:
| Capability | Plain Dart (setState / ValueNotifier / Stream) |
cell |
|---|---|---|
| Change notification | Manual listener or stream wiring | Built-in pulse graph — every change emits |
| Transactions | None — failures leave partial state | Built-in Cell.transaction / Cell.txApply: commands with compensation, atomic staging, and rollback |
| Validation | Manual if checks at call sites |
TestCell gate on every write |
| Restricted views | None, or copying the data | Zero-copy unmodifiable / deputy proxies |
| Audit trail | None | ApplyReceipt, causal trace, provenance |
| Timing operators | Hand-rolled Timers |
debounce / throttle / distinct |
| Async combinators | Hand-rolled Future/Stream plumbing |
asyncMap (concurrency/latest/exhaust), switchMap, fromFuture/fromStream |
| Multi-source aggregation | Manual bookkeeping | Cell.synthesis fan-in |
Transaction ready, in one breath:
final counter = Cell.state<int>(initial: 0); // One audited, compensable command: final outcome = await counter.cell.command(increment) .args([5]) .undo(decrement, args: [5]) .run(); // ApplyAccepted with a receipt — or ApplyRejected, never a throw // Stage commands with recorded compensation inside a transaction ledger: final tx = Cell.txApply(); await tx.execute(participants: [counter.cell], body: (scope) { counter.cell.apply<dynamic>( ( function: increment, arguments: (positionalArguments: [5], namedArguments: null), compensation: ( function: decrement, arguments: (positionalArguments: [5], namedArguments: null), cell: counter.cell, ), ), tx: scope, ); // buffered — invisible to readers until the transaction commits }); // Or buffer several cells into one atomic commit: final tx2 = Cell.transaction(); await tx2.begin([counter.cell, settings.cell]); tx2.update(counter.cell, 5); // buffered tx2.update(settings.cell, theme); // buffered await tx2.commit(); // both land together — or neither does
Defaults are pass-through and allow-all — you can ship a counter without
learning Nucleus. Validation, deputies, provenance, and timing control are
available when you need them.
Table of Contents
- Overview
- What's new in 1.1
- When it fits
- Install
- Quick example
- Core operators
- How much you need to know
- Documentation
- Ecosystem
- Status
- License
What's new in 1.1
Two headline changes shipped with the stable release.
Forensic Cell.apply
Every mutation request is now a first-class, auditable command — not a bag of positional parameters.
final outcome = await userCell.command(updateProfile)
.args(['Simon'])
.named({#active: true})
.undo(updateProfile, args: ['Original Name'])
.run();
switch (outcome) {
case ApplyAccepted(result: final user):
print('Update successful: ${user.name}');
case ApplyRejected(reason: final error):
print('Safety gate blocked the change: $error');
case ApplyStaged():
print('Staged in the transaction ledger');
}
apply<R>(ApplyCommand, {tx}) is the only gateway: sealed ApplyOutcome<R> results, ApplyReceipt forensics, the cell.command(...) builder DSL, vetted/trusted modifiable whitelists, and Saga compensation through Cell.txApply — with validation running through the deputy's full testRule chain. The complete list is in CHANGELOG.md.
Performance
Six optimization phases, tracked by a committed benchmark suite with a regression gate (benchmark/):
| Shape | Before | 1.1.0 |
|---|---|---|
Single-hop emit (ingress → observer) |
~170 µs | ~5–6 µs (~30×) |
Cell.distinct, duplicate-heavy |
~1.7 ms | ~8 µs (~210×) |
| Chain depth 50 | ~8.3 s (exponential) | ~12.7 ms (linear) |
Cell() construction |
~3.7 µs | ~2.1 µs |
Cell() heap footprint |
~2.7 KB | ~1.1 KB |
Run dart run benchmark/runner.dart --out current.json and compare against benchmark/baseline.json; the honest comparison story is feature-accounted in benchmark/README.md.
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 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.dev. From this monorepo:
dependencies:
cell: ^1.1.0 # stable
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 ?? 0) + delta);
},
);
final observer = Cell.observe(
source: counter.cell,
effect: (Pulse 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.
| Factory | Use when | |
|---|---|---|
| 1 | Cell.state |
Persistent mutable state |
| 2 | Cell.ingress |
Manual emit / ingest of external events |
| 3 | Cell.observe |
Side effects; start / stop |
| 4 | Cell.derive |
Pure projection of one source |
| 5 | Cell.debounce |
Emit after a silence window |
| 6 | Cell.distinct |
Skip equal consecutive payloads |
| 7 | Cell.throttle |
Cap emission frequency |
| 8 | Cell.synthesis |
Aggregate several sources |
| 9 | Cell.asyncMap |
Map each value to a Future (concurrency, latestOnly, exhaust) |
| 10 | Cell.hub |
Route by Pulse.type |
| 11 | Cell.switchMap |
Follow the latest inner cell |
| 12 | Cell.fromFuture / Cell.fromStream |
Bridge dart:async |
| 13 | Cell.sanitized |
Redact before egress |
| 14 | Cell.open |
Manual topology (emit / link) |
| 15 | Cell.transaction |
Multi-cell buffered writes |
| 16 | Cell.txApply |
Staged apply + compensation |
Also implemented, outside that numbered set: Cell.valve (predicate gate) and Cell.apply / cell.command(...) (audited mutations with receipts and Saga compensation). 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.
- Operators — intended default for application code.
- Pipelines and propagation — custom
Receptor/Instruction, andSynapses+PropagationPolicy, when a factory’s default is not enough. - Validation and authority —
TestCellandContext. Off by default (TestCell.allowAll,Context.system). - 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
| Document | What it is |
|---|---|
| HowTo-Start.md | Walkthrough of the core concepts |
| HowTo-16_Essential_Operators.md | Operator reference and learning path |
| FEATURES.md | Source-checked feature catalog |
| ARCHITECTURE.md | Why the pieces are shaped this way |
| TEST_VERIFICATION.md | Unit-test inventory, measured coverage, and how to run the suite |
| HowTo-TestCell.md | Validation rules |
| HowTo-Synapses.md | Linking, filters, propagation |
| HowTo-Receptor.md | Transformation pipelines |
| HowTo-Instruction.md | Instruction stages |
| HowTo-Transaction.md | Buffered multi-cell writes |
| HowTo-TransactionOnApply.md | Staged apply + compensation |
| HowTo-Advanced.md | Index of optional governance machinery |
| benchmark/README.md | Benchmark suite, pass criteria, and the feature-accounted comparison story |
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
| Package | Delivery | Adds |
|---|---|---|
| cell (this) | Now | Nodes, pulses, operators, governance, transactions |
| cell_flow | Now | 100+ instruction factories on Flow, plus fluent chaining (mapTo, asyncExpand, zip, …) |
| cell_tissue | Now | Reactive collections (list / map / set / queue) |
Flutter has no dedicated widgets here. Bind with Cell.observe (or an adapter) and drive setState or your existing state library.
Status
Stable on pub.dev (1.1.0). Public APIs for cells, pulses, operators, transactions, and the integrity-gated apply/txApply command model are exercised by a passing unit-test suite.
Release verification:
cell1174/1174,cell_flow1091/1091,cell_tissue362/362 unit tests pass.dart analyze libreports no issues; the test files carry a few pre-existing informational lints.dart doc .completes with zero warnings;doc/apiis generated.- The benchmark suite's 60 tracked results pass the 15% regression gate (
benchmark/compare.dart). Context,PulseContext, andSensitivitylet 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
dart test
dart format .
dart doc .
License
MIT or Apache-2.0. See LICENSE.
Authors
Lee Man Hoi Simon. See AUTHORS for copyright holders.