computed top-level constant

ComputedFunctor const computed

Core declarative reactive computation functor powered by the 2-Phase Lazy-Pull DAG (LPDAG) engine.

Automatically and dynamically tracks reactive dependencies accessed via BloomVia, evaluating on-demand with zero redundant executions and zero-allocation 1-pass epoch diffing.

System Architectural Flow

[Upstream Bloom States] ──(Mutates)──> [Push-Dirty Notification (Single-Pass)]
                                                   │
                                                   ▼ (Marks Stale)
                                              [computed]
                                                   │
                                                   ▼ (Lazy Pull-Data on untracked / via read)
                          [1-Pass Epoch Diffing & O(S) Direct Source Scanning]

Architectural Benefits

  1. Lazy Pull-Data Scheduling: Computations run only when requested by downstream consumers or render cycles.
  2. Zero-Allocation Epoch Diffing: Graph edge registration and stale edge pruning occur inline without heap churn.
  3. Explicit BloomVia Dependency Manifest: Dynamically records dependencies via via(node) with zero dynamic tracking stack overhead.
  4. $O(S)$ Freshness Invariant: Verifies freshness directly against its $S$ immediate upstream sources.

Sub-Functor & Computation Pathways

computed(...)                  ──> Synchronous derivation ([Bloom])
  │                                  ├─ Fast-path zero-allocation inline evaluation
  │                                  └─ Precondition gating via [BloomGuard]
  │
  ├─ .future(...)              ──> Single-shot asynchronous request with SWR ([Bloom])
  │    │                             ├─ Auto-refetch on reactive dependency mutation
  │    │                             ├─ Instant SWR cache preload ([initialFactory])
  │    │                             └─ Error fallback recovery ([onError])
  │    │
  │    └─ .async(...)          ──> Inlined keyword alias for [future]
  │
  └─ .stream(...)              ──> Continuous real-time stream subscription ([Bloom])
                                     ├─ Auto-switching & async* generator synthesis
                                     ├─ Graceful retention across routes ([Graceful.period])
                                     └─ Duplicate event filtering ([distinct], [equals])

Execution Modes

Mode Target Use Case Key Capabilities
computed(...) Pure synchronous derivations Fast-path zero-allocation inline evaluation
computed.future(...) Single-shot asynchronous requests Auto-refetch on mutation, precondition gating, SWR cache
computed.stream(...) Continuous real-time data feeds async* synthesis, WebSocket retain, graceful mooring

Quick Examples

Synchronous:

final fullName = computed((via) => '${via(firstName.bloom)} ${via(lastName.bloom)}');

Asynchronous (Future):

final userProfile = computed.future((via) => api.fetchUser(via(userId.bloom)));

Continuous (Stream):

final messages = computed.stream((via) => socket.watchMessages(via(roomId.bloom)));

For comprehensive real-world patterns (guards, cache preloading, error recovery, graceful policies):

Implementation

const computed = ComputedFunctor._();