reacton library

Reacton - A novel reactive graph engine for Dart.

Fine-grained state management with reactons, computed values, effects, state branching, time-travel debugging, and more.

Quick Start

import 'package:reacton/reacton.dart';

// Create reactons (Level 1)
final counterReacton = reacton(0, name: 'counter');

// Derive state (Level 2)
final doubleReacton = computed((read) => read(counterReacton) * 2);

// Use in a store
final store = ReactonStore();
print(store.get(counterReacton)); // 0
store.set(counterReacton, 5);
print(store.get(doubleReacton)); // 10

Classes

ActionLog

A complete audit log of all state mutations.

ActionRecord

A record of a single state mutation.

All<T>

Run multiple futures in parallel and wait for all of them to complete.

AsyncData<T>

Data state - the async operation completed successfully.

AsyncError<T>

Error state - the async operation failed.

AsyncLoading<T>

Loading state - an async operation is in progress.

AsyncReacton<T>

A reacton that manages an asynchronous value.

AsyncValue<T>

Represents the state of an asynchronous operation.

BranchChange

A single change in a branch.

BranchDiff

The complete set of differences between a branch and its parent.

Call<T>

Execute an asynchronous function and return its result.

Cancel

Cancel a running SagaTask.

CollaborativeReacton<T>

A reactive state unit that synchronizes across distributed nodes using CRDT (Conflict-free Replicated Data Type) semantics.

CollaborativeSession

Manages CRDT-based state synchronization for a set of CollaborativeReacton instances over a SyncChannel.

CollectionChange<T>

Change event for observable collections.

CollectionCleared<T>

ComposedLens<A, B, C>

A lens formed by composing two lenses in sequence.

ConflictEvent<T>

Describes a conflict that was detected and automatically resolved during CRDT merge.

CrdtMergeStrategy<T>

A sealed hierarchy of conflict resolution strategies for concurrent CRDT updates.

CrdtValue<T>

A value annotated with CRDT metadata for distributed conflict resolution.

CustomMerge<T>

Custom merge function for application-specific conflict resolution.

Debouncer

Debounce utility for rate-limiting function calls.

Delay

Suspend the saga for the given duration.

DevToolsMiddleware<T>

Middleware that reports state changes to DevTools.

EffectNode

An effect node that runs side effects when dependencies change.

EnumSerializer<T extends Enum>

Serializer for enum values.

FilteredListLens<T>

A lens that focuses on the subset of a list matching a predicate.

Fork

Fork a child saga to run concurrently (non-blocking).

GraphNode<T>

Internal representation of a node in the reactive dependency graph.

HandshakeAck

Handshake response from the worker.

HandshakeInit

Initial handshake message sent when spawning a worker.

History<T>

Time-travel controller for a reacton.

HistoryEntry<T>

A single entry in the history log.

InMemorySyncChannel

An in-memory SyncChannel backed by Dart streams.

Interceptor<T>

An interceptor that can transform or reject reacton updates.

InterceptorChain<T>

A chain of interceptors executed in order.

IsolateChannel

Two-way communication channel between isolates.

IsolateMessage

Base class for all messages between isolates.

IsolateStore

Enables sharing reactive state across Dart isolates.

ItemAdded<T>

ItemRemoved<T>

ItemsMoved<T>

ItemUpdated<T>

Join

Wait for a previously forked SagaTask to complete.

JsonPersistenceMiddleware<T>

Convenience middleware for persisting reactons with JSON serialization.

JsonSerializer<T>

Built-in JSON serializer for types that support toJson().

LastWriterWins<T>

Last-writer-wins conflict resolution based on wall-clock timestamps.

ListItemLens<T>

A lens that focuses on a single element of a List by index.

ListReacton<T>

A writable reacton that holds a List<T> with granular collection operations.

ListSerializer<T>

Serializer for List types.

LoggingMiddleware<T>

Built-in middleware that logs reacton lifecycle events.

MapChange<K, V>

Change event for observable maps.

MapCleared<K, V>

MapEntryAdded<K, V>

MapEntryLens<K, V>

A lens that focuses on a single entry of a Map by key.

MapEntryRemoved<K, V>

MapEntryUpdated<K, V>

MapReacton<K, V>

A writable reacton that holds a Map<K, V> with granular operations.

MaxValue<T extends Comparable<T>>

Max-value conflict resolution (GCounter pattern).

MemoryStorage

In-memory storage adapter (non-persistent, for testing).

Middleware<T>

Base class for reacton middleware.

OptimisticUpdate<T>

Performs an optimistic update with automatic rollback on failure.

PersistenceMiddleware<T>

Built-in middleware for automatic reacton persistence.

PrimitiveSerializer<T>

Serializer for primitive types (int, double, String, bool).

Put<T>

Dispatch a value to a WritableReacton in the store.

QueryConfig

Configuration for a query reacton.

QueryContext<Arg>

Context available during query execution.

QueryFamily<T, Arg>

A family of query reactons parameterized by an argument.

QueryReacton<T>

A query reacton that fetches data from an async source with smart caching.

Race<T>

Race multiple futures against each other. The first to complete wins, and the others are discarded.

ReactiveGraph

The core reactive graph engine.

ReactonBase<T>

Base class for all reactons in the Reacton reactive system.

ReactonFamily<T, Arg>

A factory that creates parameterized reactons on-demand.

ReactonLens<S, T>

A bidirectional, reactive lens that focuses on a part of a reacton's state.

ReactonModule

A module groups related reactons with lifecycle management.

ReactonOptions<T>

Configuration options for reactons.

ReactonRef

Unique identity for a reacton, used as a key in the store.

ReactonStore

The central value container for all reactons in the Reacton system.

ReactonSubscribe

Request to subscribe to a reacton's changes.

ReactonUnsubscribe

Request to unsubscribe from a reacton's changes.

ReactonValueChanged

Sent when a reacton's value changes.

ReadonlyReacton<T>

A read-only reacton that derives its value from other reactons.

RecordedSession

A complete, immutable recording of state changes within a ReactonStore.

RetryPolicy

Policy for retrying failed async operations.

Saga<E>

A saga definition that describes how to handle events of type E.

SagaBuilder<E>

Builder DSL for registering event handlers on a Saga.

SagaContext

Provides saga handlers with an imperative API for issuing effects.

SagaEffect<T>

A declarative description of a side effect to be performed by the saga runtime.

SagaRegistration<E>

Describes a single event-handler registration within a Saga.

SagaTask

Represents a running saga instance.

Select<T>

Read the current value of a ReactonBase from the store without subscribing to changes.

SelectorReacton<T, S>

A selector reacton that watches a sub-value of another reacton.

Serializer<T>

Interface for serializing/deserializing reacton values for persistence.

SessionMark

A named bookmark in a recorded session timeline.

SessionPlayer

Replays a RecordedSession against a ReactonStore.

SessionRecorder

Records state changes from a ReactonStore in real time.

SnapshotDiff

The differences between two snapshots.

StateBranch

A state branch - an isolated copy-on-write overlay on the parent store.

StateEvent

A single recorded state change within a session.

StateMachineReacton<S, E>

A state machine reacton manages typed state transitions.

StorageAdapter

Abstract interface for persistent storage backends.

StoreSnapshot

An immutable snapshot of all reacton values at a point in time.

SyncAck

Acknowledgment message confirming receipt of a sync update.

SyncChannel

Abstract transport layer for CRDT synchronization.

SyncDelta

Incremental state update message.

SyncFull

Full state synchronization message.

SyncMessage

A sealed hierarchy of wire-protocol messages for CRDT state synchronization.

SyncRequestFull

Request for full state synchronization.

Take<E>

Wait for the next event of type E dispatched to the saga.

Throttler

Throttle utility for rate-limiting function calls.

TransitionContext<S>

Context available during state machine transitions.

UnionMerge<T extends Set>

Union-merge conflict resolution (GSet pattern).

UpdateScheduler

Handles batching of updates for the reactive graph.

VectorClock

A vector clock for establishing causal ordering between distributed events.

WritableReacton<T>

A writable reacton holds a mutable value that can be read and written.

Enums

HandlerStrategy

The concurrency strategy used by a saga event handler registration.

MergeStrategy

Strategy for resolving conflicts when merging a branch.

NodeState

The reactivity state of a graph node.

SyncStatus

The synchronization status of a CollaborativeSession.

Mixins

Disposable

Mixin for objects that hold resources and need cleanup.

Extensions

ReactonLensComposition on ReactonLens<S, T>

Extension providing shorthand composition operators on ReactonLens.

ReactonStoreBranching on ReactonStore

Extension on ReactonStore for branch operations.

ReactonStoreCollab on ReactonStore

Extension on ReactonStore providing collaborative state synchronization capabilities.

ReactonStoreHistory on ReactonStore

Extension on ReactonStore for time-travel.

ReactonStoreLens on ReactonStore

Extension on ReactonStore providing lens-aware operations.

ReactonStoreLensIntegration on ReactonStore

Extension on ReactonStore providing convenience aliases for lens-typed reactons.

ReactonStoreList on ReactonStore

Extension on ReactonStore for list operations.

ReactonStoreMap on ReactonStore

Extension on ReactonStore for map operations.

ReactonStoreModules on ReactonStore

Extension on ReactonStore for module management.

ReactonStoreOptimistic on ReactonStore

Extension on ReactonStore for optimistic updates.

ReactonStoreQuery on ReactonStore

Extension on ReactonStore for query operations.

ReactonStoreRecording on ReactonStore

Adds session recording and replay capabilities to ReactonStore.

ReactonStoreSaga on ReactonStore

Extends ReactonStore with saga (effect orchestrator) capabilities.

ReactonStoreStateMachine on ReactonStore

Extension on ReactonStore for state machine operations.

Functions

asyncReacton<T>(Future<T> fetch(ReactonReader read), {String? name, RetryPolicy? retryPolicy, Duration? refreshInterval}) → AsyncReacton<T>

Create an async reacton that fetches data when dependencies change.

collaborativeReacton<T>(T initialValue, {String? name, CrdtMergeStrategy<T>? strategy, Serializer<T>? serializer, ReactonOptions<T>? options}) → CollaborativeReacton<T>

Creates a CollaborativeReacton with the given initial value and CRDT configuration.

computed<T>(T compute(ReactonReader read), {String? name, ReactonOptions<T>? options}) → ReadonlyReacton<T>

Create a computed (read-only) reacton that derives its value from other reactons.

createEffect(EffectCleanup? fn(ReactonReader read), {String? name}) → EffectNode

Create a side effect that automatically tracks its dependencies.

family<T, Arg>(ReactonBase<T> create(Arg arg)) → ReactonFamily<T, Arg>

Create a family of parameterized reactons.

filteredListLens<T>(WritableReacton<List<T>> source, bool predicate(T), {String? name, bool equals(List<T>, List<T>)?}) → FilteredListLens<T>

Creates a FilteredListLens that focuses on a subset of a list reacton matching a predicate.

lens<S, T>(WritableReacton<S> source, T get(S), S set(S, T), {String? name, bool equals(T, T)?}) → ReactonLens<S, T>

Creates a ReactonLens that focuses on part of a reacton's state.

listLens<T>(WritableReacton<List<T>> source, int index, {String? name}) → ListItemLens<T>

Creates a ListItemLens that focuses on a specific element of a list reacton by index.

mapLens<K, V>(WritableReacton<Map<K, V>> source, K key, {String? name}) → MapEntryLens<K, V>

Creates a MapEntryLens that focuses on a specific key of a map reacton.

reacton<T>(T initialValue, {String? name, ReactonOptions<T>? options, void onWrite(void set<V>(WritableReacton<V>, V), T value)?}) → WritableReacton<T>

Create a writable reacton with the given initial value.

reactonList<T>(List<T> initialValue, {String? name, ReactonOptions<List<T>>? options}) → ListReacton<T>

Create a reactive list reacton.

reactonMap<K, V>(Map<K, V> initialValue, {String? name, ReactonOptions<Map<K, V>>? options}) → MapReacton<K, V>

Create a reactive map reacton.

reactonQuery<T>({required Future<T> queryFn(QueryContext<void>), QueryConfig config = const QueryConfig(), String? name}) → QueryReacton<T>

Create a query reacton.

reactonQueryFamily<T, Arg>({required Future<T> queryFn(QueryContext<Arg>), QueryConfig config = const QueryConfig(), String? name}) → QueryFamily<T, Arg>

Create a query family.

saga<E>({String? name, required void builder(SagaBuilder<E> on)}) → Saga<E>

Create a Saga that handles events of type E.

selector<T, S>(ReactonBase<T> source, S select(T), {String? name, ReactonOptions<S>? options}) → SelectorReacton<T, S>

Create a selector reacton that watches a sub-value of another reacton.

stateMachine<S, E>({required S initial, required Map<S, Map<E, TransitionHandler<S>>> transitions, Map<E, TransitionGuard<S>>? guards, TransitionEffect<S>? onTransition, String? name, ReactonOptions<S>? options}) → StateMachineReacton<S, E>

Create a state machine reacton with typed states and events.

Typedefs

EffectCleanup = void Function()

A function that can be called to clean up an effect.

NodeChangeCallback = void Function(ReactonRef ref)

Callback for when a node's value changes.

ReactonReader = T Function<T>(ReactonBase<T> reacton)

Type of reader function used by computed reactons and effects.

SagaHandler = Future<void> Function(SagaContext ctx, [dynamic event])

Signature for a saga handler function.

TransitionEffect<S> = void Function(S previousState, S newState)

Side effect to run after a transition completes.

TransitionGuard<S> = bool Function(S currentState)

Guard function that determines if a transition should be allowed.

TransitionHandler<S> = FutureOr<S> Function(TransitionContext<S> context)

A transition handler returns the next state (sync or async).

Unsubscribe = void Function()

A function that unsubscribes/cancels a subscription.

Exceptions / Errors

QueryCancelledException

Exception thrown when a query is cancelled.

SagaCancelledException

Thrown when a saga task is cancelled.