Design Patterns

Design Patterns

Proven architectural patterns for building maintainable, extensible, and testable TypeScript codebases. All 22 Gang of Four patterns with practical implementations.

When to Apply

Reference these patterns when:

• Solving recurring architectural problems
• Refactoring tightly coupled code
• Building plugin/extension systems
• Making code more testable via dependency injection
• Reviewing PRs with architectural concerns
• Choosing between inheritance and composition

Pattern Categories

Creational Patterns

Create objects flexibly, hiding creation logic from consumers.

| Pattern | Intent | | -------------------- | --------------------------------------------------------- | | Factory Method | Delegate object creation to subclasses | | Abstract Factory | Create families of related objects without concrete types | | Builder | Construct complex objects step-by-step | | Prototype | Clone existing objects instead of building from scratch | | Singleton | Ensure exactly one instance with global access |

See references/CREATIONAL.md for implementations.

Structural Patterns

Compose classes and objects into larger, flexible structures.

| Pattern | Intent | | ------------- | ------------------------------------------------------------- | | Adapter | Make incompatible interfaces work together | | Bridge | Separate abstraction from implementation | | Composite | Treat individual objects and compositions uniformly | | Decorator | Attach responsibilities dynamically without subclassing | | Facade | Simplify complex subsystem with a unified interface | | Flyweight | Share common state to reduce memory across many objects | | Proxy | Control access to an object through a substitute |

See references/STRUCTURAL.md for implementations.

Behavioral Patterns

Manage algorithms, responsibilities, and communication between objects.

| Pattern | Intent | | ---------------------------- | ------------------------------------------------------- | | Chain of Responsibility | Pass requests along a handler chain | | Command | Encapsulate requests as objects for queuing/undo | | Iterator | Traverse collections without exposing internals | | Mediator | Centralize complex communication between objects | | Memento | Capture and restore object state | | Observer | Notify dependents automatically on state changes | | State | Alter behavior when internal state changes | | Strategy | Swap algorithms at runtime | | Template Method | Define algorithm skeleton, let subclasses override steps | | Visitor | Add operations to objects without modifying them |

See references/BEHAVIORAL.md for implementations.

Pattern Selection Guide

| Problem | Pattern(s) | | ------------------------------------------ | ----------------------------------- | | Need to decouple object creation | Factory Method, Abstract Factory | | Complex object with many optional fields | Builder | | Expensive object creation, need copies | Prototype | | Global shared resource (config, pool) | Singleton | | Incompatible third-party interface | Adapter | | Multiple dimensions of variation | Bridge | | Tree structures (files, UI, org charts) | Composite | | Add features without subclassing | Decorator | | Simplify complex API surface | Facade | | Thousands of similar objects, memory heavy | Flyweight | | Lazy loading, access control, caching | Proxy | | Flexible request processing pipeline | Chain of Responsibility | | Undo/redo, task queues, macros | Command | | Custom collection traversal | Iterator | | Many-to-many object communication | Mediator | | Snapshots, save/restore state | Memento | | Event systems, reactive updates | Observer | | Object behavior depends on its state | State | | Swappable algorithms (sort, compress, etc) | Strategy | | Algorithm with fixed steps, variable parts | Template Method | | Operations across heterogeneous objects | Visitor |

Best Practices

DO

• Choose patterns that solve actual problems you're facing now
• Prefer composition over inheritance
• Use dependency injection to decouple components
• Keep pattern implementations simple — avoid gold-plating
• Document why a pattern was chosen (not just which one)
• Consider testability when choosing patterns
• Combine patterns when appropriate (e.g., Strategy + Factory)

DON'T

• Apply patterns preemptively for hypothetical future needs
• Force a pattern where a simple function/object suffices
• Create unnecessary abstraction layers
• Use Singleton as a disguised global variable
• Choose inheritance when composition works better
• Ignore team familiarity — a simpler pattern everyone knows beats a "better" one nobody understands

SOLID Quick Reference

| Principle | Summary | Related Patterns | | ------------------------- | ---------------------------------------------------- | ---------------------------------------- | | Single Responsibility | One class, one reason to change | Strategy, Command, Observer | | Open/Closed | Open for extension, closed for modification | Decorator, Strategy, Template Method | | Liskov Substitution | Subtypes must be substitutable for base types | Factory Method, Abstract Factory | | Interface Segregation | Prefer small, focused interfaces | Adapter, Facade | | Dependency Inversion | Depend on abstractions, not concretions | All patterns using interfaces/abstract |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fellipeutaka
• Source: fellipeutaka/leon
• License: MIT

Install and usage instructions live in the source repository linked above.