Visitor.

01 / The idea

Where should the next operation live?

Giving each node an export method is a reasonable start. A text node returns its text, an image contributes its description, and a group combines its children. The operation is easy to find beside the data it uses.

Then the inventory arrives, and the description review after it. If each one adds a method to every node, each workflow ends up spread across the document model. You want to change how export works without opening the files that define what a document is.

Visitor puts an operation in a separate object with a method for each supported node type. A node accepts that object and routes the call to its corresponding method. The operation can then keep its rules and accumulated result together.

So the visitor knows the document’s vocabulary, and each node knows which visitor method is its own. That makes a new operation cheap: you write one more visitor. A new kind of node is the expensive change, because every visitor needs a method for it.

02 / See the shape

The node chooses a handler. The handler owns the policy.

Follow an Image node: accept receives the operation, then calls its image method with the node. Text export reads the description; inventory reads the source; review checks the relationship between description and decorative intent.

Group.accept only dispatches to the group method. Each visitor decides whether to walk the children. Text export stops at a draft group. Inventory includes unpublished assets, and review includes unpublished images. Children are visited in their stored order.

The basic view shows this dispatch contract. The practical view adds all three operations and their traces. The call site runs them over the same article; complete files include everything needed to reproduce the output.

export interface Visitor {
	visitText(node: TextNode): void;
	visitImage(node: ImageNode): void;
	visitGroup(node: GroupNode): void;
}
export interface DocumentNode {
	readonly id: string;
	accept(visitor: Visitor): void;
}
export class TextNode implements DocumentNode {
	readonly id: string;
	readonly text: string;
	constructor(id: string, text: string) {
		this.id = id;
		this.text = text;
	}
	accept(visitor: Visitor) {
		visitor.visitText(this);
	}
}
export class ImageNode implements DocumentNode {
	readonly id: string;
	readonly src: string;
	readonly alt: string;
	readonly decorative: boolean;
	constructor(id: string, src: string, alt: string, decorative: boolean) {
		this.id = id;
		this.src = src;
		this.alt = alt;
		this.decorative = decorative;
	}
	accept(visitor: Visitor) {
		visitor.visitImage(this);
	}
}
export class GroupNode implements DocumentNode {
	readonly id: string;
	readonly draft: boolean;
	readonly children: readonly DocumentNode[];
	constructor(id: string, draft: boolean, children: readonly DocumentNode[]) {
		this.id = id;
		this.draft = draft;
		this.children = [...children];
	}
	// Dispatch only. This method does not walk the children.
	accept(visitor: Visitor) {
		visitor.visitGroup(this);
	}
}

type Visitor interface {
	VisitText(*TextNode)
	VisitImage(*ImageNode)
	VisitGroup(*GroupNode)
}
type DocumentNode interface{ Accept(Visitor) }
type TextNode struct{ ID, Text string }

func (n *TextNode) Accept(v Visitor) { v.VisitText(n) }

type ImageNode struct {
	ID, Src, Alt string
	Decorative   bool
}

func (n *ImageNode) Accept(v Visitor) { v.VisitImage(n) }

type GroupNode struct {
	ID       string
	Draft    bool
	Children []DocumentNode
}

// Dispatch only. The visitor decides whether to walk children.
func (n *GroupNode) Accept(v Visitor) { v.VisitGroup(n) }

03 / Follow the walk

The same root can produce a different walk.

Run text export with the notes kept as draft. Then switch to inventory. Predict whether draft-image is visited, even though its source has already appeared on hero. A callback can happen without adding an output entry.

Try an empty hero description, or mark it decorative while keeping a description. Compare text export with image review: omitting text and reporting a description issue are different policies.

04 / Try a decision

A new operation and a new node are different changes.

A word-count visitor can implement the existing three methods. The node definitions need no word-count method. Setup still needs to expose or call that new operation.

Video changes the vocabulary itself. Every operation now needs a policy for something it did not previously understand. This is the other half of the design, and a useful test of whether it fits the changes you expect.

05 / Give it a real job

Run a fresh operation over a stable document.

An export button, build task, or review command can pass the current document to runOperation. It creates a fresh visitor and returns that run’s output and callback trace. Reusing a TextExport instance would append another run’s lines to the previous ones; the helper deliberately avoids that lifetime.

The supplied operations read the tree without changing it, synchronously, over trusted finite input. An image source is only a string: inventory neither normalizes URLs nor checks files.

Review has two authored rules: flag an empty description on an informative image, and flag a nonempty one on an image marked decorative. Whitespace is preserved. Passing them shows that those two conditions hold, not that the descriptions are good or the document accessible.

06 / Make the call

A visitor is one way to keep operations separate.

A TypeScript discriminated union can also support ordinary functions that switch on each variant. Each function remains a separate operation. For a small vocabulary and a few functions, that can be the clearest arrangement.

The visitor contract becomes useful when operations need a shared extension interface, reusable traversal hooks, or state that lasts across a walk. A match-based implementation can select the method, while the visitor contract describes what an operation must provide.

Required visitor methods expose missing implementations after the contract is updated. Default handlers can make partial visitors convenient while weakening that coverage signal.

Keep behavior on nodes when it belongs to their responsibilities and adding node kinds is the common change. Keep direct functions when they express the job clearly. Reach for Visitor when keeping operations together earns the extra dispatch contract.

07 / Already in your toolbox

Read the callback contract before writing the handler.

Go’s ast.Visitor works with ast.Walk. Visit returns the visitor to use for children; returning nil skips them. Walk also sends a nil-node callback after visiting children. That library owns the walk, unlike our group methods.

08 / Take the idea with you

Which kind of change should have one home?

Explain the design without saying “Visitor”: these nodes describe the document, this operation knows what each kind means, and this part owns the walk. Then name one new operation that stays together—and one new node type that would make you inspect every operation.

Choose Visitor when a known vocabulary keeps gaining independent operations, and you are willing to revisit those operations when the vocabulary changes.