Design Principles in TypeScript (beyond SOLID & GoF)

The design heuristics that predate and underpin SOLID: how to measure and reduce coupling, maximize cohesion, avoid premature/false abstraction, and keep objects in charge of their own data — adapted to idiomatic TypeScript.

🎯 Why: Design for Change

The goal of writing software is to be able to change it safely. Coupling is the cost of the next change; cohesion is its locality. Tell-Don't-Ask, Demeter, encapsulation, composition-over-inheritance — all of these exist to shrink the blast radius of an edit. DRY and YAGNI cut both ways: too little abstraction and a change ripples; too much and the seam is in the wrong place. Pick the abstraction that makes the next diff small.

Scope — how this differs from the other two skills

• solid-principles owns SRP, OCP, LSP, ISP, DIP. This skill does not re-explain those. Where a principle here is adjacent (Separation of Concerns ≈ SRP at the architecture level; Program-to-an-Interface ≈ DIP/ISP), the reference file states the distinction and defers to solid-principles.
• gof-patterns owns the 23 named patterns. This skill explains the forces (coupling, cohesion, Tell-Don't-Ask) that motivate those patterns but never re-documents a pattern. "Composition over inheritance" here is the general principle; the patterns that apply it (Strategy, Decorator) live in gof-patterns.

How to use this skill

1. Match the symptom in the decision guide to a principle.
2. Open references/principles.md for that principle's full before/after TypeScript example and its "when this is over-engineering" note.
3. Apply the smallest change that removes real pain. These are heuristics that trade off against each other (DRY vs. coupling, YAGNI vs. extensibility) — resolve the conflict in favor of the code that is cheapest to change now.

Reference file

• references/principles.md — all principles with intent, a smell, a bad example, a refactor, TypeScript-specific notes, and when not to apply.

The principles

Decision guide — symptom → principle

TypeScript-specific guidance

• Connascence is the practical coupling metric. Prefer connascence of name (shared identifier) over connascence of type, and both over connascence of position (argument order) — replace positional params with an options object. Keep stronger forms (meaning, algorithm, timing) local to one module. See the Coupling section.
• readonly, #private, and accessor methods enforce encapsulation. Use #field (true runtime privacy) over the private keyword when callers must not reach in; expose readonly views instead of mutable arrays/objects.
• A narrow function type is an interface. "Program to an interface" rarely needs a class implements; type Notify = (e: Event) => void decouples just as well with less ceremony.
• as const + discriminated unions make illegal states unrepresentable — the strongest form of Fail Fast (compile-time instead of runtime).
• Tell-Don't-Ask conflicts with rich domain models exposed to React. UI often legitimately needs to ask (render state). Apply Tell-Don't-Ask to domain/service code; let view models be data bags.
• DRY is about knowledge, not characters. Two functions with identical bodies that encode different decisions should stay separate; coupling them to save lines creates a change-amplifier. Rule of Three before extracting.