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                         |
| ------------------------- | ---------------------------------------------------- | ---------------------------------------- |
| **S**ingle Responsibility | One class, one reason to change                      | Strategy, Command, Observer              |
| **O**pen/Closed           | Open for extension, closed for modification          | Decorator, Strategy, Template Method     |
| **L**iskov Substitution   | Subtypes must be substitutable for base types        | Factory Method, Abstract Factory         |
| **I**nterface Segregation | Prefer small, focused interfaces                     | Adapter, Facade                          |
| **D**ependency Inversion  | Depend on abstractions, not concretions              | All patterns using interfaces/abstract   |