Composite

The three participants

Every Composite setup has the same three roles. Once you can name them, you can spot the pattern anywhere:

• Component — the shared interface, e.g. FileSystemItem with size(). This is the only type client code ever talks to. It declares the operations that make sense for both single items and groups.
• Leaf — a plain end object with no children, e.g. File. It implements the operation directly: size() just returns its own byte count. Leaves do the real work.
• Composite — the container, e.g. Folder. It holds a list of children (each typed as Component, so files and folders mix freely) and implements the operation by delegating: call size() on every child and combine the answers.

How one call cascades down the tree

Say you call size() on the root folder project. The folder doesn't know (or care) what its children are — it just calls size() on each one. readme.md answers 2 KB immediately. src is a folder, so the same thing happens one level down: it asks app.ts (14 KB) and utils.ts (6 KB), adds them to 20 KB, and passes that up. Every level does one tiny job — ask children, add — and the recursion assembles the full answer:

interface FileSystemItem {
  size(): number;                       // the one shared operation
}

class File implements FileSystemItem {
  constructor(private bytes: number) {}
  size(): number { return this.bytes; } // Leaf: answers directly
}

class Folder implements FileSystemItem {
  private children: FileSystemItem[] = [];

  add(item: FileSystemItem): void { this.children.push(item); }

  size(): number {                      // Composite: delegates + combines
    return this.children.reduce((sum, child) => sum + child.size(), 0);
  }
}

Notice what's missing: Folder.size() has no if (child is File) check. A child is just a FileSystemItem that knows how to report its size. That's the uniformity the pattern buys you — add a new kind of node (a symlink, a zip archive) and Folder doesn't change at all.

Child management: where should add() live?

Composites need child-management methods — add(item), remove(item), maybe getChildren(). The classic design question is where to declare them, and there are two honest answers:

• Transparency — declare add()/remove() on the Component interface itself. Now clients treat everything uniformly, even for child management. The cost: File.add() exists but makes no sense, so a leaf must throw or silently ignore it — a runtime surprise.
• Safety — declare add()/remove() only on Composite (as in the code above). Now it's impossible to add a child to a file — the compiler stops you. The cost: clients that want to build trees must know they're holding a Folder, so uniformity is slightly weaker.

This tree shape is everywhere

Once you see the file-system version, you'll recognise the same structure all over software:

• UI component trees — a window holds panels, panels hold buttons and more panels; render() on the root renders everything.
• Org charts — a manager 'contains' employees and other managers; headcount() or totalSalary() rolls up the same way size() does.
• Menus — a menu holds items and submenus; MenuItem and Menu share one interface.
• Arithmetic expressions — (2 + 3) * 4 is a tree where numbers are leaves and operators are composites; evaluate() cascades exactly like size().

A close cousin worth contrasting: [[decorator]] also wraps objects behind a shared interface, but a Decorator has exactly one child and exists to add behaviour on the way through. A Composite has many children and exists to aggregate their answers. Same wrapping trick, different purpose.

Use Composite when your problem is genuinely a tree

Two signals tell you this pattern fits. Both should be true:

• You have a part–whole hierarchy — objects that contain other objects of the same general kind, nested to any depth: folders in folders, panels in panels, bundles in bundles, teams in teams.
• Clients should ignore the difference — the code using these objects wants to ask one question (size(), render(), price(), headcount()) without checking whether it's holding one item or a group. If you find yourself writing if (item is Folder) ... else ... all over, Composite removes exactly those branches.

When NOT to use it

• The structure is flat — a plain list of files with no nesting needs a list, not a pattern. Composite only earns its keep when containers hold other containers.
• Leaves and containers genuinely need different APIs — if clients almost always need folder-only operations (permissions, watching, listing) and almost never treat files and folders alike, forcing one shared interface makes it too general: it fits neither side well.
• The hierarchy is fixed and two levels deep — a report with exactly 'sections containing rows' can be two plain classes. Reach for Composite when depth is open-ended.