CollectiveValue<V> class abstract interface

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.

Key features:

  • Reactive: Automatically notifies listeners when the value changes.
  • Validation: Supports validation rules to ensure the value meets certain criteria.
  • Async Operations: Can perform asynchronous operations on the value.
  • Immutable Variants: Provides immutable versions of the value for safe sharing.
  • Customizable: Allows customization of container behavior and validation rules.

Example: Basic Usage

final counter = CollectiveValue<int>(0);

// Listen to changes
final listener = Cell.listen(
  bind: counter,
  listen: (ValueChange<int> change, _) {
    print('Changed from ${change.before} to ${change.after}');
  }
);

counter.value = 1; // Output: Changed from 0 to 1

Example: Validation

final age = CollectiveValue<int>(
  null,
  test: TestCollective.create(
    elementDisallow: (age) => age != null && (age < 0 || age > 120)
  )
);

age.value = 25;  // Allowed
age.value = -5;  // Blocked by validation

Example: Async Operations

final config = CollectiveValue<String>('default');

void main() async {
  await config.async.setValue('new config');
  print(config.value); // 'new config'
}

Example: Value Change Tracking

// Track value changes
final value = CollectiveValue<int>(0);

value.setValue(1); // Triggers ValueChange with before=0, after=1

// Listen for changes
final listener = Collective.listen<CollectivePost>(
  bind: value,
  listen: (post, _) {
    final changes = post.body?[Collective.elementUpdated] as Iterable<ElementValueChange>;
    changes.forEach((change) {
      print('Changed from ${change.before} to ${change.after}');
    });
  }
);

Example: Immutable Variant

final immutableValue = CollectiveValue.unmodifiable(counter);

//Attempting to modify immutableValue will throw an error
immutableValue.value = 5; // Throws error
print(immutableValue.value); // 0

Example: Complete Example

import 'package:collective/collective.dart';

void main() async {
  // Create validated value
  final temperature = CollectiveValue<double>(
    null,
    test: TestCollective.create(
      elementDisallow: (temp) => temp != null && (temp < -50 || temp > 100)
  );

  // Logger cell
  final logger = Cell.listen(
    bind: temperature,
    listen: (ValueChange<double> change, _) {
      print('Temp changed: ${change.before}°C → ${change.after}°C');
    }
  );

  // Simulate sensor updates
  await temperature.async.setValue(23.5);
  await Future.delayed(Duration(seconds: 1));
  await temperature.async.setValue(24.1);

  // Try invalid value
  temperature.value = -100; // ❌ Blocked by validation
}

/// See also:

Implemented types
Implementers
Available extensions

Constructors

CollectiveValue.new(V? value, {Cell? bind, TestCollective<dynamic, Collective> test, SignalTransform<Cell, Signal, Signal>? transform})
Creates a reactive single value container
factory
CollectiveValue.empty({Cell? bind, TestCollective<dynamic, Collective> test})
Creates an empty CollectiveValue without initial value.
factory
CollectiveValue.fromProperties(CollectiveValueProperties<V> properties, {V? value})
Creates from properties with optional initial value.
factory
CollectiveValue.unmodifiable(CollectiveValue<V> bind, {bool unmodifiableElement})
Creates an unmodifiable version of this CollectiveValue.
factory

Properties

async → CollectiveValueAsync<V>
Creates an async variant for modifiable operations
no setteroverride
first → V
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<V>
A new Iterator that allows iterating the elements of this Iterable.
no setterinherited
last → V
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 → V
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 → CollectiveValue<V>
Returns an unmodifiable version of this value.
no setteroverride
value ↔ V?
The value of this CollectiveValue
getter/setter pair
wait → Future<List<T>>

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

Waits for futures in parallel.
no setter

Methods

any(bool test(V 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
contains(Object? element) → bool
Whether the collection contains an element equal to element.
inherited
deputy({covariant TestCollective<dynamic, Collective>? test, covariant MapObject? mapObject}) → CollectiveValue<V>
Creates an deputy for this CollectiveValue.
override
elementAt(int index) → V
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(V element)) → bool
Checks whether every element of this iterable satisfies test.
inherited
expand<T>(Iterable<T> toElements(V element)) → Iterable<T>
Expands each element of this Iterable into zero or more elements.
inherited
firstWhere(bool test(V element), {V orElse()?}) → V
The first element that satisfies the given predicate test.
inherited
fold<T>(T initialValue, T combine(T previousValue, V element)) → T
Reduces a collection to a single value by iteratively combining each element of the collection with an existing value
inherited
followedBy(Iterable<V> other) → Iterable<V>
Creates the lazy concatenation of this iterable and other.
inherited
forEach(void action(V 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(V element), {V orElse()?}) → V
The last element that satisfies the given predicate test.
inherited
map<T>(T toElement(V 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(V combine(V value, V element)) → V
Reduces a collection to a single value by iteratively combining elements of the collection using the provided function.
inherited
set(V? value) → dynamic
Sets the value of this CollectiveValue and returns true if successful.
singleWhere(bool test(V element), {V orElse()?}) → V
The single element that satisfies test.
inherited
skip(int count) → Iterable<V>
Creates an Iterable that provides all but the first count elements.
inherited
skipWhile(bool test(V value)) → Iterable<V>
Creates an Iterable that skips leading elements while test is satisfied.
inherited
take(int count) → Iterable<V>
Creates a lazy iterable of the count first elements of this iterable.
inherited
takeWhile(bool test(V value)) → Iterable<V>
Creates a lazy iterable of the leading elements satisfying test.
inherited
toList({bool growable = true}) → List<V>
Creates a List containing the elements of this Iterable.
inherited
toSet() → Set<V>
Creates a Set containing the same elements as this iterable.
inherited
toString() → String
A string representation of this object.
inherited
where(bool test(V element)) → Iterable<V>
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
Comparison operators for numeric values
operator <=(Object other) → bool
Comparison operators for numeric values
operator ==(Object other) → bool
The equality operator.
inherited
operator >(Object other) → bool
Comparison operators for numeric values

Static Methods

create<V, I extends Iterable<V>>({V? value, Cell? bind, ContainerType container = ContainerType.growableFalse, CollectiveReceptor<dynamic, Signal, Signal> receptor = CollectiveReceptor.unchanged, TestCollective<dynamic, Collective> test = TestCollective.passed, MapObject? mapObject, Synapses<Signal, Cell> synapses = Synapses.enabled, bool setter(CollectiveValue<V> value, I container, V? v)?, V? getter(CollectiveValue<V> value, I container)?}) → CollectiveValue<V>
Factory constructor for full configuration.
override