BloomCoupler<T> class base

A dynamic reactive socket controller that allows hot-coupling or cold-coupling upstream Bloom pipelines at runtime without rebuilding downstream consumers.

Standard Bloom pipelines form a statically connected DAG. BloomCoupler introduces a dynamic 1-tier relay proxy in the pipeline, allowing developers to switch the upstream source node dynamically while maintaining unbroken continuity for downstream listeners.

Following the Producer-Consumer decoupling model of BloomController, BloomCoupler acts as the controller/producer handle and exposes a read-only bloom consumer view, completely encapsulating mutation and coupling capabilities from downstream consumers.

System Architectural Flow

[Upstream Bloom A] (Detached on couple)
       │
       ▼ (coupler.couple(bloomB))
┌─────────────────────┐
│   BloomCoupler<T>    │ ──► bloom (Read-Only) ──► [Downstream Transformations / Terminals]
└─────────────────────┘
       ▲
       │ (Newly Attached)
[Upstream Bloom B]

Common Use Cases:

Environment Coupling: Dynamically coupling a mock data source with a live API source.
Session Management: Switching the active user stream upon authentication state changes.
Feature Toggles: Rerouting reactive data flows based on runtime configuration.

Warning (Anti-Pattern Prevention):

DO NOT perform circular coupling (e.g. coupling a downstream node that already depends on this coupler). Circular coupling causes infinite dependency loops and topological corruption.

BAD:

// [Anti-Pattern] Circular coupling: coupler depends on downstream child
final coupler = BloomCoupler<int>.late();
final childBloom = computed((via) => via(coupler.bloom) + 1);
coupler.couple(childBloom); // Circular dependency loop!

GOOD:

// [Recommended] Hot-coupling independent upstream sources
final mockSource = Bloom.constant('Guest');
final liveSource = blooming<String>('User123');

final coupler = BloomCoupler<String>(mockSource);
final greetingBloom = computed((via) => 'Hello, ${via(coupler.bloom)}!');

coupler.couple(liveSource.bloom); // Safely coupled to live source

Implemented types

BloomState<T>
LpdagStatus

Available extensions

Constructors

BloomCoupler(Bloom<T> inbound): Creates a BloomCoupler initialized with inbound.
BloomCoupler.error(Object error, [StackTrace? stackTrace]): Creates a BloomCoupler initialized in an error state.
BloomCoupler.late(): Creates a BloomCoupler in an uninitialized (empty) state.

Properties

bloom → Bloom<T>: Exposes the underlying read-only Bloom node for downstream consumers.
no setter
data → T: Extracts the underlying data synchronously from this node or state.
no setterinherited
dataOrNull → T?: Safely extracts the underlying data, returning null if not in a hasData state.
no setterinherited
debug → BloomDebug: Available on BloomCoupler, provided by the BloomCouplerDebugExtension extension
Access point for zero-overhead node inspection and diagnostics.
no setter
debugCreationLocation → String?: Available on BloomCoupler, provided by the BloomCouplerDebugExtension extension
The exact code location where this coupler was instantiated in debug mode.
no setter
debugLabel ↔ String?: Available on BloomCoupler, provided by the BloomCouplerDebugExtension extension
A developer-defined label to identify this coupler socket in debug mode.
getter/setter pair
debugReflector → LpdagReflector?: Available on LpdagStatus, provided by the LpdagStatusReflectorExtension extension
Zero-overhead diagnostic reflector for Flutter DevTools and LPDAG inspection.
no setter
debugVersion → int: Available on BloomCoupler, provided by the BloomCouplerDebugExtension extension
The internal version of this BloomCoupler for testing and verification.
no setter
emptyReason → Object?: The optional reason explaining why this state is empty, or null if unspecified or not empty.
no setterinherited
error → Object: Extracts the underlying exception or failure object from an error state.
no setterinherited
hasData → bool: Whether this state contains a valid, extractable data payload.
no setterinherited
hasError → bool: Whether this state is in a corrupted state containing an error or exception.
no setterinherited
hashCode → int: The hash code for this object.
no setterinherited
isActive → bool: Whether this coupler currently has active downstream subscribers.
no setteroverride
isEmpty → bool: Whether this state is in an uninitialized or dormant state.
no setterinherited
phase → BloomPhase: The operational phase (BloomPhase.valid, BloomPhase.empty, or BloomPhase.error) of this state.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
snapshot → BloomSnapshot<T>: The immutable snapshot representation of the current state of this BloomState entity.
no setterinherited
stackTrace → StackTrace: Extracts the call stack trace at the point of failure from an error state.
no setterinherited

Methods

couple(Bloom<T> newInbound) → Bloom<T>?: Couples the currently attached inbound source node with newInbound.
coupleGuarded(Bloom<T> callback()) → Bloom<T>?: Safely executes callback and couples the inbound node to the returned Bloom.
dataOrElse(T fallback()) → T: Safely extracts the underlying data, returning the result of fallback if not in a hasData state.
inherited
debugTrace([String? label, int traceCount = 5]) → void: Available on BloomCoupler, provided by the BloomCouplerDebugExtension extension
Captures the current stack trace and assigns an optional label to this coupler socket.
decouple() → void: Immediately decouples and detaches the currently attached inbound node.
equals(covariant BloomState<T> other, [bool equals(T previous, T next)?]) → bool: Determines if this state is equivalent to other using an optional custom equals comparator.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
setError(Object error, [StackTrace? stackTrace]) → Bloom<T>: Injects an error state into the coupler with optional stackTrace.
toString() → String: A string representation of this object.
inherited
tryDecoupling(Bloom bloom) → bool: Decouples the inbound node only if it matches bloom.
withDebugLabel(String label) → BloomCoupler: Available on BloomCoupler, provided by the BloomCouplerDebugExtension extension
Assigns a developer-defined debug label and returns this coupler socket.

Operators

operator ==(Object other) → bool: The equality operator.
inherited