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
- 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. - 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.
- 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
payloadorsource) checks the_shapebitmask first. This is an "exception-free" sparse read that is significantly faster than standard reflection. - Flyweight Pattern: The internal
_recordis 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
-
- Pulse<
P>
- Pulse<
- 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
Iteratorthat allows iterating the elements of thisIterable.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<
Returns a new version of this pulse with updatedP> , provided by the PulseExtension extensioncontextmetadata. -
attach(
dynamic context) → Iterable< Pulse> -
Available on Iterable<
Returns a new collection of pulses, each with the providedPulse> , provided by the PulseIterableExtension extensioncontextmetadata attached. -
batch(
) → Pulse -
Available on Iterable<
Aggregates multiple signals into a single, flat CollectivePulse.Pulse> , provided by the PulseIterableExtension extension -
cast<
T> () → Pulse< T> -
Available on Pulse<
Re-casts the pulse payload to typeP> , provided by the PulseExtension extensionTwhile maintaining causal history. -
cast<
R> () → Iterable< R> -
A view of this iterable as an iterable of
Rinstances.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<
Recursively flattens any nested CollectivePulse structures into a sequence of simple pulses.Pulse> , provided by the PulseIterableExtension extension -
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
actionon 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<
Transforms the payload of this pulse into a new typeP> , provided by the PulseExtension extensionTwhile preserving its causal history. -
mapEach<
T> (T mapper(dynamic payload)) → Iterable< Pulse< T> > -
Available on Iterable<
Transforms the payload of every pulse in the collection while preserving their individual causal traces.Pulse> , provided by the PulseIterableExtension extension -
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
countelements.inherited -
skipWhile(
bool test(Pulse element)) → Iterable< Pulse> -
Creates an
Iterablethat skips leading elements whiletestis satisfied.inherited -
take(
int count) → Iterable< Pulse> -
Creates a lazy iterable of the
countfirst 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<
Executes a side-effectP> , provided by the PulseExtension extensionactionusing the current payload and returns this pulse instance. -
toJson(
{bool lenient = false}) → Map< String, dynamic> -
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<
Appends a diagnostic stage to the causal trace of every pulse in this collection.Pulse> , provided by the PulseIterableExtension extension -
withStep(
String step) → Pulse< P> -
Appends
stepto the pulse's causal trace without branching the causal chain.override
Operators
-
operator +(
covariant Pulse other) → CollectivePulse -
Combines this pulse and
otherinto a composite CollectivePulse.override -
operator ==(
Object other) → bool -
The equality operator.
override