atelier-typescript-functional-patterns_skill

Overview

This skill provides battle-tested functional programming patterns for reliable TypeScript. I supply ready-to-paste helpers and guidance for ADTs, discriminated unions, Option/Result types, and branded types so your code becomes safer and self-documenting. Follow these patterns to make illegal states unrepresentable and shift errors from runtime to compile time.

How this skill works

The skill codifies type-first designs: sum and product types model variants and states, Option/Result model nullable values and recoverable errors, and Brand-based smart constructors enforce invariants. It includes utilities (map/flatMap, Ok/Err, Some/None), an assertNever helper for exhaustiveness, and examples to integrate into state machines, parsing, and domain objects. Use the patterns to let the TypeScript compiler prove correctness and make refactors mechanical and low-risk.

When to use it

• Model state machines (pending → settled → failed) and enforce transitions
• Replace ad-hoc null/undefined checks with explicit Option types
• Return Result from functions that can fail with recoverable errors
• Prevent unit and ID confusion using branded types and smart constructors
• Make domain invariants explicit and validated at construction time

Best practices

• Use a consistent discriminant field (_tag, kind, or type) for unions to enable narrowing
• Always include assertNever in default switch branches for exhaustiveness checks
• Prefer Option for expected absence and Result for recoverable failures; reserve exceptions for programmer errors
• Validate values in smart constructors and expose only branded types to the rest of the codebase
• Enable strict TypeScript flags (strictNullChecks, noImplicitReturns, strictFunctionTypes) before broad adoption

Example use cases

• Transaction lifecycle state machine with exhaustive handling of pending/settled/failed/reversed
• Configuration parsing that returns Result<Config, ConfigError> instead of throwing
• APIs that return Option<User> to make nullability explicit and composable
• Financial code using Cents/Dollars branded types and smart constructors to prevent unit mixing
• Migration approach: apply patterns to new features, refactor touched files, and prioritize high-risk domains like payments