typescript-design-patterns · diff

git:20261029.32a42ce to git:20261029.c763ba7

5 added, 22 removed. Audit A to A.

---

name: typescript-design-patterns

description: >

Use when choosing, implementing, or reviewing TypeScript design patterns for creation,

composition, communication, and state: factories, builders, cloning, shared-resource

lifetime, adapters, facades, wrappers, composites, proxies, flyweights, strategies, state

machines, observers, mediators, commands, undo/redo, middleware, iterators, template

methods, or visitors. Compare candidates with plain functions, objects, modules, or

discriminated unions and preserve behavior and lifecycle contracts.

---

# TypeScript Design Patterns

Choose a pattern from the problem's variation and ownership requirements.

Keep the implementation as small as the contract allows.

## Define the design pressure

1. Read the existing interfaces, callers, module conventions, and tests around

the requested change. Identify the runtime and compiler features available.

2. State what varies: object creation, implementation combinations, behavior,

state transitions, event recipients, or operations over a stable structure.

3. State what stays stable: a client contract, construction invariant, ordering

rule, state transition rule, or lifecycle boundary.

4. Record relevant constraints: sync/async behavior, mutation, identity, error

propagation, cancellation, disposal, serialization, and concurrent use.

5. Compare a plain function/object with one or two candidate patterns. Choose

based on the current requirement; avoid abstractions for hypothetical variants.

## Select one family reference

- | Problem | Start with | Read |

- | --- | --- | --- |

- | Product selection, compatible families, construction steps, copies, shared resources | Factory, Abstract Factory, Builder, Prototype, scoped Singleton | [Creational patterns](references/creational.md) |

- | Interface mismatch, subsystem entry point, trees, wrappers, independent dimensions, access, shared data | Adapter, Facade, Composite, Decorator, Bridge, Proxy, Flyweight | [Structural patterns](references/structural.md) |

- | Interchangeable policy, transitions, events, coordination, undo, middleware, traversal, extension hooks | Strategy, State, Observer, Mediator, Command, Memento, Chain of Responsibility, Iterator, Template Method, Visitor | [Behavioral patterns](references/behavioral.md) |

+ | Problem | Read |

+ | --- | --- |

+ | Product selection, compatible families, construction stages, copies, shared resources | [Creational patterns](references/creational.md) |

+ | Contract translation, wrappers, trees, independent dimensions, access, shared data | [Structural patterns](references/structural.md) |

+ | Policy, transitions, events, coordination, undo, middleware, traversal, extension hooks | [Behavioral patterns](references/behavioral.md) |

Load only the family needed for the task. Use the other references only when

comparing overlapping choices, such as Decorator versus Proxy or Command versus

Memento. Keep creation policy separate from the behavior being created.

- ## Resolve the important distinctions

- - Choose **Adapter** to translate a contract, **Facade** to simplify a subsystem,

- and **Bridge** for two dimensions that must vary independently.

- - Choose **Decorator** to compose responsibilities and **Proxy** to mediate

- access or lifetime. Define wrapper order and preserve the delegated contract.

- - Choose **Strategy** when a client selects a policy and **State** when valid

- behavior follows the current state and its transition rules.

- - Choose **Command** to capture an action and **Memento** to capture state.

- Combine them only when the history requirements need both.

- - Choose **Observer** for subscriptions and **Mediator** for coordination.

- Assign ownership of subscriptions and define listener failure behavior.

- - Choose **Visitor** for changing operations over a relatively stable node family.

- Prefer a discriminated union with exhaustive functions when that stays clearer.

- - Distinguish a simple factory function from the subclass-based Factory Method

- pattern. Distinguish the Decorator pattern from TypeScript `@decorator` syntax.

## Implement the contract

1. Define the smallest type the client needs. Prefer typed functions for a single

operation, composed objects for capabilities, and classes when identity or

lifecycle makes them useful.

2. Keep construction and external I/O wiring at clear boundaries. Reuse the

project's established libraries and integration conventions.

3. Preserve input/output relationships with generics or discriminants. Localize

necessary assertions and verify the invariant behind them; do not silence a

mismatch with `any` or a broad assertion.

4. Validate untrusted runtime inputs before treating them as a factory choice,

event payload, configuration, or transition. Types alone do not validate data.

5. Define state and resource ownership explicitly. Bound caches/history where

appropriate; return disposal/unsubscribe handles for owned registrations.

6. Make failures observable. Define retry, rollback, and partial-completion policy

when a wrapper, chain, command, or initialization performs several effects.

7. Keep examples small and executable in their stated environment. Replace

teaching stubs with the user's real adapters when producing application code.

## Verify the pattern's invariant

| Family | Verify |

| --- | --- |

| Creation | Required fields, invalid choices, compatible product family, clone independence, shared initialization and failure policy |

| Structure | Contract translation, wrapper order, method receiver behavior, cache invalidation, access policy, empty/deep composites |

| Behavior | Legal/illegal transitions, event-payload correlation, listener cleanup, failure propagation, undo/redo history, traversal order |

Run the repository's typecheck and focused behavior checks. For replacement

implementations, run the same public contract against each. For async components,

include concurrent calls, rejection, cancellation, and cleanup when relevant.

Add tests for meaningful behavior or concrete defects, not for the existence of

pattern-named classes.

## Deliver the result

Explain the requirement, chosen pattern, simpler alternative considered, and

resulting public contract. Include the implementation or focused review findings,

verification evidence, and material tradeoffs such as indirection, retained state,

or lifecycle complexity. State which checks were not run.

## Source basis

Use the 22 patterns covered by the pinned teaching guides as the source taxonomy.

Apply the qualifications in the references instead of copying samples blindly.

- [Creational patterns, chapter 10](https://github.com/nirajkvinit/StructWeave-Algorithms/blob/e2a796e212d431c906c85957ea3c203ce0e2218f/languages/typescript/10-design-patterns-creational.md)

- [Structural patterns, chapter 11](https://github.com/nirajkvinit/StructWeave-Algorithms/blob/e2a796e212d431c906c85957ea3c203ce0e2218f/languages/typescript/11-design-patterns-structural.md)

- [Behavioral patterns, chapter 12](https://github.com/nirajkvinit/StructWeave-Algorithms/blob/e2a796e212d431c906c85957ea3c203ce0e2218f/languages/typescript/12-design-patterns-behavioral.md)