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
- An instruction receives the host cell, the incoming Pulse, and
optional
usermetadata. - It returns a new Pulse (to continue propagation) or
null(to terminate the signal). - Instructions are chained using the
+operator. The output of the first becomes the input of the second. - If any instruction in a chain returns
null, the entire chain short-circuits. - 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.dartfor a complete executable walkthrough of pattern matching, priority ordering, and multicast routing. - HowTo: See
guide/HowTo-Instruction.mdfor 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.
constfactory
-
Instruction.chain(Iterable<
Instruction< instructions, {dynamic user, O? strategy(I pulse, {C? cell, dynamic user})?})Cell, Pulse, Pulse> > -
Creates an InstructionChain that orchestrates multiple instructions.
constfactory
- 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.
constfactory
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