Building Reactive DevTools: Inspecting, Visualizing, and Profiling the Graph

Recap

In the previous chapters, we explored:

• Scheduler internals
• Memory and graph management
• Priority and layered scheduling
• Time-slicing and cooperative scheduling

All of these mechanisms are essential for making a reactivity system work correctly internally.

But internal correctness alone is not enough.

For developers, the more important question is:

How do we observe, debug, and understand the system?

That is where DevTools and diagnostics become critical.

---

Inspecting Nodes

Why do we need inspect()?

One of the most common debugging needs during development is:

“What is the current value of this signal or computed?”

If the only solution is console.log, debugging quickly becomes inconvenient and intrusive.

A proper inspection layer gives developers visibility without polluting application logic.

---

Feature Design

The inspector should provide:

• Current value
• Dependency relationships (deps / subs)

• Whether the node is:

  • stale
  • disposed

---

Implementation

// devtools.ts
// type reused from previous graph.ts
import type { Node } from "./graph.js";

// Assign IDs using WeakMap without polluting Node structure
const ids = new WeakMap<Node, string>();
let seq = 0;

function getId(n: Node) {
  let id = ids.get(n);

  if (!id) {
    id = `${n.kind}#${++seq}`;
    ids.set(n, id);
  }

  return id;
}

export type InspectSnapshot = {
  id: string;
  kind: Node["kind"];
  inDegree: number;
  outDegree: number;
  deps: { id: string; kind: Node["kind"] }[];
  subs: { id: string; kind: Node["kind"] }[];
};

// Get a flat snapshot of a single node (non-recursive)
export function inspect(node: Node): InspectSnapshot {
  return {
    id: getId(node),
    kind: node.kind,
    inDegree: node.deps.size,
    outDegree: node.subs.size,
    deps: [...node.deps].map(n => ({
      id: getId(n),
      kind: n.kind,
    })),
    subs: [...node.subs].map(n => ({
      id: getId(n),
      kind: n.kind,
    })),
  };
}

---

Debug-Friendly Logging

export function logInspect(node: Node) {
  const snap = inspect(node);

  console.log(
    `[inspect] ${snap.id} (${snap.kind})  in=${snap.inDegree}  out=${snap.outDegree}`
  );

  if (snap.deps.length) {
    console.log("  deps ↑");
    console.table(snap.deps);
  } else {
    console.log("  deps ↑ (none)");
  }

  if (snap.subs.length) {
    console.log("  subs ↓");
    console.table(snap.subs);
  } else {
    console.log("  subs ↓ (none)");
  }
}

This provides a much friendlier debugging experience than raw logging.

---

Recursive Graph Inspection

When debugging larger dependency chains, inspecting a single node is often not enough.

We can recursively expand the graph while avoiding cycles.

export function inspectRecursive(root: Node, depth = 1) {
  const seen = new Set<Node>();

  type Row = {
    from: string;
    to: string;
    dir: "deps" | "subs";
  };

  const rows: Row[] = [];

  const queue: Array<{
    node: Node;
    dUp: number;
    dDown: number;
  }> = [{
    node: root,
    dUp: depth,
    dDown: depth,
  }];

  seen.add(root);

  while (queue.length) {
    const { node, dUp, dDown } = queue.shift()!;
    const fromId = getId(node);

    if (dUp > 0) {
      for (const dep of node.deps) {
        rows.push({
          from: getId(dep),
          to: fromId,
          dir: "deps",
        });

        if (!seen.has(dep)) {
          seen.add(dep);

          queue.push({
            node: dep,
            dUp: dUp - 1,
            dDown: 0,
          });
        }
      }
    }

    if (dDown > 0) {
      for (const sub of node.subs) {
        rows.push({
          from: fromId,
          to: getId(sub),
          dir: "subs",
        });

        if (!seen.has(sub)) {
          seen.add(sub);

          queue.push({
            node: sub,
            dUp: 0,
            dDown: dDown - 1,
          });
        }
      }
    }
  }

  return {
    center: getId(root),
    nodes: [...seen].map(n => ({
      id: getId(n),
      kind: n.kind,
    })),
    edges: rows,
  };
}

---

Mermaid Export

We can even export subgraphs into Mermaid diagrams for documentation or DevTools visualization.

export function toMermaid(root: Node, depth = 1) {
  const g = inspectRecursive(root, depth);

  const lines = ["graph TD"];

  for (const n of g.nodes) {
    lines.push(
      `  ${n.id.replace(/[^a-zA-Z0-9_#]/g, "_")}["${n.id}"]`
    );
  }

  for (const e of g.edges) {
    const a = e.from.replace(/[^a-zA-Z0-9_#]/g, "_");
    const b = e.to.replace(/[^a-zA-Z0-9_#]/g, "_");

    lines.push(`  ${a} --> ${b}`);
  }

  return lines.join("\n");
}

---

API Summary

• inspect(node)

  • Fastest single-node snapshot

• logInspect(node)

  • Debug-friendly console tables

• inspectRecursive(node, depth)

  • Small graph expansion without infinite loops

• toMermaid(node, depth)

  • Export subgraphs for docs or DevTools rendering

---

Graph Visualization

As applications grow larger, textual inspection is no longer sufficient.

At that point, we need dependency graph visualization.

• Signal nodes (blue) represent data sources
• Computed nodes (green) represent derived values
• Effect nodes (yellow) represent side effects

Inside DevTools, we could:

• Click nodes to inspect current values
• Highlight stale nodes
• Visualize link/unlink operations
• Observe automatic cleanup and graph pruning

This makes the dataflow fully observable.

Instead of a black box, developers can literally see:

Which state triggered which update.

---

Render Counters

The Problem

In UI frameworks, one of the most common performance issues is over-rendering.

For example:

• Components re-render repeatedly
• But nothing meaningful actually changes

---

Feature Design

A render counter can:

• Increment on each render
• Display a small overlay badge
• Aggregate render statistics in DevTools

---

Why This Matters

This helps developers identify:

• Unnecessary re-renders
• Missing memoization
• Poor equality strategies
• Expensive recomputation chains

It also guides optimization decisions like:

• memo
• shallowEqual
• computed caching

---

Hotspot Tracking

Why Track Hotspots?

In large applications, knowing that something updated is not enough.

We also need to know:

Which nodes update the most frequently?

That is where hotspot profiling becomes valuable.

---

Feature Design

We can track:

• Update counts
• Update frequency
• Execution duration
• Graph degree statistics

And combine them with:

• Heatmaps
• Timeline views
• Priority scheduling traces

---

Hotspot Implementation

1. hotspot.ts

// hotspot.ts
import type { Node } from "../graph.js";

export type HotspotStats = {
  updates: number;
  lastTs: number;
  freqPerMin: number;
  durTotal: number;
  durCount: number;
};

let stats = new WeakMap<Node, HotspotStats>();

const liveNodes = new Set<Node>();

const alpha = 0.2;

const now = () =>
  globalThis.performance?.now?.() ?? Date.now();

The system tracks:

• Frequency
• Total execution time
• Average execution time
• Update counts

without modifying the core graph structure itself.

---

2. Tracking Signal Writes

recordUpdate(node);

We only inject instrumentation where actual work happens.

For example:

• signal.set()
• computed.recompute()
• effect.run()

This keeps the core runtime clean and minimally invasive.

---

3. Wrapping Computation Timing

withTiming(node, () => {
  // recompute logic
});

This allows us to measure:

• recomputation frequency
• average execution duration
• expensive reactive chains

---

Example Usage

logTopHotspots(5, "freq", allNodes());

logTopHotspots(5, "avgTime", allNodes());

logTopHotspots(5, "updates", allNodes());

This lets us quickly identify:

• high-frequency nodes
• expensive computations
• reactive bottlenecks

---

Real-World Use Cases

Game Loops

Identify states updating every frame.

Forms

Detect extremely hot input fields.

Data Visualization

Locate nodes responsible for expensive re-renders.

Async Systems

Observe retry storms or invalidation cascades.

---

Why DevTools Matter

DevTools are not just debugging utilities.

They also help developers:

Build Mental Models

Understand how the reactive graph actually flows.

Optimize Performance

Locate bottlenecks quickly instead of guessing blindly.

Learn Reactivity

Make invisible runtime behavior visible and intuitive.

---

Possible Future Directions

Timeline Profiling

Visualize update propagation over time.

Priority-Aware Diagnostics

Inspect how different scheduler priorities interact.

Automated Suggestions

Examples:

• “This signal updates too frequently.”
• “Consider memoizing this computed.”
• “This effect causes excessive downstream invalidation.”

---

Final Thoughts

By adding:

• node inspection
• graph visualization
• render counters
• hotspot profiling

we transform the reactive system from a black box into an observable runtime.

This not only improves debugging and optimization,
but also helps developers truly understand how reactivity works internally.

DevTools are not just developer conveniences —
they are part of how a runtime teaches its own architecture.

At this point, I’ve shared most of the core knowledge I gained while implementing this series.

There are still many unexplored trade-offs and architectural differences across reactive libraries, and those differences often determine why certain libraries perform better in specific scenarios.

In the next article, I’d like to share some personal reflections and lessons learned from writing this entire series.