CollectiveSet<E> class abstract interface

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.

Key Features

Reactive Modifications: All mutating operations (add, remove, etc.) automatically notify listeners Signals include elementAdded and elementRemoved events
Validation: Operations validate against configured TestCollective rules Supports element-level and operation-level validation
Identity Set Support: Can be configured to use identity comparison (identical) instead of equality
Delegated Views: deputy() creates modified views without affecting original set unmodifiable provides an immutable view
Type Parameters:
- <E>: The type of elements in the set

Example:

final set = CollectiveSet<int>();
final listener = Cell.listen<CollectivePost>(
  bind: set,
  listen: (post, _) => print('Change: ${post.body}')
);
set.add(1); // Triggers elementAdded signal

Example:

// Create set with validation
final set = CollectiveSet<String>(
    identitySet: true,
    test: TestCollective.create(
        elementDisallow: (element, _) => element?.length > 10
    )
);

// Invalid elements won't be added
set.add('too-long-string'); // Fails validation
set.add('ok'); // Succeeds

Example: Custom Validation

// Create collection with complex validation
final users = CollectiveSet<User>(
    test: TestCollective.create(
        elementDisallow: (user, _) => user?.isBanned ?? true,
        actionDisallow: (coll) => [coll.addAll], // Disable bulk adds
        maxLength: 1000 // Limit size
    )
);

// Attempt operations
users.add(bannedUser); // Fails validation
users.addAll([user1, user2]); // Fails - addAll disabled

Example: Async Operations

final asyncSet = CollectiveSet<String>();

void main() async {
  await asyncSet.async.add('hello');
  await asyncSet.async.addAll(['world', '!']);

  final removed = await asyncSet.async.remove('hello');
  print(removed); // true
}

Example: Bidirectional Binding

final sourceSet = CollectiveSet.of([1, 2, 3]);
final mirrorSet = CollectiveSet(bind: sourceSet);

sourceSet.add(4);
print(mirrorSet); // {1, 2, 3, 4}

Example: Complete Example

import 'package:collective/collective.dart';

void main() async {

  // Create a validated set
  final uniqueIds = CollectiveSet<int>(
    test: TestCollective.create(
      elementDisallow: (id) => id > 1000,  // Reject invalid IDs
    )
  );

  // Processor cell
  final logger = Cell.listen(
    bind: uniqueIds,
    listen: (post, _) {
      if (post.body?.containsKey(Collective.elementAdded) ?? false) {
        print('New IDs: ${post.body?[Collective.elementAdded]}');
      }
    }
  );

  // Add data
  uniqueIds.addAll([101, 102, 103]);  // Allowed
  uniqueIds.add(1001);                // Blocked by validation

  // Async batch insert
  await uniqueIds.async.addAll([104, 105]);
}

Constructors

CollectiveSet.new(Iterable<E> elements, {Cell? bind, TestCollective<dynamic, Collective> test, bool identitySet}): Creates a CollectiveSet with initial elements.
factory
CollectiveSet.empty({Cell? bind, TestCollective<dynamic, Collective> test, bool identitySet}): Creates an empty CollectiveSet.
factory
CollectiveSet.fromProperties(CollectiveSetProperties<E> properties, {Iterable<E>? elements}): Creates a CollectiveSet from existing properties.
factory
CollectiveSet.unmodifiable(CollectiveSet<E> bind, {bool unmodifiableElement = true}): Creates an unmodifiable view of an existing CollectiveSet.
factory

Properties

async → CollectiveSetAsync<E>: Creates a Async CollectiveSet for async modifiable operations
no setteroverride
first → E: The first element.
no setterinherited
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.
no setterinherited
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
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 → CollectiveSet<E>: Gets an unmodifiable view of this set.
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 element) → dynamic: Adds an element to the set
addAll(Iterable<E> elements) → 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
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
containsAll(Iterable<Object?> other) → bool: Whether this set contains all the elements of other.
deputy({covariant TestCollective<dynamic, Collective>? test, covariant MapObject? mapObject}) → CollectiveSet<E>: Creates a delegated view with modified behavior.
override
difference(Set<Object?> other) → Set<E>: Creates a new set with the elements of this that are not in other.
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
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
intersection(Set<Object?> other) → Set<E>: Creates a new set with the elements of this that are in other.
join([String separator = ""]) → String: Converts each element to a String and concatenates the strings.
inherited
lastWhere(bool test(E element), {E orElse()?}) → E: The last element that satisfies the given predicate test.
inherited
lookup(Object? object) → E?: Returns if the object in the set, otherwise returns null.
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? object) → dynamic: Removes the specified element from the set
removeAll(Iterable<Object?> elements) → dynamic: Removes all elements in the iterable from the set
removeWhere(bool test(E element)) → dynamic: Removes all elements in the iterable from the set
retainAll(Iterable<Object?> elements) → dynamic: Retains only the elements in the iterable
retainWhere(bool test(E element)) → dynamic: Retains only the elements that satisfy the test
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
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
union(Set<E> other) → Set<E>: Creates a new set with the elements of this and other.
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 ==(Object other) → bool: The equality operator.
inherited

Static Methods

create<E, I extends Set<E>>({Iterable<E>? elements, Cell? bind, ContainerType container = ContainerType.set, CollectiveReceptor<dynamic, Signal, Signal> receptor = CollectiveReceptor.unchanged, TestCollective<dynamic, Collective> test = TestCollective.passed, MapObject? mapObject, Synapses<Signal, Cell> synapses = Synapses.enabled}) → CollectiveSet<E>: Creates a fully configured CollectiveSet instance.
override