Building a Field Dependency Graph

The exact problem: a form has fourteen conditional rules written as if statements inside change handlers, and nobody can answer two questions about it — which fields does changing the country affect, and can a rule ever trigger itself.

Context and Prerequisites

The reasoning behind modelling dependencies as a graph is in cross-field dependency logic. This page builds the graph: how to declare edges, how to sort them, and how to detect the cycle that no evaluation order can satisfy.

Core Pattern

interface Rule {
  readonly id: string;
  /** Fields this rule READS. These are the incoming edges. */
  readonly reads: readonly string[];
  /** Fields this rule WRITES — validity, requiredness, visibility, a value. */
  readonly writes: readonly string[];
  readonly evaluate: (values: Values) => RuleResult;
}

/** Adjacency built from the rules: field → the fields it can affect. */
export function buildGraph(rules: readonly Rule[]): Map<string, Set<string>> {
  const edges = new Map<string, Set<string>>();
  for (const rule of rules) {
    for (const from of rule.reads) {
      const to = edges.get(from) ?? new Set<string>();
      for (const w of rule.writes) if (w !== from) to.add(w);
      edges.set(from, to);
    }
  }
  return edges;
}

/**
 * Kahn's algorithm. Returns null when a cycle exists — which is a bug in the
 * RULE SET, so it should fail a test rather than be handled at runtime.
 */
export function topologicalOrder(edges: Map<string, Set<string>>): string[] | null {
  const indegree = new Map<string, number>();
  for (const [from, tos] of edges) {
    indegree.set(from, indegree.get(from) ?? 0);
    for (const to of tos) indegree.set(to, (indegree.get(to) ?? 0) + 1);
  }
  const queue = [...indegree].filter(([, d]) => d === 0).map(([n]) => n);
  const order: string[] = [];
  while (queue.length) {
    const node = queue.shift()!;
    order.push(node);
    for (const to of edges.get(node) ?? []) {
      const d = indegree.get(to)! - 1;
      indegree.set(to, d);
      if (d === 0) queue.push(to);
    }
  }
  // Fewer nodes emitted than exist means at least one is stuck in a cycle.
  return order.length === indegree.size ? order : null;
}

/** After a field changes, only its descendants need re-evaluating. */
export function affectedBy(field: string, edges: Map<string, Set<string>>): string[] {
  const seen = new Set<string>();
  const stack = [field];
  while (stack.length) {
    const n = stack.pop()!;
    for (const to of edges.get(n) ?? []) if (!seen.has(to)) { seen.add(to); stack.push(to); }
  }
  return [...seen];
}

Step-by-Step Walkthrough

1. Make every rule declare reads and writes. This is the entire migration, and it is mechanical.

2. Build the adjacency once. At registration, not per change.

3. Sort once and cache. The order depends on the rules, which do not change at runtime.

4. Assert acyclicity in a test. A cycle is a rule-set bug; discovering it in a browser is a hung tab.

5. Walk descendants on change. Only the affected subgraph re-evaluates.

6. Evaluate in sorted order. Every rule’s inputs are settled when it runs, so one pass is enough.

Failure Modes and Edge Cases

1. Under-declared reads

A rule that quietly reads a field it did not declare will not re-run when that field changes. Under-declaring is the dangerous direction; over-declaring only costs extra evaluations.

2. A rule that writes what it reads

Self-edges are excluded above, which is right for the common “normalise this field” rule but hides a real cycle if two rules do it to each other. The sort catches the pair.

3. Async rules in the order

A remote check cannot block the pass. Run the synchronous chain to completion, then dispatch the async ones — and treat their results as arriving later, through the queue rather than through the graph.

4. Dynamic rules

Rules added when a section appears change the graph. Rebuild and re-sort on registration change, and re-assert acyclicity then too.

5. The order is not an announcement order

Sorted order is right for evaluation. For announcing consequences, the reader needs cause before effect, which is the same order — but only if you announce as you evaluate, not after collecting everything.

Verification Checklist

• Every rule declares both reads and writes
• The graph is built once, at registration
• A cycle fails a test rather than reaching a browser
• Changing a field re-evaluates only its descendants
• One pass settles every affected rule
• Async rules run after the synchronous chain
• Adding rules at runtime rebuilds and re-asserts the graph

Common Pitfalls

• Under-declaring reads. A rule that quietly reads an undeclared field never re-runs when that field changes, and the bug looks like validation that works for some readers and not others.
• Leaving visibility rules out. Showing and hiding fields creates edges exactly like validation does, and a pair that hides each other is a cycle that manifests as flickering.
• Rebuilding per keystroke. The graph depends on the rules, which do not change at runtime. Build and sort once, then only walk.
• Handling cycles at runtime. Any runtime handling is a silent choice about which rule loses. Assert the sort succeeds in a test instead.
• Putting async rules in the order. A topological pass that awaits a round trip stops being a pass. Run the synchronous chain, then dispatch.

Related

• Cross-Field Dependency Logic — why the graph shape matters
• Conditional Required Fields Without Cycles — the rule shape that most often creates one
• Queueing Async Validators in Order — where the async rules go

← Cross-Field Dependency Logic

Frequently Asked Questions