Skill: Composite
Intent
Represent part-whole hierarchies as tree structures so clients can operate on individual elements and compositions using the same interface.
Applicability Signals
- Signal 1: Domain naturally forms recursive tree structures (UI widgets, file systems, org charts, expression trees).
- Signal 2: Client logic branches repeatedly between leaf handling and collection handling.
- Signal 3: Operations should apply uniformly at any hierarchy depth.
Contraindications
- Case 1: Structure is flat and unlikely to become hierarchical.
- Case 2: Leaves and containers require radically different APIs with little overlap.
- Case 3: Tree mutability/performance constraints make generic traversal too expensive.
Decision Heuristics
- If recursive part-whole modeling is central and clients need uniform treatment, prefer Composite.
- If you only need traversal behavior over an existing structure, Iterator may be enough.
- Decision anti-bias note: avoid forcing uniform APIs when domain semantics differ sharply.
Implementation Checklist
- [ ] Define component interface for shared operations.
- [ ] Implement leaf with direct behavior.
- [ ] Implement composite holding child components and delegating/aggregating operations.
- [ ] Define child-management operations with clear ownership rules.
- [ ] Add recursive tests for depth, ordering, and failure handling.
Misuse Checks
- Misuse 1: Leaf receives irrelevant child-management methods → Remediation: keep child management only where needed or use safe no-op policy.
- Misuse 2: Composite violates invariants (cycles, duplicate ownership) → Remediation: enforce parent/child integrity checks.
- Misuse 3: Clients depend on concrete leaf/composite checks frequently → Remediation: move behavior into component interface.
Verification Rubric
- Correctness:
- [ ] Leaf operation works standalone.
- [ ] Composite operation correctly aggregates/delegates across nested children.
- Design quality:
- [ ] Component interface captures meaningful shared behavior.
- [ ] Hierarchy manipulation rules are explicit and validated.
- Regression safety:
- [ ] Tests cover single node, multi-level tree, and invalid hierarchy edge cases.
Language-Specific Adaptations (Optional)
- TypeScript: model
Componentinterface and recursive child arrays with readonly where possible. - Python: dataclass-based leaves/composites can keep tree structure clear.
- Go: use interface + struct composition; guard against cycles in add-child operations.
Related Patterns (Optional)
- Iterator: traverse composite trees without exposing internal representation.
- Visitor: add operations across composite structures without modifying component classes.
Attribution & Sources
- Source Site: Refactoring.Guru
- Source URLs:
- https://refactoring.guru/design-patterns/composite
- https://refactoring.guru/design-patterns
- Derivation Note: Concepts derived from referenced sources; explanatory wording rewritten for this repository.
- Policy Note: This artifact intentionally includes no direct quotes and no Refactoring.Guru images.