BloomSnapshot<T> class sealed

An immutable, atomic container that encapsulates the precise state and data of a Bloom node at a specific point in time.

In the Bloom framework, data never flows as raw values; it is always strictly packaged inside a BloomSnapshot. This guarantees absolute state determinism across the topological graph. A snapshot exists in exactly one of three mutually exclusive states:

Valid (hasData): Contains safely resolvable data (even if that data is null).
Empty (isEmpty): Represents a state where data has not yet been provided or has been cleared.
Error (hasError): Contains an error and an optional stack trace resulting from a failed computation.

State Transition Flow

┌───────────────────────────────────────────────────────────┐
│                      BloomSnapshot<T>                      │
├───────────────────┬───────────────────┬───────────────────┤
│  Valid (hasData)  │  Empty (isEmpty)  │ Error (hasError)  │
├───────────────────┬───────────────────┬───────────────────┤
│ • Holds T payload │ • No data yet     │ • Holds error &   │
│ • .data is safe   │ • .data throws    │   stackTrace      │
│ • null is valid   │ • .dataOrNull -> Ø│ • .data throws    │
└───────────────────────────────────────────────────────────┘

Pipeline-Level Null Safety

This class elevates Dart's Sound Null Safety philosophy to the pipeline level. In a BloomSnapshot, null is NEVER treated as a missing state. Instead, null is respected as a perfectly valid, explicit data payload (e.g., BloomSnapshot<String?>(null)). The concept of "no data" is completely segregated into its own dedicated type (BloomSnapshot.empty).

Warning (Anti-Pattern Prevention):

DO NOT directly read .data when hasData is false. Accessing .data on an empty or error snapshot triggers a Fail-Fast BloomSnapshotExtractionException.
Always inspect state using pattern matching or defensively extract via dataOrNull / dataOrElse.

BAD:

// [Anti-Pattern] Directly accessing .data on snapshot without state check
final name = snapshot.data; // Throws BloomSnapshotExtractionException if empty or error!

GOOD:

// [Recommended] Safe extraction with fallback or pattern matching
final name = snapshot.dataOrNull ?? 'Guest';
// Or exhaustive pattern matching via phase:
final message = switch (snapshot.phase) {
  BloomPhase.valid => 'Value: ${snapshot.data}',
  BloomPhase.empty => 'No data available',
  BloomPhase.error => 'Failed: ${snapshot.error}',
};

Implemented types

BloomState<T>

Annotations

@immutable

Constructors

BloomSnapshot(T data): Creates an immutable valid snapshot carrying the given data payload.
const

factory
BloomSnapshot.empty([Object? emptyReason]): Creates an immutable uninitialized (empty) snapshot with an optional emptyReason.
const

factory
BloomSnapshot.error(Object error, [StackTrace? stackTrace]): Creates an immutable error snapshot storing error and optional stackTrace.
const

factory

Properties

data → T: Extracts the underlying data synchronously from this snapshot.
no setteroverride
dataOrNull → T?: Safely extracts the underlying data, returning null if the snapshot is not in a valid state.
no setteroverride
emptyReason → Object?: The optional reason explaining why this snapshot is empty, or null if unspecified or not empty.
no setteroverride
error → Object: Extracts the underlying exception or failure object from an error snapshot.
no setteroverride
hasData → bool: Whether this snapshot contains a valid, extractable data payload.
no setteroverride
hasError → bool: Whether this snapshot is in a corrupted state containing an error or exception.
no setteroverride
hashCode → int: The hash code for this object.
no setterinherited
isEmpty → bool: Whether this snapshot is in an uninitialized or dormant state.
no setteroverride
phase → BloomPhase: The operational phase (BloomPhase.valid, BloomPhase.empty, or BloomPhase.error) of this snapshot.
no setteroverride
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
snapshot → BloomSnapshot<T>: The underlying snapshot representing this entity's current state.
no setterinherited
stackTrace → StackTrace: Extracts the call stack trace at the point of failure from an error snapshot.
no setteroverride

Methods

dataOrElse(T fallback()) → T: Safely extracts the underlying data, returning the result of fallback if not in a valid state.
override
equals(covariant BloomState<T> other, [bool equals(T previous, T next)?]) → bool: Determines if this snapshot is equivalent to other by comparing their validity and underlying payloads using an optional custom equals comparator.
override
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 ==(Object other) → bool: The equality operator.
inherited