Encapsulate Composite With Builder

Triggered by

Destination

Symptom

Construction sites for tree-shaped objects sprawl across dozens of intermediate variables and `addChild` calls. The tree's shape is buried under wiring code; readers have to mentally rebuild it on every visit, and the construction site no longer resembles the structure it produces. The reader's comprehension cost per visit scales with the tree's size and the wiring's verbosity.

Goal

A fluent builder whose API mirrors the tree's shape. Client code reads as an outline of the structure it builds — one statement per node, indentation matching depth, so the construction site is the tree, supporting separation of concerns between construction grammar and tree semantics.

Before the refactoring

// Client constructs the XML tree by wiring TagNodes manually.
const order = new TagNode('Order');
const customer = new TagNode('Customer');
customer.setAttribute('id', 'C-901');
order.addChild(customer);
const items = new TagNode('Items');
const item1 = new TagNode('Item');
item1.setAttribute('sku', '123');
item1.setAttribute('qty', '2');
items.addChild(item1);
const item2 = new TagNode('Item');
item2.setAttribute('sku', '456');
item2.setAttribute('qty', '1');
items.addChild(item2);
order.addChild(items);
const xml = order.toXML();

After the refactoring

// Client reads as an outline of the tree it builds.
const xml = new XMLBuilder('Order')
  .addChild('Customer').addAttribute('id', 'C-901').end()
  .addChild('Items')
    .addChild('Item').addAttribute('sku', '123').addAttribute('qty', '2').end()
    .addChild('Item').addAttribute('sku', '456').addAttribute('qty', '1').end()
  .end()
  .toXML();

Example source: Adapted from Joshua Kerievsky's XML-builder example in Refactoring to Patterns (Addison-Wesley, 2004), chapter 6. The Java original used a TagNode composite + XMLBuilder fluent API; this JavaScript translation keeps the same shape — TagNode for the composite, a chained builder for the construction grammar.

Pressure

Composite construction code accretes inline at every call site. Renaming a node type ripples to all sites; the tree's invariants (required children, allowed attribute combinations) live scattered across construction sites. The team's verification cost compounds across sites that each must enforce invariants independently, and the blast radius of any node-type edit stretches across every construction site.

Tradeoff

Fluent builders are tightly coupled to the composite's shape; changes to the composite ripple into the builder API. Method chains are hard to step through in a debugger — stack traces sit on the chain's closing `.end()` call rather than the failing node, slowing diagnosis. The team's debugging cost rises when failures happen mid-chain.

Relief

One builder owns the construction grammar; client code becomes a literal of the structure. Adding a node type is one new builder method; constraints (required attributes, allowed children) move into the builder where the type system can enforce them. The team's enhancement cost drops because new node types add one method instead of dozens of construction-site updates.

Trap

A builder DSL designed around one client's tree shape that the next client cannot use. Builders that don't enforce tree invariants are thin facades over the composite — readability without correctness — and drift into godlike `*Manager` classes. The cure adds accidental complexity that raises cognitive load per read.