CollectiveList<E> class abstract interface

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.

Key features:

  • Reactivity: Automatically notifies changes to connected cells.
  • Validation: Supports custom validation rules for elements and actions.
  • Async Operations: Provides async methods for list operations.
  • Immutability: Can create unmodifiable versions of the list.
  • Customizability: Allows user-defined properties and behaviors.

Example: Basic Usage

final todoList = CollectiveList<String>();

// Listen to changes
final listener = Cell.listen(
  bind: todoList,
  listen: (CollectivePost post, _) {
    post.body?.forEach((event, elements) {
      print('$event: $elements');
    });
  }
);

todoList.addAll(['Buy milk', 'Walk dog']);
// Output: CollectiveEvent._(identifier: #elementAdded): [Buy milk, Walk dog]

todoList.removeAt(0);
// Output: CollectiveEvent._(identifier: #elementRemoved): [Buy milk]

Example: Validation

final validList = CollectiveList<int>(
  test: TestCollective.create(
    elementDisallow: (n) => n < 0,  // Blocks negatives
    maxLength: 3                    // Max 3 items
  )
);

validList.add(1);     // Allowed
validList.add(-1);    // Blocked
validList.addAll([2, 3, 4]);  // 4th item blocked
validList.add(5);    // Blocked

Example: Async Operations

  await asyncList.async.add('Hello');
  await asyncList.async.insertAll(0, ['Welcome', 'Hi']);

  final removed = await asyncList.async.removeLast();
  print(removed); // 'Hello'

Example: Async Operations

final asyncList = CollectiveList<String>();

void main() async {
  await asyncList.async.add('Hello');
  await asyncList.async.insertAll(0, ['Welcome', 'Hi']);

  final removed = await asyncList.async.removeLast();
  print(removed); // 'Hello'
}


// Create a reactive list
final list = CollectiveList<int>(growable: true);

// Listen to changes
final listener = Cell.listen<CollectivePost>(
   bind: list,
   listen: (post, _) => print('Change: ${post.body}')
);

list.add(1); // Triggers elementAdded signal
list.insert(0, 2); // Triggers elementAdded signal
list.removeAt(0); // Triggers elementRemoved signal

Example: Chained Collectives

// Create source list
final source = CollectiveList<int>([1, 2, 3]);

// Create filtered view
final filtered = CollectiveList<int>(
    bind: source,
    test: TestCollective.create(
        elementDisallow: (e, _) => e! < 2
    )
);

// Changes to source propagate to filtered
source.add(0); // Won't appear in filtered
source.add(5); // Will appear in filtered
Implemented types
Implementers
Available extensions

Constructors

CollectiveList.new({Cell? bind, TestCollective<dynamic, Collective> test, bool growable})
Creates an empty growable list by default from elements
factory
CollectiveList.fromProperties(CollectiveListProperties<E> properties, {Iterable<E>? elements})
Creates a CollectiveList from properties
factory
CollectiveList.of(Iterable<E> elements, {Cell? bind, TestCollective<dynamic, Collective> test, bool growable})
Creates a growable list by default from elements
factory
CollectiveList.unmodifiable(CollectiveList<E> bind, {bool unmodifiableElement = true})
Creates an unmodifiable CollectiveList from elements
factory

Properties

async → CollectiveListAsync<E>
Creates a Async CollectiveListAsync for async modifiable operations
no setteroverride
first ↔ E
The first element.
getter/setter pairinherited-getter
firstOrNull → T?

Available on Iterable<T>, provided by the IterableExtensions extension

The first element of this iterator, or null if the iterable is empty.
no setter
hashCode → int
The hash code for this object.
no setterinherited
indexed → Iterable<(int, T)>

Available on Iterable<T>, provided by the IterableExtensions extension

Pairs of elements of the indices and elements of this iterable.
no setter
isEmpty → bool
Whether this collection has no elements.
no setterinherited
isNotEmpty → bool
Whether this collection has at least one element.
no setterinherited
iterator → Iterator<E>
A new Iterator that allows iterating the elements of this Iterable.
no setterinherited
last → E
The last element.
no setterinherited
lastOrNull → T?

Available on Iterable<T>, provided by the IterableExtensions extension

The last element of this iterable, or null if the iterable is empty.
no setter
length ↔ int
The number of elements in this Iterable.
getter/setter pairinherited-getter
modifiable → Iterable<Function>
Returns an iterable containing modifiable functions.
no setterinherited
nonNulls → Iterable<T>

Available on Iterable<T?>, provided by the NullableIterableExtensions extension

The non-null elements of this iterable.
no setter
reversed → Iterable<E>
An Iterable of the objects in this list in reverse order.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
single → E
Checks that this iterable has only one element, and returns that element.
no setterinherited
singleOrNull → T?

Available on Iterable<T>, provided by the IterableExtensions extension

The single element of this iterator, or null.
no setter
test → TestCollective<dynamic, Collective>
Gets the test object associated with the cell.
no setterinherited
unmodifiable → CollectiveList<E>
Creates an unmodifiable view of this cell.
no setteroverride
wait → Future<List<T>>

Available on Iterable<Future<T>>, provided by the FutureIterable extension

Waits for futures in parallel.
no setter

Methods

add(E value) → dynamic
Adds an element to the set
addAll(Iterable<E> iterable) → dynamic
Adds all elements from the iterable to the set
any(bool test(E element)) → bool
Checks whether any element of this iterable satisfies test.
inherited
apply(Function function, List? positionalArguments, [Map<Symbol, dynamic>? namedArguments]) → dynamic
Applies a function with controlled validation.
inherited
asMap() → Map<int, E>
An unmodifiable Map view of this list.
asNameMap() → Map<String, T>

Available on Iterable<T>, provided by the EnumByName extension

Creates a map from the names of enum values to the values.
byName(String name) → T

Available on Iterable<T>, provided by the EnumByName extension

Finds the enum value in this list with name name.
cast<R>() → Iterable<R>
A view of this iterable as an iterable of R instances.
inherited
clear() → dynamic
Clears the set, removing all elements
contains(Object? element) → bool
Whether the collection contains an element equal to element.
inherited
deputy({covariant TestCollective<dynamic, Collective>? test, covariant MapObject? mapObject}) → CollectiveList<E>
Creates an Deputy from this CollectiveList with either test or map or both properties. The new CollectiveList
override
elementAt(int index) → E
Returns the indexth element.
inherited
elementAtOrNull(int index) → T?

Available on Iterable<T>, provided by the IterableExtensions extension

The element at position index of this iterable, or null.
every(bool test(E element)) → bool
Checks whether every element of this iterable satisfies test.
inherited
expand<T>(Iterable<T> toElements(E element)) → Iterable<T>
Expands each element of this Iterable into zero or more elements.
inherited
fillRange(int start, int end, [E? fillValue]) → dynamic
Fills the range of elements with the specified value
firstWhere(bool test(E element), {E orElse()?}) → E
The first element that satisfies the given predicate test.
inherited
fold<T>(T initialValue, T combine(T previousValue, E element)) → T
Reduces a collection to a single value by iteratively combining each element of the collection with an existing value
inherited
followedBy(Iterable<E> other) → Iterable<E>
Creates the lazy concatenation of this iterable and other.
inherited
forEach(void action(E element)) → void
Invokes action on each element of this iterable in iteration order.
inherited
getRange(int start, int end) → Iterable<E>
Creates an Iterable that iterates over a range of elements.
indexOf(E element, [int start = 0]) → int
The first index of element in this list.
indexWhere(bool test(E element), [int start = 0]) → int
The first index in the list that satisfies the provided test.
insert(int index, E element) → dynamic
Inserts an element at the specified index
insertAll(int index, Iterable<E> iterable) → dynamic
Inserts all elements from the iterable at the specified index
join([String separator = ""]) → String
Converts each element to a String and concatenates the strings.
inherited
lastIndexOf(E element, [int? start]) → int
The last index of element in this list.
lastIndexWhere(bool test(E element), [int? start]) → int
The last index in the list that satisfies the provided test.
lastWhere(bool test(E element), {E orElse()?}) → E
The last element that satisfies the given predicate test.
inherited
map<T>(T toElement(E e)) → Iterable<T>
The current elements of this iterable modified by toElement.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
reduce(E combine(E value, E element)) → E
Reduces a collection to a single value by iteratively combining elements of the collection using the provided function.
inherited
remove(Object? value) → dynamic
Removes the specified element from the set
removeAt(int index) → dynamic
Removes the element at the specified index
removeLast() → dynamic
Removes the last element from the set
removeRange(int start, int end) → dynamic
Removes a range of elements from the set
removeWhere(bool test(E element)) → dynamic
Removes all elements in the iterable from the set
replaceRange(int start, int end, Iterable<E> replacements) → dynamic
Replaces the range of elements with the specified replacements
retainWhere(bool test(E element)) → dynamic
Retains only the elements that satisfy the test
setAll(int index, Iterable<E> iterable) → dynamic
Sets the elements in the range to the specified iterable
setFirst(E value) → dynamic
Sets the first element of the list
setRange(int start, int end, Iterable<E> iterable, [int skipCount = 0]) → dynamic
Sets the elements in the range to the specified iterable
setValueAt(int index, E value) → dynamic
Sets the value at the given index in the list to value.
shuffle([Random? random]) → void
Shuffles the elements of this list randomly.
singleWhere(bool test(E element), {E orElse()?}) → E
The single element that satisfies test.
inherited
skip(int count) → Iterable<E>
Creates an Iterable that provides all but the first count elements.
inherited
skipWhile(bool test(E value)) → Iterable<E>
Creates an Iterable that skips leading elements while test is satisfied.
inherited
sort([int compare(E a, E b)?]) → void
Sorts this list according to the order specified by the compare function.
sublist(int start, [int? end]) → List<E>
The sublist of this list from start to end.
take(int count) → Iterable<E>
Creates a lazy iterable of the count first elements of this iterable.
inherited
takeWhile(bool test(E value)) → Iterable<E>
Creates a lazy iterable of the leading elements satisfying test.
inherited
toList({bool growable = true}) → List<E>
Creates a List containing the elements of this Iterable.
inherited
toSet() → Set<E>
Creates a Set containing the same elements as this iterable.
inherited
toString() → String
A string representation of this object.
inherited
where(bool test(E element)) → Iterable<E>
Creates a new lazy Iterable with all elements that satisfy the predicate test.
inherited
whereType<T>() → Iterable<T>
Creates a new lazy Iterable with all elements that have type T.
inherited

Operators

operator +(List<E> other) → List<E>
Creates a new CollectiveList by concatenating this list with another.
operator ==(Object other) → bool
The equality operator.
inherited
operator [](int index) → E
The object at the given index in the list.
operator []=(int index, E value) → void
Sets the value at the given index in the list to value.

Static Methods

create<E, I extends List<E>>({Iterable<E>? elements, Cell? bind, ContainerType container = ContainerType.growableTrue, CollectiveReceptor<dynamic, Signal, Signal> receptor = CollectiveReceptor.unchanged, TestCollective<dynamic, Collective> test = TestCollective.passed, MapObject? mapObject, Synapses<Signal, Cell> synapses = Synapses.enabled}) → CollectiveList<E>
Creates an user defined CollectiveList
override