NeuronAtom<T> class

A modern, lightweight reactive value container.

NeuronAtom is the foundation of Neuron's reactive system. It holds a value of type T and notifies listeners when the value changes. Think of it as a smarter version of Flutter's ValueNotifier with additional features.

Core Features

• Value observation: Listeners are notified when value changes
• Equality checking: Custom equality to control when listeners fire
• Value guards: Transform or validate values before emission
• Initial value: Access original value via initialValue
• Previous value: Track changes via previousValue
• Lifecycle hooks: onActive and onInactive for resource management
• RAII Finalizer: Automatically calls dispose if an atom is garbage collected

Basic Usage

final counter = NeuronAtom<int>(0);

// Listen to changes
final cancel = counter.subscribe(() {
  print('New value: ${counter.value}');
});

counter.value = 1;  // Prints: New value: 1
counter.value = 1;  // No print (value unchanged)
counter.value = 2;  // Prints: New value: 2

cancel(); // Stop listening

Custom Equality

Control when listeners are notified:

final user = NeuronAtom<User>(
  User(id: 1),
  equals: (a, b) => a.id == b.id,  // Only notify if ID changes
);

Value Guards

Transform or validate values before emission:

final percentage = NeuronAtom<int>(
  50,
  guard: (current, next) => next.clamp(0, 100),  // Ensure 0-100 range
);

percentage.value = 150;  // Actually sets to 100

Selective Listening

Create derived atoms that only update for specific changes:

final user = NeuronAtom<User>(User(name: 'Alice', age: 30));
final nameOnly = user.select((u) => u.name);  // Only fires on name change

Note: For most use cases, use Signal<T> instead, which extends NeuronAtom with stream support and controller binding.

See also:

• Signal - Preferred reactive value with stream support
• AsyncSignal - For async operations
• Computed - For derived values