testing library
Testing utilities for cell_flutter.
testing.dart is the binding's Test Surface — the barrel library
that exports every test helper the binding provides, plus the
application-facing surface (cell_flutter.dart) they build on. It is
the single import a test needs to pump, emit, record, and assert against
cells inside a testWidgets body.
Why it is used
Widget-testing a cell-backed widget has three recurring shapes, and this library covers each without hand-rolled scaffolding:
- Pumping: a widget needs a
CellScope(for lookups) or at least aMaterialApp+Scaffoldframe (for text and theme).pumpWithCellsandpumpCellassemble the correct tree with one call. - Emitting: writing
cell.value = ...does not trigger a render on its own;emitAndSettleandemitAndPumpcombine the write with the pumping needed to see the result. - Observing:
recordPulsescaptures the full pulse sequence, andexpectCellValue/expectCellGoldenassert on the current value or the rendered pixels.
CellTestHarness bundles all three for suites with several shared
cells, and takes care of recorder cleanup in tearDown.
Import from test files only
import 'package:cell_flutter/testing.dart';
import 'package:flutter_test/flutter_test.dart';
Requirement: test-only usage (read this)
cell_flutter/testing.dart imports package:flutter_test/flutter_test.dart.
cell_flutter declares flutter_test as a regular dependency — the
same pattern bloc_test, mocktail, and mockito use — so the import
resolves automatically. To keep flutter_test out of production
builds, add cell_flutter itself to your dev_dependencies:
dev_dependencies:
cell_flutter: ^0.4.0
Application code that imports package:cell_flutter/cell_flutter.dart
(not testing.dart) is unaffected; the flutter_test import never
enters the production graph.
What this library exports
Re-export:
package:cell_flutter/cell_flutter.dart— the entire application-facing surface (CellBuilder,CellSelector,CellValueBuilder,CellAsyncBuilder,CellListener,CellScope,CellNotifier,CellAsStream,CellAsValue, plus the corecellre-export). Test helpers are typically written against the same surface the production code uses, so this library re-exports it.
Widget pumping:
CellPumpWithCells.pumpWithCells— pumps a widget inside aCellScope, with an optional custom wrapper.CellPumpCell.pumpCell— pumps a bareCellBuilderin a defaultMaterialApp+Scaffoldframe.
Emission:
CellEmitAndSettle.emitAndSettle— writes the value and pumps until the tree settles.CellEmitAndSettle.emitAndPump— writes the value and pumps a single frame (or an explicitDuration), without waiting for settle.
Observation:
CellRecordPulses.recordPulses— records the ordered pulse sequence emitted by anyCell.PulseRecorder<T>— the recorder type; exposespulsesandpayloads.CellExpectValue.expectCellValue— asserts aValueCell's current value against a matcher.CellExpectGolden.expectCellGolden— captures a golden image of aCellBuilderat the cell's current value.
Fixture:
CellTestHarness— a per-test registry that owns recorders and bundles pumping + emission + cleanup.
Inherited caveats
The binding rests on cell's verified replay round-trip (commit
05b4895d). Concurrent asyncMap effect attribution is tracked
separately and is not claimed by this binding. recordPulses
records every pulse regardless of type; only Cell.fromFuture
currently emits error pulses in the core package — fromStream and
asyncMap do not. See record_pulses.dart for the full explanation.
See Also:
package:cell_flutter/cell_flutter.dart— the application-facing surface this library re-exports.package:cell_flutter/hooks.dart— the optionalflutter_hooksintegration, with its own hook equivalents for tests that useHookWidget.record_pulses.dart— the authoritative statement of per-source error-pulse behavior (overrides contradictory claims in other binding docs).test/error_pulse_sources_test.dart— the test file that locks in the per-source error-pulse behavior these docs describe.CellTestHarness— the higher-level fixture for multi-cell suites.
Classes
-
ApplyAccepted<
R> - The command was authorized, safety-checked, and successfully executed.
- ApplyCommandRunner
- A helper class used to set up and execute an action on a cell.
- ApplyLedger
- The framework's internal Record Keeper and receipt generator.
-
ApplyOutcome<
R> - The official, auditable result of submitting an ApplyCommand.
-
ApplyRejected<
R> - The command was denied by the framework's safety rules (the Integrity Gate).
- ApplyStaged
- The command was accepted and placed into a transaction to be run later.
- ApplyTransactionScope
- Handle for a staged command transaction — the mechanism behind Cell.txApply.
- ApplyVeto
- A special signal used by a function to cancel its own operation.
-
Async<
C> -
A foundational marker interface and architectural contract representing
an Asynchronous Proxy or Controller for a core component
C. -
AsyncPriorityQueue<
E> -
AsyncQueueList<
E> -
AsyncSynapses<
P extends Pulse, L extends Cell> - An Asynchronous Projection of a Synapses instance for non‑blocking signal distribution.
-
Box<
T> - A specialized, lightweight container used to provide a mutable state anchor within the framework's immutable Record architecture.
- Cell
- A reactive node: holds state (or relays signals), validates every incoming change against a policy, and broadcasts accepted changes to whatever else is listening.
-
CellAsyncBuilder<
V> - A widget that renders the asynchronous state of any Cell as an AsyncSnapshot<V>.
- CellBase
- The foundational abstract implementation of the Cell interface.
-
CellBuilder<
V> - A widget that rebuilds its builder whenever cell's value changes.
- CellEditingController
- A TextEditingController bound two-way to a ValueCell<String>.
- CellErrorBoundary
- Renders a fallback instead of Flutter's error screen when a cell-driven error is thrown while building the subtree below it.
- CellErrorBoundaryState
- The state behind CellErrorBoundary.
- CellFlutterDevTools
- The in-app Cell Inspector.
-
CellFormField<
T> - A FormField whose value is bound two-way to a ValueCell<T>.
- CellGraph
- A registered cell graph: the unit of identity and replay in the framework.
- CellGraphBuilder
- The entry point for constructing a CellGraph.
- CellGraphRegistry
- Public read-only access to the cell id registry.
- CellGraphSnapshot
- A serialisable snapshot of an entire cell graph.
- CellInspectorOverlay
- A floating in-app Cell Inspector panel.
-
CellListener<
V> - A widget that invokes onPulse for every pulse emitted by cell, without rebuilding its subtree.
-
CellListView<
T> - A virtualized list whose item collection is bound to a Cell.
-
CellNotifier<
V> - Adapts a ValueCell to Flutter's ValueNotifier contract as a read-only bridge.
- CellPulseRecord
- One recorded pulse, display-formatted.
- CellRegistry
- The live registry behind CellFlutterDevTools.
- CellRegistryEntry
- One registered cell and its journal.
- CellRestorationScope
- Provides a RestorationBucket to descendant RestorableCells and registers them automatically with Flutter's restoration protocol.
- CellRestorationScopeState
- The stateful, mixin-bearing half of CellRestorationScope.
- CellScope
- An InheritedWidget that provides a small set of app-level cells to the subtree below it, addressed by Symbol.
-
CellSelector<
V, S> - A widget that rebuilds its builder only when a selected slice of cell's value changes.
- CellSnapshot
- A serialisable projection of one cell's identity and current value.
- CellTestHarness
- A per-test Cell Registry that bundles the cells a test suite needs, tracks their pulse recorders, and disposes both in one call.
- CellTextField
- A TextFormField whose value is bound two-way to a ValueCell<String>.
-
CellValueBuilder<
V> - A widget that rebuilds its builder whenever any Cell emits a new value.
- ClockEffect
- A read of the system clock. Records the epoch millis.
-
CollectivePulse<
P> - A Collective Pulse — a flat bundle of independent pulses travelling together as a single atomic wave.
-
CollectivePulseBase<
P> - The abstract base class for CollectivePulse implementations.
- CompensationFailure
- Describes a single failed compensation attempt.
- Context
- Metadata describing a Cell's tier, domain, and operational boundaries — used by TestCell rules to make context-aware decisions.
- ContextBase
- The foundational implementation of the Operational Environment, providing the core logic for Prototype-based Inheritance and Ontological Resolution.
- ContextTranslator
- Bridges a DeputyContext across mandate schema versions.
- ContextTranslatorRegistry
-
A simple registry of translators keyed by
(from, to). - CycleChecker
- A specialized Traversal Guard and Topology Validator, responsible for preventing infinite recursion and ensuring the reactive graph remains a Directed Acyclic Graph (DAG) during signal propagation.
- DefaultValue
-
DefaultValue is a metadata annotation primarily used by the code generation
framework (such as
build_model) to define a fallback or initial value for fields in a model class. - DeputyContext
- Represents the Formal Mandate and declaration of intention for a Deputy.
- DivergenceReport
- A single point at which a replay diverged from its recording.
- EffectJournal
- The boundary between a receptor and the outside world.
- EffectRecord
- A single recorded non-deterministic observation.
- EmailPattern
- EmailPattern is a specialized EntryPattern metadata annotation designed to validate whether a string conforms to a standard email address format.
- EntryPattern
- EntryPattern is a specialized TestRule metadata annotation that validates whether a string input matches a specific Regular Expression (RegExp).
-
EphemeralPolicy<
C extends Cell> - Defines the Lifecycle Governance for transient reactive nodes.
-
EvolvedPulse<
P> - An immutable signal derived from a previous pulse through a transformation step — a causal link in the signal's journey.
-
EvolvedPulseBase<
P> - The abstract base class for EvolvedPulse implementations.
-
FilterRule<
P extends Pulse> - A filter that can transform, redact, or suppress a Pulse before it is broadcast to downstream observers.
-
FinalBox<
T> - A specialized, write-once container providing a thread-safe, immutable anchor for state that is initialized after construction.
- ForkHandle
- A forked history.
- ForkLedgerStore
- A LedgerStore wrapper that injects a synthetic ForkRecord entry at seq 0.
- ForkRecord
- The genesis record of a fork ledger.
- FunctionObject
- Simple wrapper for functions or records containing function information. Used to pass function metadata through the system.
-
FunctionTypeObject<
T> - Lazy-evaluated version of TypeObject that executes a function to get the value. Useful for deferred initialization or expensive object creation.
-
Governance<
V> - The foundational Authority Protocol for defining structural and behavioral guardrails within the framework's Mandate ontology.
-
GovernanceEntry<
G extends Governance< V> , V> - A strongly-typed key-value pair that represents a single dimension of governance within the framework's Scene-Driven Ontology.
- HashChain
- The rolling hash chain that binds ledger entries.
- Identity
- A utility for materializing unique identities within the somatic graph.
- Inheritable
- InMemoryLedgerStore
- An in-memory LedgerStore, suitable for tests and for ephemeral graphs whose ledger does not need to survive the process.
-
Instruction<
C extends Cell, I extends Pulse, O extends Pulse> - A discrete logic unit that defines how a Receptor reacts to a Pulse.
-
InstructionBase<
C extends Cell, I extends Pulse, O extends Pulse> - The foundational implementation and architectural base for all Instruction variants.
-
InstructionChain<
C extends Cell, I extends Pulse, O extends Pulse> - A composite Instruction that orchestrates a sequence of processing units.
- IoEffect
-
A single I/O call (network, disk, database). Records the label, the
request digest, and the response digest; the raw response is held
only if the caller supplied
rawOutput. For replay,rawOutputis required — the digest alone cannot reconstruct the response. - JournalScope
- The task-local stack of active journals.
- Ledger
- The durable, hash-chained record of every state transition.
- LedgerEntry
- A single, immutable row in the ledger.
- LedgerScope
- The graph-scoped ambient that coordinates state capture and ledger append.
- LedgerScopeImpl
- The per-graph implementation of the scope.
- LedgerStore
- The persistence backend for a Ledger.
- Lock
-
A mutual-exclusion lock: serializes access to a shared resource across
asynchronous code, similar to Java's
synchronized. - MaxLength
-
MaxLength is a specialized TestRule metadata annotation used primarily by
the code generation framework (such as
build_model) to enforce structural and data-integrity constraints on model fields. - Modifiable
- A specialized architectural marker and base interface for objects that support controlled mutation through the framework's dynamic command pattern.
-
ModifiableAsync<
C extends Cell> - Provides asynchronous execution of operations on a Cell.
- MultiLock
- A Lock that atomically acquires several other locks together.
- Nucleolus
- A specialized, terminal implementation of the Nucleus contract representing the framework's "zero-state" and Ontological Root.
- Nucleus
- The immutable blueprint underlying every Cell — its receptor, testRule, context, synapses, and lifecycle policy, stored separately from the live cell instance.
- NucleusBase
- The foundational base implementation of the Nucleus contract, providing a memory-optimized storage engine for reactive cell properties.
- NullJournal
- The "no journal in scope" sentinel. Every effectful operation fails loudly.
- OpenCell
- A specialized, interactive Cell that serves as a Reactive Bridge for external stimulus injection and dynamic topology management.
- OpenCellAsync
- Represents the Asynchronous Governance Interface for an OpenCell.
- PolicyReplay
- Policy-tick journaling for EphemeralPolicy.
- PolicyTickEffect
- A single tick of an EphemeralPolicy.
-
PriorityQueue<
E> - A collection of elements that maintains a Deterministic Priority Order, serving as a specialized Ranked Execution Buffer for the reactive fabric.
- PropagationPolicy
- A declarative blueprint defining the Temporal Dynamics and Operational Governance of pulse propagation.
-
Pulse<
P> - A reactive signal — the fundamental unit of communication in the framework.
-
PulseBase<
P> - The foundational blueprint for all nervous signals within the reactive graph.
- PulseCodec
- Canonical serialiser for Pulse.
- PulseContext
- Represents the Causal Identity and ontological Provenance of a Pulse.
- PulseContextCodec
- Serialises and deserialises PulseContext, preserving the full parent chain.
- PulseEphemeralPolicy
- A governance policy that defines the Lifecycle Constraints and Termination Logic for a Pulse as it traverses the reactive graph.
- PulseReconstructor
- Reconstructs the input Pulse that produced a LedgerEntry.
-
PulseRecorder<
T extends Cell> - A recorder that captures every pulse emitted by a Cell, in order.
-
PulseShell<
P, R extends Receptor< Cell> > - A specialized Shell providing a Perceptual Projection of a Pulse to facilitate pre-execution validation and security gating.
-
QueueList<
E> -
Receptor<
C extends Cell> - The transformation pipeline that decides how a Cell responds to an incoming Pulse.
-
ReceptorAsync<
C extends Cell> - An asynchronous execution handle for a Receptor that facilitates non‑blocking pulse processing and lifecycle synchronization.
-
ReceptorBase<
C extends Cell> - The foundational base implementation of Receptor that provides the core synchronization and pulse propagation engine.
- RecordingJournal
- The recording side of the journal.
- RegisteredCell
- A thin wrapper that pairs a Cell with its graph-scoped name.
- ReplayEngine
- The replay engine.
- ReplayJournal
- The replay side of the journal.
- ReplayOptions
- Strictness flags that control the replay engine's behaviour when the replayed state diverges from the recorded state.
- ReplayResult
- The result of a ReplayEngine.replay call.
-
RestorableCell<
V> - A ValueCell whose value participates in Flutter's state restoration.
-
RestorableCellDelegate<
V> -
The internal
RestorablePropertythat bridges a RestorableCell to Flutter's restoration protocol. -
Shell<
T> - A specialized Defensive Perimeter and Projection Layer representing a formal contract for Bidirectional Mutual Authorization.
- StateDelta
- A single cell's state change within a ledger entry.
- StreamEffect
- A stream event. Records the event's stream label, the digest of the value, and optionally the raw value.
-
Synapses<
P extends Pulse, L extends Cell> - The distribution fabric for a Cell's outgoing signals—defining how, when, and to whom a pulse is delivered.
-
SynapsesBase<
P extends Pulse, C extends Cell> -
The foundational base implementation for Synapses, serving as the
Transmission Engine of the
cell.corereactive framework. -
SyncBox<
T> - A synchronized variant of Box providing Thread-Safe Access and facilitating Atomic State Transitions across concurrent execution boundaries.
- SyncCycleChecker
- A thread-safe, Synchronized Circular Dependency Guard for asynchronous reactive flows.
-
SyncQueue<
E> - A thread-safe implementation of a PriorityQueue, providing Synchronized Access for prioritized collection-based state.
-
SyncSet<
E> - A thread-safe implementation of a Set, providing Synchronized Access for collection-based state.
- SynthesisCell
- Represents a Synthesis Cell—a specialized structural node that aggregates signals from multiple source cells into a single unified stream.
-
TestActionRule<
C extends Cell> - A specialized behavioral guard for validating imperative logic and functional action execution within the reactive graph.
-
TestCell<
C extends Cell> - The central validation gate for a Cell – it decides what's allowed.
- TestCellReplay
- Purity-aware invocation of a TestCell.
-
TestLinkRule<
C extends Cell> - A specialized behavioral guard for validating Topological Synapses and graph formation within the reactive framework.
- TestPasses
- A sentinel implementation of TestCell that always authorises every operation.
-
TestPulseRule<
C extends Cell> - A rule that validates incoming Pulse signals before they reach a cell.
-
TestRule<
C> - A fundamental architectural component representing an Integrity Gate or Validation Guard, responsible for enforcing structural and business invariants across the reactive graph.
- TimerEffect
- A timer firing. Records the scheduled duration and the actual fire time; the pair is what makes debounce/throttle replayable.
- TransactionBegun
- Emitted when a transaction begins.
- TransactionCommitted
- Emitted when a transaction commits successfully.
- TransactionEvent
- Base class for all transaction lifecycle events.
- TransactionOptions
- Configuration options for a Cell.transaction.
- TransactionRolledBack
- Emitted when a transaction is rolled back.
- TransactionTimedOut
- Emitted when a transaction times out.
- TransactionUpdated
- Emitted when a cell is updated during a transaction.
- TxApplyBegun
- Emitted once, immediately after ApplyTransactionScope.begin succeeds.
- TxApplyCommitted
- Emitted after a successful ApplyTransactionScope.commit.
- TxApplyCompensationFailed
- Emitted each time a compensation attempt fails.
- TxApplyCompensationRetry
- Emitted before each retry of a compensation function.
- TxApplyEvent
- Base class for all lifecycle events emitted by an ApplyTransactionScope.
- TxApplyOptions
- Configuration for Cell.txApply.
- TxApplyRejected
- Emitted when a staged command is refused.
- TxApplyRolledBack
- Emitted after a rollback (full or savepoint-scoped).
- TxApplyStaged
- Emitted once per successful ApplyTransactionScope.enqueueCommand.
-
TypeObject<
T> - Wrapper class for holding typed objects. Provides type safety when working with generic containers.
- Unmodifiable
- A specialized Marker Interface and architectural anchor used to identify reactive nodes and data structures that have been restricted to Read-Only access.
-
UnmodifiableCollectivePulse<
P> -
UnmodifiableEvolvedPulse<
P> -
UnmodifiablePulse<
P> - A read‑only projection of a pulse that enforces structural finality.
-
UnmodifiablePulseBase<
P> -
UnmodifiableValueCell<
V> -
A specialized read‑only proxy of a
ValueCellthat enforces immutability. - UuidEffect
- A UUID generation. Records the generated UUID.
- ValidationFailure
- Represents a validation failure for a specific cell.
-
ValueCell<
V> - A state‑bearing reactive node – the primary way to manage persistent state in the Cell Framework.
-
ValueCellAsync<
V> - A specialized asynchronous controller for ValueCell, providing a thread‑safe and non‑blocking interface for state interaction.
-
ValueNucleus<
V> -
A specialized Nucleus blueprint designed to manage and propagate a
discrete, persistent state value of type
V. - ValueRange
- ValueRange is a specialized TestRule metadata annotation designed to validate whether a numeric input falls within a specific inclusive boundary.
- Values
- Values is a specialized TestRule that validates whether a given input is present within a predefined collection of allowed values.
- VerdictEffect
-
The decision reached by an
effectfulTestCell. - VersionRegistry
-
Maps
(cellId, version)to the receptor and test rule that implemented that version. - WebsiteUrlPattern
- WebsiteUrlPattern is a specialized EntryPattern metadata annotation designed to validate whether a string conforms to a standard web URL format.
Enums
- AuditLevel
- Defines the Observability Granularity and XAI Verbosity required for a Deputy's operations.
- Clearance
- Defines the Sovereign Physical Laws and structural boundaries of reactive operations within the framework.
- CompensationErrorPolicy
- Determines how the transaction scope behaves when a compensation attempt fails.
- ForkPolicy
- How a fork handles the parent graph's state.
- HubRouting
- Defines how a Cell.hub decides which spoke (child cell) should receive an incoming signal.
- Isolation
- Defines the Architectural Boundary & State Visibility of a Deputy.
- IsolationLevel
- Defines the consistency and visibility guarantees for a transaction.
- LineageArgument
-
Defines the specific data field to be extracted when traversing a Pulse's
Causal History via the
lineagemethod. - LockOrdering
- Defines the order in which locks are acquired during commit.
-
Mandate<
V> - Defines the Capability Profile and Authorization Scope for a Deputy.
-
Ontology<
V> - Defines the Structural Taxonomy, Static Identity, and Architectural Shape of a Cell.
- PriorityTier
- Defines the Semantic Urgency Tiers for signal execution.
- PropagationStrategy
- Defines the tactical execution models for Pulse Propagation within the Cell framework's reactive graph.
-
Provenance<
V> - Defines the Causal Accountability, Audit Trail, and Operational Intent of a Pulse.
- Purity
- Classifies a Receptor or TestCell by its effect footprint.
- ReasoningStrategy
- Defines the Logical Pedigree and algorithmic origin of a Pulse.
- Sensitivity
- Defines the Information Classification and data-privacy tier of a Pulse.
- Sovereignty
- Defines the Commitment Authority and Escalation Protocol assigned to a Deputy.
Mixins
-
Deputy<
C extends Cell> - The mixin implementing proxy behavior for Cell.deputy — you don't use this directly.
- Effectful
- The declarative marker for effectful receptors and rules.
- EffectfulReadOnly
- A variant of Effectful for receptors that read the outside world but do not mutate it (clocks, environment variables, read-only database lookups). Reports Purity.readOnlyExternal.
-
GovernanceMixin<
G extends Governance< V> , V> - A convenient mixin that provides default implementations for the Governance interface methods.
-
InstructionChainMixin<
C extends Cell, I extends Pulse, O extends Pulse> - A mixin that provides the core execution engine for composite instructions.
- OpenReceptorMixin
- A mixin that implements the Manual Control Interface for the reactive network.
- OpenSynapsesMixin
- A mixin that implements the Reactive Topology Interface for OpenCell architectures.
Extensions
- ApplyCommandDSL on Cell
- A "fluent" shortcut that makes it easier to create and run commands on a cell.
- CellAsStream on Cell
-
Bridges a Cell to a Dart
Stream<V?>. - CellAsValue on Cell
- An extension that mirrors any Cell into a fresh ValueCell.
- CellEmitAndSettle on WidgetTester
- An extension on WidgetTester that drives a ValueCell through the widget tree and lets the frame pipeline catch up.
- CellExpectGolden on WidgetTester
-
An extension on WidgetTester that captures a golden image of a
CellBuilderover a ValueCell, at the cell's current value. - CellExpectValue on WidgetTester
- An extension on WidgetTester that asserts a ValueCell's current value against a matcher, with a cell-naming diagnostic on failure.
- CellGraphFork on CellGraph
- Forking extensions for CellGraph.
- CellGraphTranslators on CellGraph
- The graph-scoped translator registry.
- CellGraphVersions on CellGraph
- The graph-scoped version registry (see VersionRegistry).
- CellGraphVisualise on CellGraph
- Visualisation for CellGraph and Ledger.
- CellPumpCell on WidgetTester
-
An extension on WidgetTester that pumps a bare
CellBuilderover a ValueCell. - CellPumpWithCells on WidgetTester
- An extension on WidgetTester that pumps a widget inside a CellScope.
- CellRecordPulses on T
- An extension that records every pulse emitted by a Cell, for assertion in tests.
- CellRestoration on Cell
- Static factory access for RestorableCell.
- ForkParentLookup on Ledger
- The parent ledger's hash at a given sequence.
- ForkVerify on ForkHandle
-
Fork-aware verification. A fork's verify requires the parent
ledger's
verify()to pass. - LedgerVisualise on Ledger
- Visualisation for a Ledger's entries (also used by the CLI).
-
PulseExtension
on Pulse<
P> - Provides a fluent, functional API for operating on individual Pulse instances.
-
PulseIterableExtension
on Iterable<
Pulse> - Fluent extensions for collections of Pulse objects.
-
PulseJson
on Pulse<
P> - Encodes this pulse to its canonical JSON wire form via encodePulse.
- ReplayEngineFork on ReplayEngine
- Fork-aware replay: replays a parent ledger into a fork handle, applying a Mutation to each entry.
- TekartikLockExtension on Lock
-
Extension on Lock providing synchronous execution when possible, for
synchronous
computations that don't need to always go through a Future. -
ValueCellBuilder
on ValueCell<
V> - Fluent constructor for a CellBuilder over a ValueCell.
Constants
- pulseNullPayload → const Object
-
Explicitly override
payloadtonullin Pulse.fromJson. - pulseNullPolicy → const Object
-
Explicitly override
policytonullin Pulse.fromJson. - pulseNullSource → const Object
-
Explicitly override
sourcetonullin Pulse.fromJson. - pulseNullStep → const Object
-
Explicitly override
steptonullin Pulse.fromJson. - pulseNullType → const Object
-
Explicitly override
typetonullin Pulse.fromJson.
Functions
-
canonicalJsonDecode(
String source) → Object? - Decodes a canonical JSON string into a JSON-encodable object tree.
-
canonicalJsonEncode(
Object? value, {bool omitNulls = false}) → String -
Encodes
valueinto deterministic, canonical JSON. -
cellEditingController(
ValueCell< String> cell) → CellEditingController -
Creates a CellEditingController bound to
cell. -
decodePulse(
Map< String, dynamic> json, {Cell? resolver(String id)?, bool lenient = false, void onSkipped(List<String> skipped)?}) → PulseBase - Decodes a pulse from the canonical JSON produced by encodePulse.
-
encodePulse(
PulseBase pulse, {bool lenient = false}) → Map< String, dynamic> -
Encodes
pulseto its canonical JSON wire form. -
fingerprint(
Object? value) → String -
Computes the SHA-256 fingerprint of
value's canonical JSON form, hex-encoded. -
get<
T> (Function fn, {Function? fallback, T? orElse}) → T -
A robust functional utility for safely executing operations of type
Twith multi-stage recovery logic and hierarchical fallbacks. -
mapMerge<
K, V> (Map< String, dynamic> map, Map<String, dynamic> other) → Map<String, dynamic> -
restorableState<
V> ({required String restorationId, V? initial, V? fromPrimitives(Object? data)?, Object? toPrimitives(V? value)?}) → RestorableCell< V> - The unqualified alias for CellRestoration.restorableState.
-
snapshotForCell<
V> (Cell cell) → AsyncSnapshot< V> ? -
Returns the AsyncSnapshot the widget should show for
cell's currently retained pulse, ornullwhen nothing usable is retained. -
snapshotForPulse<
V> (Pulse< Object?> pulse) → AsyncSnapshot<V> -
Projects a single Pulse into an AsyncSnapshot for a
CellAsyncBuilder. -
withCellLocks<
T> (Iterable< Cell> cells, Future<T> body(), {int order(Cell a, Cell b)?}) → Future<T> -
Acquires the locks of
cellsin a deterministic total order. -
withLocks<
T> (Iterable< Lock?> locks, Future<T> body()) → Future<T> - Creates a cell that emits the values of a Dart Stream.
Typedefs
-
ApplyArguments
= ({Map<
Symbol, Object?> ? namedArguments, List<Object?> ? positionalArguments}) - A structured container for function arguments that allows for auditing and reversals.
- ApplyCommand = ({ApplyArguments arguments, ApplyCompensation? compensation, Function function})
- A complete request to perform an action or change state within a cell.
- ApplyCompensation = ({ApplyArguments arguments, Cell? cell, Function function})
- A set of instructions used to undo or "roll back" a change if it fails.
- ApplyReceipt = ({ApplyArguments arguments, Cell cell, String? contextVersion, Function function, String id, int? ledgerSeq, String? pulseDigest, String? receptorVersion, String? ruleVersion, DateTime timestamp, int? txSequence, bool vetted})
- The permanent, official record of a specific action taken by a cell.
-
Arguments
= ({Map<
Symbol, dynamic> ? namedArguments, List? positionalArguments}) - Represents a tuple of positional and named arguments for function calls. Used when validating or processing function applications in cells.
-
EgressHandle<
S extends Pulse> = ({Cell cell, void Function() start, void Function() stop}) - A management handle for an Output Terminal, providing a controlled interface to manage an external side-effect listener.
-
FunctionType<
R> = R Function() - Generic function type that takes no parameters and returns RNA. Used in FunctionTypeObject for lazy evaluation.
-
HubHandle
= ({Pulse? Function(Pulse pulse) emit, Future<
Pulse?> Function(Pulse pulse) emitAsync, Future<void> Function(Pulse pulse, {bool serializedCompletion}) ingest, Cell root, Iterable<Cell> spokes}) - A management handle for a Signal Distribution Hub, providing a unified interface to control a multi-destination routing cluster.
-
IngressHandle<
I> = ({Cell cell, bool Function(I input) emit, Future< bool> Function(I input) emitAsync, Future<void> Function(Pulse<I> pulse, {bool serializedCompletion}) ingest}) - A management handle for an Input Gateway, providing a controlled interface for injecting external imperative stimuli into the reactive graph.
-
InheritableHandle
= ({Cell? bind, Context context, EphemeralPolicy<
Cell> ? ephemeralPolicy, Receptor<Cell> receptor, TestCell<Cell> testRule}) - A structured grouping of the Governance & Logic properties that define a node's operational identity and can be cascaded through the inheritance chain.
-
MirroredCell<
V> = ({ValueCell< V> cell, void Function() dispose}) - The paired result of CellAsValue.asValueCell: a mirror cell and the callback that releases it.
- Mutation = Pulse? Function(LedgerEntry entry, Pulse pulse)
- A what-if mutation hook.
- NucleusSimplest = Nucleolus
- A semantic type alias representing the framework's Zero-Overhead Root and the terminal ancestor of all reactive blueprints.
- OpenCellBase = _OpenCell
- Base class for all OpenCell types.
- PulseResolver = Cell? Function(String id)
-
Resolves a
Cell.idto a live Cell. -
SpokeRegistration
= ({DeputyContext? context, Pulse? Function(Cell cell, Pulse pulse, {dynamic user})? handler, String key, bool Function(String? type)? match, int priority, Receptor<
Cell> ? receptor}) - A configuration record for an individual Spoke (Destination) within a Cell.hub.
-
StateHandle<
V> = ({ValueCell< V> cell, Future<void> Function(Pulse<V> pulse, {bool serializedCompletion}) ingest, bool Function(V? value) update, Future<bool> Function(V? value) updateAsync}) - A management record that bundles a ValueCell with its imperative update functions — the standard way to create and interact with a state atom.
-
SynthesisHandle
= ({bool Function(Cell cell) add, void Function(Iterable<
Cell> cells) addAll, SynthesisCell cell, bool Function() clear, bool Function() isEmpty, bool Function(Cell cell) remove, void Function(Iterable<Cell> cells) removeAll, void Function() start, void Function() stop, List<Cell> Function() toList}) - An Administrative Record providing a control interface for dynamic SynthesisCell topographies.
-
TransactionScope
= ({Future<
void> Function(Iterable<Cell> cells) begin, Future<void> Function() commit, dynamic Function(Cell cell) pending, dynamic Function(Cell cell) read, Future<void> Function({Object? savepoint}) rollback, Object Function() savepoint, void Function(Cell cell, dynamic value) update}) - A handle for coordinating atomic, multi‑cell transactions.
Exceptions / Errors
- ForkIntegrityException
- Thrown by ForkVerify.verify when a fork's parent ledger, fork ledger, or genesis binding is invalid.
- LedgerIntegrityException
- Thrown by Ledger.verify when an entry's hash, sequence, or predecessor chain does not match.
- PulseDecodeError
- A pulse JSON record cannot be decoded.
- PulseNotSerializable
- A pulse cannot be serialised because it carries a field that has no honest wire representation.
- ReplayDivergenceException
- Thrown when a replay diverges from the recording.
- TransactionConflictException
- Thrown when an isolation conflict is detected during commit.
- TransactionTimeoutException
- Thrown when a transaction exceeds its timeout duration.
- TransactionValidationException
- Thrown when validation of buffered writes fails during commit.
- TxApplyCompensationException
- Raised when one or more compensations fail under CompensationErrorPolicy.collectThenThrow or CompensationErrorPolicy.failFast.
- TxApplyException
-
Raised for control-flow problems in a ApplyTransactionScope: wrong
phase (e.g.
commitbeforebegin), non-modifiable function, non- participant cell, or a rejected command at commit time.