Data Flow Analysis

The data flow analyzer builds a graph of value and service dependencies between steps in your Effect program. It tracks which steps produce values, which steps consume them, and identifies issues like undefined reads or duplicate writes.

Building a Data Flow Graph

import { analyze, buildDataFlowGraph } from "effect-analyzer/analysis"
import { Effect } from "effect"

const ir = await Effect.runPromise(analyze("./src/transfer.ts").single)
const graph = buildDataFlowGraph(ir)

console.log(graph.nodes.length)         // Number of data flow nodes
console.log(graph.edges.length)         // Number of dependency edges
console.log(graph.undefinedReads)       // Reads with no matching producer
console.log(graph.duplicateWrites)     // Keys written by multiple steps

Graph Structure

The DataFlowGraph contains:

Field	Type	Description
nodes	DataFlowNode[]	One node per effect step
edges	DataFlowEdge[]	Edges from producer to consumer
producedKeys	Set<string>	All keys that have a producer
undefinedReads	UndefinedRead[]	Reads where no producer was found
duplicateWrites	DuplicateWrite[]	Keys written by more than one step

Each DataFlowNode records:

Field	Type	Description
id	string	Node identifier (matches IR node ID)
name	string | undefined	Human-readable step name
writes	string | undefined	The success type this step produces
reads	string[]	Service IDs this step reads from Context

Querying Producers and Consumers

Find which steps produce or consume a given key:

import { getProducers, getConsumers } from "effect-analyzer/analysis"

// Who produces the "balance" value?
const producers = getProducers(graph, "balance")

// Who consumes "AccountService"?
const consumers = getConsumers(graph, "AccountService")

Transitive Dependencies

Trace the full dependency chain for a node:

import { getTransitiveDependencies } from "effect-analyzer/analysis"

const deps = getTransitiveDependencies(graph, "step-4")
// All nodes that step-4 transitively depends on

Finding Cycles

Detect circular dependencies in the data flow:

import { findCycles } from "effect-analyzer/analysis"

const cycles = findCycles(graph)
if (cycles.length > 0) {
  console.log("Circular dependencies found:", cycles)
}

Validating Data Flow

Run a comprehensive validation that checks for undefined reads, duplicate writes, and other issues:

import { validateDataFlow } from "effect-analyzer/analysis"

const validation = validateDataFlow(graph)

console.log(validation.undefinedReads)   // Reads with no producer
console.log(validation.duplicateWrites)  // Keys with multiple producers

Note

Undefined reads are not always bugs - they may indicate services provided at the call site via Effect.provideService. The validation reports them for your review.

Execution Order

Get the topological order of data flow nodes - the order in which they must execute based on their dependencies:

import { getDataFlowOrder } from "effect-analyzer/analysis"

const order = getDataFlowOrder(graph)
// Returns node IDs in dependency-respecting order

Mermaid Visualization

Render the data flow as a Mermaid diagram:

CLI

npx effect-analyze ./src/transfer.ts --format mermaid-dataflow

Library API

import { buildDataFlowGraph, renderDataFlowMermaid } from "effect-analyzer/diagram"

const graph = buildDataFlowGraph(ir)
const diagram = renderDataFlowMermaid(graph)

console.log(diagram)

The diagram shows nodes as boxes with their produced types, and edges indicating which values flow between steps.

Related

• Error Analysis - track error flow instead of value flow
• Complexity Metrics - overall program complexity
• All Formats - mermaid-dataflow format reference