Skip to main content

cell 1.1.0 copy "cell: ^1.1.0" to clipboard
cell: ^1.1.0 copied to clipboard

Foundation layer of the Cell Framework — Cells, Nucleus, Context, Deputy Pattern, and Conactive execution with Causal Integrity.

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.

  1. Version pin: cell 1.1.0, cell_flow 1.0.0, cell_tissue 1.0.0.
  2. Preflight: dart run tool/ai_preflight.dart — prints the resolved versions and any stale pins.
  3. API chooser: lib/doc/api_chooser.dart (generated from the ### AI Agent Guide doc blocks).
  4. Layer guides:
    • guide/HowTo-Mitose-Cell.md — Cell factory choices
    • guide/HowTo-Mitose-Flow.md — Flow operator choices
    • guide/HowTo-Mitose-Tissue.md — Tissue collection choices
  5. 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.

Dart License Version Status

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 via guide/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) and Cell.transaction (buffered multi-cell atomic commits) are core factories of the cell package itself — an integral part of the reactive graph, not an add-on layer. Every mutation request is a first-class, auditable command (apply + ApplyCommand → sealed ApplyOutcome). 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 Pulse that downstream cells react to; plain Dart requires hand-rolled listener or Stream plumbing.
  • Validated — a TestCell gate runs on every write, so validation is enforced by the framework instead of being an if you 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() is true) and its rules can only narrow what the principal already allows.
  • Auditable — ApplyReceipt forensics, causal trace, and provenance metadata ride every pulse; Cell.sanitized redacts before egress.
  • Synchronized — transactional writes serialize through the ledger, and governed cells carry synchronization locks for high-integrity paths.
  • Timing control — debounce, throttle, and distinct are library behavior, not ad-hoc Timers.
  • Composable — 16 core operators cover state, events, projection, fan-in, async mapping (asyncMap with concurrency control), routing (hub), and switching (switchMap); fromFuture / fromStream bridge dart:async.
  • Extensible — Receptor / Instruction transform pipelines, Synapses + PropagationPolicy control delivery, Context carries authority, and Nucleus / Cell.governed unlock 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 #

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.

  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 #

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:

  • cell 1174/1174, cell_flow 1091/1091, cell_tissue 362/362 unit tests pass.
  • dart analyze lib reports no issues; the test files carry a few pre-existing informational lints.
  • dart doc . completes with zero warnings; doc/api is generated.
  • The benchmark suite's 60 tracked results pass the 15% regression gate (benchmark/compare.dart).
  • 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
dart test
dart format .
dart doc .

License #

MIT or Apache-2.0. See LICENSE.

Authors #

Lee Man Hoi Simon. See AUTHORS for copyright holders.

1
likes
160
points
1.15k
downloads

Documentation

Documentation
API reference

Publisher

verified publisheropencell.dev

Weekly Downloads

Foundation layer of the Cell Framework — Cells, Nucleus, Context, Deputy Pattern, and Conactive execution with Causal Integrity.

Homepage
Repository (GitHub)
View/report issues
Contributing

Topics

#state-management #reactive #concurrency #architecture #immutability

License

Apache-2.0, MIT (license)

Dependencies

meta, synchronized, uuid

More

Packages that depend on cell