Instruction<C extends Cell, I extends Pulse, O extends Pulse> class abstract interface Instructions Pipelines & Receptors

A discrete logic unit that defines how a Receptor reacts to a Pulse.

In the biological metaphor, Instructions are the DNA of the Nucleus. They provide the "blueprints" for signal transformation, allowing a Receptor to process stimuli with forensic integrity. Instructions are stateless and composable, allowing complex processing logic to be assembled from small, focused units.

When to use

Use Instruction to encapsulate reusable transformations, filters, or side-effects that can be shared across multiple receptors. It is the standard tool for building multi-stage processing pipelines.

  • Reusable Logic: Defining a standard sanitization or validation rule used by many cells.
  • Pipeline Composition: Building complex logic by chaining simple instructions with the + operator.
  • Framework Extensions: Creating specialized signal processors that hook into the core reactive fabric.

Note: For one-off logic, you rarely need to implement Instruction directly. Instead, pass a closure to the Receptor constructor.

How it works

  1. An instruction receives the host cell, the incoming Pulse, and optional user metadata.
  2. It returns a new Pulse (to continue propagation) or null (to terminate the signal).
  3. Instructions are chained using the + operator. The output of the first becomes the input of the second.
  4. If any instruction in a chain returns null, the entire chain short-circuits.
  5. Execution is synchronous - instructions do not return Future. For asynchronous behavior, use the Instruction.future factory or the Receptor.async execution path.

Example: Validation & Sanitization Pipeline

final trim = Instruction<Cell, String, String>((pulse, {cell, user}) {
  return Pulse(pulse.payload.trim());
});

final validate = Instruction<Cell, String, String>((pulse, {cell, user}) {
  return pulse.payload.isNotEmpty ? pulse : null;
});

// Create a reusable pipeline
final pipeline = trim + validate;

Type Parameters:

  • C: The type of the Cell that serves as the host/context.
  • I: The type of the incoming Pulse (Input).
  • O: The type of the resulting Pulse (Output).

See also:

  • Receptor – The component that utilizes instructions to process signals.
  • InstructionChain – The composite implementation for sequential execution.
  • Example: See example/instruction_pipeline_walkthrough.dart for a complete executable walkthrough of pattern matching, priority ordering, and multicast routing.
  • HowTo: See guide/HowTo-Instruction.md for a guide on implementing custom instructions.
Implementers

Constructors

Instruction(O? instruction(I pulse, {C? cell, dynamic user}), {dynamic user})
Creates an Instruction from a standalone transformation function.
const
factory
Instruction.chain(Iterable<Instruction<Cell, Pulse, Pulse>> instructions, {dynamic user, O? strategy(I pulse, {C? cell, dynamic user})?})
Creates an InstructionChain that orchestrates multiple instructions.
const
factory
Instruction.future(O? instruction(I pulse, {C? cell, void future({required Pulse? result, required dynamic token})?, dynamic token, dynamic user}), {dynamic user})
Creates an Instruction with asynchronous future propagation support.
const
factory

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

call(I pulse, {C? cell, void future({required Pulse? result, required dynamic token})?, dynamic token}) → O?
Executes the transformation logic of this instruction synchronously.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator +(covariant Instruction<Cell, Pulse, Pulse> other) → Instruction<C, I, O>
Combines this instruction with another to create an InstructionChain.
operator ==(Object other) → bool
The equality operator.
inherited