ast-visitor-pattern · git:20260517.7c3f443 · 2026-05-17 · sha256 e5470d8bc75c5f76

ast-visitor-pattern git:20260517.7c3f443A

Immutable. This exact content never changes and is served at /api/v1/blob/e5470d8bc75c5f76.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_d5s65wxboaacq4mm/e5470d8bc75c5f7678972298d82633556c164a8b354a0a0518390ed5d3316528.json

Then /plugin install ast-visitor-pattern@markdownregistry-d5s65wxboaacq4mm in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: ast-visitor-pattern
description: >-
  Use the frozen-class/visitor pattern for discriminated unions that have
  multiple dispatch sites. Use when creating a new set of variants
  (commands, IR nodes, factory calls) that will be switched over in 2+
  places, or when refactoring an existing union type that has grown
  multiple switch sites.
---

# AST Class/Visitor Pattern

When a discriminated union has **3+ variants** and **2+ dispatch sites** (renderers, serializers, classifiers, etc.), replace plain union + switch with frozen subclasses and a visitor interface. This makes adding a new variant a compiler error at every consumer, instead of a silent omission.

## Structure

Four pieces, always in the same file:

```typescript
// 1. Abstract base (not exported — consumers use the union type)
abstract class FooNode {
  abstract readonly kind: string;
  abstract accept<R>(visitor: FooVisitor<R>): R;
  protected freeze(): void { Object.freeze(this); }
}

// 2. Visitor interface
export interface FooVisitor<R> {
  bar(node: BarNode): R;
  baz(node: BazNode): R;
}

// 3. Concrete subclasses — readonly fields, freeze() in constructor
export class BarNode extends FooNode {
  readonly kind = 'bar' as const;
  readonly value: string;
  constructor(value: string) {
    super();
    this.value = value;
    this.freeze();
  }
  accept<R>(visitor: FooVisitor<R>): R { return visitor.bar(this); }
}

export class BazNode extends FooNode {
  readonly kind = 'baz' as const;
  readonly count: number;
  constructor(count: number) {
    super();
    this.count = count;
    this.freeze();
  }
  accept<R>(visitor: FooVisitor<R>): R { return visitor.baz(this); }
}

// 4. Union type
export type Foo = BarNode | BazNode;
```

## Consuming

Define a visitor object (or class) per concern:

```typescript
const renderVisitor: FooVisitor<string> = {
  bar(node) { return node.value; },
  baz(node) { return String(node.count); },
};

function render(node: Foo): string {
  return node.accept(renderVisitor);
}
```

## In tests

Always construct subclass instances, never plain objects:

```typescript
// ✅
const call = new BarNode('x');

// ❌
const call: Foo = { kind: 'bar', value: 'x' };
```

## When NOT to use

- Single dispatch site → plain union + switch is simpler
- Fewer than 3 variants with no expected growth → not worth the boilerplate

## Codebase examples

- `MongoAstNode` / `MongoDdlCommandVisitor` — `packages/2-mongo-family/4-query/query-ast/src/ddl-commands.ts`
- `OpFactoryCall` / `OpFactoryCallVisitor` — `packages/3-mongo-target/1-mongo-target/src/core/op-factory-call.ts`