cell library Core

cell:core is a reactive programming framework centered around the Cell class and its extensions, particularly the Collective family of classes that implement reactive collections CollectiveSet, CollectiveList, CollectiveQueue and CollectiveValue. This framework provides a comprehensive reactive programming solution for Dart, with particular strength in managing complex state and data flow in applications.

Features

Reactive Programming Model: Automatic propagation of changes through a network of cells
Validation System: Configurable rules for what operations are allowed
Flexible Signal Processing: Customizable signal transformation and propagation
Collection Support: Reactive versions of common collection types
Modifiable/Unmodifiable Views: Both mutable and immutable variants of all containers
Asynchronous Support: Async interfaces for all operations

Core Components and Their Relationships

Cell - The Fundamental Reactive Unit

Purpose: Acts as the basic building block of reactivity

Key Relationships:
- Contains Properties that define its behavior
- Uses Receptor for signal processing
- Manages Synapses for communication with other cells
- Can be wrapped by Deputy for delegation
- Uses TestObject/TestRule for validation
Receptor - Signal Processing

Purpose: Handles signal transformation and propagation

Key Relationships:
- Attached to a Cell via Properties
- Processes incoming Signal objects
- Can trigger Synapses to propagate signals
- Has both synchronous (_Receptor) and asynchronous (ReceptorAsync) implementations
Synapses - Inter-Cell Communication

Purpose: Manages connections between cells

Key Relationships:
- Maintained in Properties
- Used by Cell to propagate signals to linked cells
- Can be enabled or disabled
- Has implementations for sync (_Synapses) and no-op (_SynapsesNever) behavior
Properties - Cell Configuration

Purpose: Contains all configurable aspects of a cell

Key Relationships:
- Owned by Cell
- Contains Receptor, Synapses, and TestObject
- Manages cell binding relationships
- Can be extended (e.g., CollectiveProperties for collections)
TestRule/TestObject - Validation System

Purpose: Provides validation rules for cell operations

Key Relationships:
- Stored in Properties
- Used by Cell to validate signals and actions
- Can be combined using operator +
- Specialized versions exist (e.g., TestCollective for collections)
Signal - Data Carrier

Purpose: Carries data between cells

Key Relationships:
- Processed by Receptor
- Propagated through Synapses
- Validated by TestObject
- Specialized versions exist (e.g., Post for collections)
Deputy - Delegation Pattern

Purpose: Wraps cells to modify behavior

Key Relationships:
- Implements same interface as wrapped Cell
- Delegates to original cell while adding functionality
- Can modify TestObject behavior
- Used via deputy() factory method

Key Architectural Patterns

Reactive Flow:

Signals enter through Receptor
TestObject validates the signal
If valid, processed by Receptor.transform
Output signal propagated via Synapses

Decorator Pattern:

Deputy wraps cells to modify behavior
CellAsync adds asynchronous capabilities

Composite Pattern:

TestObject can contain multiple TestRule instances
Collective types manage collections of cells

Strategy Pattern:

Different Receptor implementations handle signal processing
Synapses implementations vary propagation behavior

Detailed Component Interactions

Signal Processing Flow:

A Signal arrives at a Cell
The Cell's Properties.receptor processes it
The Receptor checks with TestObject for validation
If valid, applies transformation (if any)
Resulting signal is sent through Synapses to linked cells

Cell Initialization:

Cell created with or without Properties
If no Properties, defaults are used:
If binding to another cell, synapses are linked

Deputy Functionality:

Wraps an existing Cell
Can modify:
- Test behavior by combining with new TestObject
- Mapping behavior via MapObject
Maintains reference to original cell

Test System Operation:

TestObject contains one or more TestRules
Rules can test:
- Signals (TestSignalRule)
- Actions (TestActionRule)
- Links (TestLinkRule)
Rules can be combined for complex validation

Disclaimer

It is an A.I. generated document. The content is based on the code provided and may not accurately reflect the intended functionality or usage of the package. Please review and modify as necessary to ensure accuracy and clarity.

Classes

Async<C>: Class tag to indicate Async version of an object
Cell: 'cell:core' is a reactive programming framework centered around the Cell class and its extensions, particularly the Collective family of classes that implement reactive collections CollectiveSet, CollectiveList, CollectiveQueue and CollectiveValue. This framework provides a comprehensive reactive programming solution for Dart, with particular strength in managing complex state and data flow in applications.
CellAsync<C extends Cell>: Provides asynchronous execution of operations on a Cell.
CellDeputy: Deputy is a pattern that allows a Cell that delegates actions to.
CellSync: A specialized Cell that provides a default implementation for the Cell interface.
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.
MapObject: A configurable mapping system that can transform objects based on their type. Supports chaining through parent mappings and type-specific transformations.
OpenCell<C extends Cell, L extends Cell, I extends Signal, O extends Signal>: An extended Cell with open receptor and linking capabilities for enhanced reactivity.
OpenCellAsync<C extends Cell, L extends Cell, I extends Signal, O extends Signal>: An asynchronous executor for OpenCell with enhanced signal processing capabilities.
OpenCellDeputy<C extends Cell, L extends Cell, I extends Signal, O extends Signal>: A specialized CellDeputy that maintains open receptor and linking capabilities while adding layered behavior to an OpenCell.
OpenCellSync<C extends Cell, L extends Cell, I extends Signal, O extends Signal>: A specialized Cell that provides open receptor and synapse binding
Properties: Encapsulates the core characteristics of a Cell, including its receptor, linkage state, and validation tests.
Receptor<C extends Cell, I extends Signal, O extends Signal>: The signal processing engine of a Cell, transforming incoming signals into outputs.
ReceptorAsync<C extends Cell, I extends Signal, O extends Signal, R extends Receptor<C, I, O>>: An Async variant of Receptor for handling asynchronous signal processing.
Signal<T>: A typed signal that can be transmitted through cells.
Synapses<S extends Signal, L extends Cell>: A system for managing reactive connections between Cell instances.
Sync<C>: Class tag o indicate Sync version of an object
Tag: A simple identifier class using Symbols for tagging/labeling purposes. Useful for categorizing or marking cells without modifying their behavior.
TestActionRule<C extends Cell>: A specialized test rule for validating function actions within a Cell context.
TestLinkRule<C extends Cell>: A specialized test rule for validating cell linking operations within a Cell context.
TestObject<C extends Cell>: TestObject is a composite of multiple TestRules that applies them sequentially to validate operations on a Cell.
TestObjectRule<C extends Cell>: An abstract interface for creating test rules that validate arbitrary objects within a Cell context.
TestObjectTrue: A default implementation of TestObject that always passes validation.
TestRule<O, C extends Cell>: An interface for defining validation rules that can be applied to objects in a reactive cell system.
TestRuleTrue: A concrete implementation of TestRule that always returns true.
TestSignalRule<C extends Cell>: A specialized TestRule implementation for validating Signal objects within a cellular architecture.
TypeObject<T>: Wrapper class for holding typed objects. Provides type safety when working with generic containers.
Unmodifiable: A marker interface indicating immutable/unmodifiable cell variants.

Mixins

Deputy<C extends Cell>: A mixin that provides the ability to create Deputy for a cell.
OpenReceptorMixin<C extends Cell, I extends Signal, O extends Signal>: Mixin that adds signal reception capabilities to a Cell.
OpenSynapsesMixin<L extends Cell>: Mixin that adds cell linking capabilities.

Typedefs

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.
CellBase = CellSync: Base class for all Cell types.
FunctionType<R> = R Function(): Generic function type that takes no parameters and returns R. Used in FunctionTypeObject for lazy evaluation.
MapFunction = E Function<E>(E object, {Cell? cell, dynamic user}): A function signature for value transformations within a MapObject pipeline.
OpenCellBase = OpenCellSync<Cell, Cell, Signal, Signal>: Base class for all OpenCell types.
ReceptorBase<C extends Cell, I extends Signal, O extends Signal> = _Receptor<C, I, O>: A base implementation of Receptor that provides default behavior.
SignalTransform<C extends Cell, I extends Signal, O extends Signal> = O? Function({required C cell, required I signal, dynamic user}): Function signature for transforming signals in receptors.
TestActionRuleType<C extends Cell> = bool Function(Function action, C cell, {Arguments? arguments, dynamic user}): Function signature for validating actions performed on cells.
TestLinkRuleType<C extends Cell> = bool Function(Cell link, {C? cell, dynamic user}): Function signature for validating links between cells.
TestObjectBase<C extends Cell> = _TestObject<C>: A typedef representing the base implementation class for TestObject.
TestObjectRuleBase<C extends Cell> = _TestObjectRuleView<C>: Typedef for the base implementation class.
TestSignalRuleType<C extends Cell> = bool Function(Signal signal, {C? cell, dynamic user}): Function signature for validating signals received by cells.

Exceptions / Errors

TestRuleIncompatibleException: Exception thrown when incompatible rules are combined.