PulseBase<P> class abstract

The foundational blueprint for all nervous signals within the reactive graph.

PulseBase is the "Common DNA" shared by every signal, whether it is a high-speed _FastPulse or a fully audited, governed impulse. It provides the core logic for causal tracking, forensic logging, and signal evolution.

In the framework's biological metaphor, this class defines the Signal Architecture. Every impulse that travels through a cell's synapses is built upon this base, ensuring that the Forensic Ledger can always trace a signal's origin and journey.

Why it is used

  • Causal Integrity: It maintains the "Lineage" of signals. When a cell reacts to an input and produces an output, PulseBase ensures the new signal is "evolved" from the old one, preserving the audit trail.
  • Performance at Scale: It uses a specialized Bitmask Record system (_shape) to store metadata. This allows the framework to handle thousands of signals per second by avoiding expensive object allocations for every metadata field.
  • Unified Interface: It allows receptors and synapses to treat all signals—whether they are single values or collective batches—through a single, type-safe API.

How it works

  1. Signal Masking: When a pulse is created, its metadata (timestamp, source, priority, etc.) is packed into a sparse record. A bitmask (_shape) is generated to tell the engine which fields exist.
  2. Causal Evolution: Through the evolve method, a pulse creates a child signal. The child inherits the parent's "Causal Link," allowing the framework to detect infinite loops or trace history.
  3. Forensic Tracking: It provides a trace of "Genetic Markers" (steps), which are breadcrumbs representing every milestone the signal passed through.

Technical Details

  • Bitmask Optimization: Field access (like payload or source) checks the _shape bitmask first. This is an "exception-free" sparse read that is significantly faster than standard reflection.
  • Flyweight Pattern: The internal _record is a Dart Record, which the compiler can often optimize into registers, reducing heap pressure during high-frequency signaling.

See also:

  • Cell.apply — The primary gateway where these signals are vetted.
  • Pulse — The public-facing interface for this class.
Implemented types
Mixed-in types
Available extensions

Constructors

PulseBase({PulseEphemeralPolicy? policy, PulseContext? context, P? payload, dynamic type, DateTime? timestamp, Cell? source, String? step, int? priority, Function? onComplete, Function? onError, Function? onProgress, Pulse? pulse, Pulse? parent, FutureOr<Pulse?> scrutinize(Receptor<Cell> receptor)?, dynamic user})
PulseBase.fromRecord(Record record)
Creates a pulse from an existing record.
const

Properties

context → PulseContext
Execution/security context.
no setteroverride
first → Pulse
The first element.
no setterinherited
hashCode → int
The hash code for this object.
no setteroverride
isComposite → bool
Indicates whether this pulse is a multi-message bundle (a collection).
no setteroverride
isEmpty → bool
Whether this collection has no elements.
no setterinherited
isGoverned → bool
Indicates whether this pulse is subject to explicit governance.
no setteroverride
isInvalidated → bool
Indicates whether this message has reached its terminal lifecycle state.
no setteroverride
isNotEmpty → bool
Whether this collection has at least one element.
no setterinherited
iterator → Iterator<Pulse>
A new Iterator that allows iterating the elements of this Iterable.
no setterinherited
last → Pulse
The last element.
no setterinherited
length → int
The number of elements in this Iterable.
no setterinherited
payload → P?
Main payload.
no setteroverride
policy → PulseEphemeralPolicy?
The lifecycle governance policy for this pulse.
no setteroverride
priority → int
The execution priority of this pulse (0‑100, higher = more urgent).
no setteroverride
root → PulseBase<P>
The primordial ancestor that initiated this pulse's causal lineage.
no setteroverride
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
shell → PulseShell<P, Receptor<Cell>>
Returns a Defensive Proxy of this pulse for untrusted receivers.
no setteroverride
single → Pulse
Checks that this iterable has only one element, and returns that element.
no setterinherited
source → Cell?
Origin cell (for tracing).
no setteroverride
timestamp → DateTime
When this pulse was created.
no setteroverride
trace → List<String>
Causal trace path.
no setteroverride
type → dynamic
Semantic type classification for pattern matching and routing.
no setteroverride
unmodifiable → PulseBase<P>
Returns a read‑only projection of this pulse, ensuring structural and payload-level finality for the current propagation hop.
no setteroverride

Methods

any(bool test(Pulse element)) → bool
Checks whether any element of this iterable satisfies test.
inherited
attach(dynamic context) → Pulse<P>

Available on Pulse<P>, provided by the PulseExtension extension

Returns a new version of this pulse with updated context metadata.
attach(dynamic context) → Iterable<Pulse>

Available on Iterable<Pulse>, provided by the PulseIterableExtension extension

Returns a new collection of pulses, each with the provided context metadata attached.
batch() → Pulse

Available on Iterable<Pulse>, provided by the PulseIterableExtension extension

Aggregates multiple signals into a single, flat CollectivePulse.
cast<T>() → Pulse<T>

Available on Pulse<P>, provided by the PulseExtension extension

Re-casts the pulse payload to type T while maintaining causal history.
cast<R>() → Iterable<R>
A view of this iterable as an iterable of R instances.
inherited
compareTo(Pulse other) → int
Compares this pulse with another to determine relative execution precedence.
override
contains(Object? element) → bool
Whether the collection contains an element equal to element.
inherited
elementAt(int index) → Pulse
Returns the indexth element.
inherited
every(bool test(Pulse element)) → bool
Checks whether every element of this iterable satisfies test.
inherited
evolve({Pulse? pulse, String? step, covariant PulseContext? context}) → Pulse
Creates a derived version of this pulse for the next processing stage.
override
expand<T>(Iterable<T> toElements(Pulse element)) → Iterable<T>
Expands each element of this Iterable into zero or more elements.
inherited
firstWhere(bool test(Pulse element), {Pulse orElse()?}) → Pulse
The first element that satisfies the given predicate test.
inherited
flatten() → Iterable<Pulse>

Available on Iterable<Pulse>, provided by the PulseIterableExtension extension

Recursively flattens any nested CollectivePulse structures into a sequence of simple pulses.
fold<T>(T initialValue, T combine(T previousValue, Pulse element)) → T
Reduces a collection to a single value by iteratively combining each element of the collection with an existing value
inherited
followedBy(Iterable<Pulse> other) → Iterable<Pulse>
Creates the lazy concatenation of this iterable and other.
inherited
forEach(void action(Pulse 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(Pulse element), {Pulse orElse()?}) → Pulse
The last element that satisfies the given predicate test.
inherited
lineage<T>(LineageArgument arg) → List<T>
Traverses the causal chain from the root ancestor to this pulse to reconstruct a historical timeline of values.
override
map<T>(T toElement(Pulse e)) → Iterable<T>
The current elements of this iterable modified by toElement.
inherited
map<T>(T mapper(P payload)) → Pulse<T>

Available on Pulse<P>, provided by the PulseExtension extension

Transforms the payload of this pulse into a new type T while preserving its causal history.
mapEach<T>(T mapper(dynamic payload)) → Iterable<Pulse<T>>

Available on Iterable<Pulse>, provided by the PulseIterableExtension extension

Transforms the payload of every pulse in the collection while preserving their individual causal traces.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
reduce(Pulse combine(Pulse value, Pulse element)) → Pulse
Reduces a collection to a single value by iteratively combining elements of the collection using the provided function.
inherited
scrutinize(covariant Receptor<Cell> receptor, List? positionalArguments, [Map<Symbol, dynamic>? namedArguments]) → dynamic
Challenges a receptor to prove it has the authority to see this pulse.
override
singleWhere(bool test(Pulse element), {Pulse orElse()?}) → Pulse
The single element that satisfies test.
inherited
skip(int count) → Iterable<Pulse>
Creates an Iterable that provides all but the first count elements.
inherited
skipWhile(bool test(Pulse element)) → Iterable<Pulse>
Creates an Iterable that skips leading elements while test is satisfied.
inherited
take(int count) → Iterable<Pulse>
Creates a lazy iterable of the count first elements of this iterable.
inherited
takeWhile(bool test(Pulse element)) → Iterable<Pulse>
Creates a lazy iterable of the leading elements satisfying test.
inherited
tap(void action(P payload)) → Pulse<P>

Available on Pulse<P>, provided by the PulseExtension extension

Executes a side-effect action using the current payload and returns this pulse instance.
toJson({bool lenient = false}) → Map<String, dynamic>

Available on Pulse<P>, provided by the PulseJson extension

toList({bool growable = true}) → List<Pulse>
Creates a List containing the elements of this Iterable.
inherited
toSet() → Set<Pulse>
Creates a Set containing the same elements as this iterable.
inherited
toString() → String
A string representation of this object.
override
where(bool test(Pulse element)) → Iterable<Pulse>
Creates a new lazy Iterable with all elements that satisfy the predicate test.
inherited
whereType<T>() → Iterable<R>
Creates a new lazy Iterable with all elements that have type T.
inherited
withStep(String step) → Iterable<Pulse>

Available on Iterable<Pulse>, provided by the PulseIterableExtension extension

Appends a diagnostic stage to the causal trace of every pulse in this collection.
withStep(String step) → Pulse<P>
Appends step to the pulse's causal trace without branching the causal chain.
override

Operators

operator +(covariant Pulse other) → CollectivePulse
Combines this pulse and other into a composite CollectivePulse.
override
operator ==(Object other) → bool
The equality operator.
override

Static Methods

mask({PulseEphemeralPolicy? policy, PulseContext? context, dynamic payload, dynamic type, DateTime? timestamp, Cell? source, String? step, Function? onComplete, Function? onError, Function? onProgress, int? priority, dynamic user, Pulse? pulse, Pulse? parent, Function? scrutinize}) → Record