collective library Core

cell:collective library is a powerful Dart framework for building reactive data structures and event-driven systems. It provides a set of abstract and concrete classes that enable developers to create observable collections, manage state changes, and propagate signals throughout an application.

This library is designed to work seamlessly with the cell:core library, which provides the fundamental building blocks for reactive programming in Dart. The cell:collective library extends the core functionality by introducing reactive collections such as CollectiveSet, CollectiveList, CollectiveQueue, and CollectiveValue.

These collections are designed to be used in conjunction with the Cell class from the cell:core library, which provides a reactive programming model that allows developers to create and manage reactive data structures.

Features

Reactive Collections: The library provides a set of reactive collections that can be used to manage state changes and propagate signals throughout an application.
Event-Driven Architecture: The library supports an event-driven architecture that allows developers to create and manage events and signals.
Signal Propagation: The library provides a set of classes and methods that allow developers to propagate signals throughout an application.
Validation System: The library provides a validation system that allows developers to define rules for what operations are allowed on a collection.
Flexible Signal Processing: The library provides a set of classes and methods that allow developers to process signals in a flexible and customizable manner.
Collection Support: The library provides a set of classes and methods that allow developers to create and manage collections.
Modifiable/Unmodifiable Views: The library provides both modifiable and unmodifiable views of collections, allowing developers to choose the appropriate level of mutability for their use case.
Asynchronous Support: The library provides asynchronous interfaces for all operations, allowing developers to work with asynchronous data sources.
Testable: The library provides a set of classes and methods that allow developers to create and manage testable collections.
Type Safety: The library provides a set of classes and methods that allow developers to create and manage type-safe collections.
Performance: The library is designed to be performant and efficient, allowing developers to create and manage collections with minimal overhead.
Documentation: The library is well-documented, providing developers with clear and concise information on how to use the library.

Example Usage

import 'package:cell/collective.dart';

void main() {
 // Create a new CollectiveList
 final list = CollectiveList<int>();

// Add elements to the list
 list.add(1);
 list.add(2);
 list.add(3);

// Listen for changes to the list
 Cell.listen<CollectivePost>(
   bind: list,
   listen: (post, _) {
   print('List changed: ${post.body}');
   }
 );

// Remove an element from the list
list.remove(2); // Output: ElementRemoved: 2
}

// Create a immutable version of the list
final unmodifiable = list.unmodifiable;

unmodifiable.add(4); // Throws UnsupportedError

// Create an async version of the list
final asyncList = list.async;

await asyncList.add(5); // Async operation

Performance Considerations

Use unmodifiable views when mutation isn't needed
Consider identitySet for large collections of objects
Be mindful of signal propagation in deep cell hierarchies
Use asynchronous operations for expensive mutations

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.
Collective<E>: A reactive collection that combines Cell behavior with Iterable functionality. Notifies about changes (add/remove/update) and maintains relationships between cells.
CollectiveAsync<E, C extends Collective<E>>: An asynchronous wrapper for Collective operations that provides Future-based APIs.
CollectiveCell<E>: An implementation of Collective that is unmodifiable.
CollectiveCellProperties<E, I extends Iterable<E>>: Concrete implementation of collection properties configuration.
CollectiveEvent: A specialized Tag class that represents events that can occur within a Collective.
CollectiveList<E>: CollectiveList<E> is a fully reactive List implementation that extends Dart's List<E> with cell-based reactivity. It automatically propagates changes to connected cells and supports validation, async operations, and immutable variants.
CollectiveListAsync<E>: Provides asynchronous versions of CollectiveList operations.
CollectiveListDeputy<E>: A helper class that provides an "deputy" (deputy) interface for CollectiveList.
CollectivePost: A signal that carries collection change information
CollectiveProperties<E>: Interface defining configuration properties for Collective instances.
CollectiveQueue<E>: CollectiveQueue is a reactive queue implementation that extends Dart's Queue functionality with cell-based reactivity. It propagates changes through the cell network when modified and supports all standard queue operations with validation capabilities.
CollectiveQueueAsync<E>: An asynchronous interface for performing operations on a CollectiveQueue.
CollectiveQueueDeputy<E>: A helper class that provides an deputy interface for CollectiveQueue.
CollectiveReceptor<E, IN extends Signal, OU extends Signal>: Specialized receptor for handling Collective signals
CollectiveSet<E>: CollectiveSet<E> is a reactive Set implementation that integrates with Dart's Set<E> while providing cell-based reactivity. It automatically propagates changes to connected cells when modified and supports validation rules.
CollectiveSetAsync<E>: Provides asynchronous versions of CollectiveSet operations.
CollectiveSetDeputy<E>: A CollectiveSetDeputy is a delegated view of a CollectiveSet with modified behavior.
CollectiveValue<V>: CollectiveValue<V> is a reactive single-value container that integrates with the cell-based reactivity system. It provides change notifications when its value is modified and supports validation, async operations, and immutable variants.
CollectiveValueAsync<V>: An asynchronous wrapper for CollectiveValue operations that provides Future-based APIs.
CollectiveValueDeputy<V>: A helper class that provides reduced functionality for CollectiveValue objects.
CollectiveValueProperties<V>: Configuration properties for a CollectiveValue instance.
ContainerType: Defines behavior for different collection container types
ElementValueChange<E, V>: Represents a value change for a specific element within a collection.
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
Post<C extends Cell, N extends Tag>: A specialized Signal that represents a notification event between cells in a reactive system.
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.
TestCollective<E, C extends Collective<E>>: A rule-based testing system for validating operations on Collective collections.
TestCollectiveElementRule<E, C extends Collective<E>>: A rule implementation for validating elements in a Collective.
TestCollectiveTrue<E, C extends Collective<E>>: A TestCollective implementation that always passes all validations.
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.
UnmodifiableCollective<E>: An interface for an unmodifiable Collective.
UnmodifiableCollectiveCell<E>: An implementation of UnmodifiableCollective that is unmodifiable.
UnmodifiableCollectiveList<E>: An unmodifiable version of CollectiveList that prevents all mutating operations.
UnmodifiableCollectiveListAsync<E>: An async callable interface for UnmodifiableCollectiveList that prevents modifications.
UnmodifiableCollectiveQueue<E>: An unmodifiable version of a CollectiveQueue that implements the Queue interface.
UnmodifiableCollectiveQueueAsync<E>: An asynchronous interface for an unmodifiable CollectiveQueue that prevents all modifications.
UnmodifiableCollectiveSet<E>: An immutable version of CollectiveSet that prevents all modification operations.
UnmodifiableCollectiveSetAsync<E>: Async operations for an UnmodifiableCollectiveSet.
UnmodifiableCollectiveValue<V>: An immutable version of CollectiveValue that prevents modifications to the value.
UnmodifiableCollectiveValueAsync<V>: Specialized unmodifiable version of CollectiveValueAsync.
ValueChange<V>: Represents a change in value, tracking both the previous and current states.

Mixins

Deputy<C extends Cell>: A mixin that provides the ability to create Deputy for a cell.
OpenListMixin<E>: A mixin that provides reactive list operations for CollectiveCell.
OpenQueueMixin<E>: A mixin that provides queue operations for CollectiveCell implementations.
OpenReceptorMixin<C extends Cell, I extends Signal, O extends Signal>: Mixin that adds signal reception capabilities to a Cell.
OpenSetMixin<E>: A mixin for OpenSetMixin that provides additional functionality for CollectiveCell.
OpenSynapsesMixin<L extends Cell>: Mixin that adds cell linking capabilities.
OpenValueMixin<V>: A mixin that provides additional functionality for CollectiveValue objects.

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.
CollectiveBase<E> = CollectiveCell<E>: A base class for all Collective types.
CollectiveListBase<E> = _CollectiveList<E>: A base class for CollectiveList that provides common properties and methods.
CollectiveListProperties<E> = CollectiveCellProperties<E, List<E>>: Type alias for List-specific Collective properties
CollectiveQueueBase<E> = _CollectiveQueue<E>: A base class for CollectiveQueue that provides common properties and methods.
CollectiveQueueProperties<E> = CollectiveCellProperties<E, Queue<E>>: Type alias for Queue-specific Collective properties
CollectiveSetBase<E> = _CollectiveSet<E>: A base class for CollectiveSet that provides common properties and methods.
CollectiveSetProperties<E> = CollectiveCellProperties<E, Set<E>>: Type alias for Set-specific Collective properties
CollectiveValueBase<V> = _CollectiveValue<V>: A base class for CollectiveValue that provides common properties and methods.
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.
TestCollectiveBase<E, C extends Collective<E>> = TestCollective<E, C>: Base type for Collective test rules
TestCollectiveElementType<E, C extends Collective<E>> = bool Function(E? element, C base, {Function? action, dynamic user}): Function signature for validating elements in a Collective Parameters:
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.