CollectiveQueue<E> class abstract interface

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.

This implementation provides a robust, reactive queue that integrates seamlessly with the cell-based architecture while maintaining the performance characteristics of Dart's native Queue.

Key features:

Reactive Operations: All modifications trigger signal propagation Type Safety: Generic E type for queue elements Validation: Integrated with TestCollective system Customizable: Supports user-defined properties and behaviors Unmodifiable Variant – UnmodifiableCollectiveQueue for immutable use Async Operations – async interface for non-blocking mutations

Best Practices

• Use the CollectiveQueue for reactive data structures that require dynamic updates and notifications.
• Use the UnmodifiableCollectiveQueue for immutable data structures that should not change after creation.
• Use async operations to avoid blocking the main thread.
• Use the TestCollective for validation to ensure data integrity.
• Use the CollectiveReceptor for custom signal handling and processing.
• Use the MapObject for custom mapping and transformation of elements.
• Use the Synapses for managing relationships between cells.
• Use the CollectiveCellProperties for customizing the properties of the queue.

Example: Basic usage

final queue = CollectiveQueue<int>();

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

queue.addAll([1, 2, 3]);
// Output: Event: CollectiveEvent._(identifier: #elementAdded), Elements: {1, 2, 3}

queue.removeFirst();
// Output: Event: CollectiveEvent._(identifier: #elementRemoved), Elements: {1}

Example: With Validation

final positiveQueue = CollectiveQueue<int>(
  test: TestCollective.create(
    elementDisallow: (n, _) => n <= 0,
    maxLength: 5
  )
);

positiveQueue.add(1); // Success
positiveQueue.add(0); // Throws/blocked by validation
positiveQueue.addAll([2, 3, 4, 5, 6]); // Last item blocked by maxLength

Example: Async Operations

final queue = CollectiveQueue<String>();

void main() async {
  await queue.async.add('first');
  await queue.async.addAll(['second', 'third']);

  final item = await queue.async.removeFirst();
  print(item); // 'first'
}

Example: Complete Example

import 'package:collective/collective.dart';

void main() async {
  // Create queue with validation
  final taskQueue = CollectiveQueue<String>(
    test: TestCollective.create(
      elementDisallow: (task, _) => task.isEmpty,
      maxLength: 10
    )
  );

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

  // Add tasks
  taskQueue.addAll(['Task1', 'Task2']);

  // Process items
  while (taskQueue.isNotEmpty) {
    final task = taskQueue.removeFirst();
    print('Processing: $task');
    await Future.delayed(Duration(seconds: 1));
  }

  // Async addition
  await taskQueue.async.add('UrgentTask');
}

Implemented types

• CollectiveCell<E>

Implementers

• CollectiveQueueAsync
• CollectiveQueueDeputy
• UnmodifiableCollectiveQueue

Available extensions

• EnumByName
• FutureIterable
• IterableExtensions
• NullableIterableExtensions

Constructors

CollectiveQueue.new({Cell? bind, TestCollective<dynamic, Collective> test, bool growable})

Creates an empty growable list by default from elements

factory

CollectiveQueue.fromProperties(CollectiveQueueProperties<E> properties, {Iterable<E>? elements})

Creates a CollectiveQueue from properties

factory

CollectiveQueue.of(Iterable<E> elements, {Cell? bind, TestCollective<dynamic, Collective> test, bool growable})

Creates a growable list by default from elements

factory

CollectiveQueue.unmodifiable(CollectiveQueue<E> bind, {bool unmodifiableElement = true})

Creates an unmodifiable CollectiveQueue from elements

factory

Properties

async → CollectiveQueueAsync<E>

Creates an async variant for modifiable operations

no setter, override

first → E

The first element.

no setter, inherited

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 setter, inherited

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 setter, inherited

isNotEmpty → bool

Whether this collection has at least one element.

no setter, inherited

iterator → Iterator<E>

A new Iterator that allows iterating the elements of this Iterable.

no setter, inherited

last → E

The last element.

no setter, inherited

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 setter, inherited

modifiable → Iterable<Function>

Returns an iterable containing modifiable functions.

no setter, inherited

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 setter, inherited

single → E

Checks that this iterable has only one element, and returns that element.

no setter, inherited

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 setter, inherited

unmodifiable → CollectiveQueue<E>

Creates an unmodifiable view of this cell.

no setter, override

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 value at the end of the queue.

addAll(Iterable<E> iterable) → dynamic

Adds all values iterable at the end of the queue.

addFirst(E value) → dynamic

Adds value at the beginning of the queue.

addLast(E value) → dynamic

Adds value at the end of the queue.

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>() → Queue<R>

Provides a view of this queue as a queue of R instances, if necessary.

override

clear() → dynamic

Clears the queue.

contains(Object? element) → bool

Whether the collection contains an element equal to element.

inherited

deputy({covariant TestCollective<dynamic, Collective>? test, covariant MapObject? mapObject}) → CollectiveQueue<E>

Creates an Deputy from this CollectiveQueue with either test or map or both properties. The new CollectiveQueue

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

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

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

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 first occurrence of value from the queue.

removeFirst() → dynamic

Removes the first element from the queue.

removeLast() → dynamic

Removes the last element from the queue.

removeWhere(bool test(E element)) → dynamic

Removes all elements that satisfy the test condition.

retainWhere(bool test(E element)) → dynamic

Retains all elements that satisfy the test condition.

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

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 Queue<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}) → CollectiveQueue<E>

Creates an user defined CollectiveQueue

override