typescript

Write type-safe TypeScript with proper narrowing, inference patterns, and strict mode best practices.

When to Use

User needs TypeScript expertise — from basic typing to advanced generics. Agent handles type narrowing, inference, discriminated unions, and strict mode patterns.

Quick Reference

Topic	File
Generic patterns	generics.md
Utility types	utility-types.md
Declaration files	declarations.md
Migration from JS	migration.md

Stop Using any

• unknown forces you to narrow before use — any silently breaks type safety
• API responses: type them or use unknown, never any
• When you don't know the type, that's unknown, not any

Narrowing Failures

• filter(Boolean) doesn't narrow — use .filter((x): x is T => Boolean(x))
• Object.keys(obj) returns string[], not keyof typeof obj — intentional, objects can have extra keys
• Array.isArray() narrows to any[] — may need assertion for element type
• in operator narrows but only if property is in exactly one branch of union

Literal Type Traps

• let x = "hello" is string — use const or as const for literal type
• Object properties widen: { status: "ok" } has status: string — use as const or type annotation
• Function return types widen — annotate explicitly for literal returns

Inference Limits

• Callbacks lose inference in some array methods — annotate parameter when TS guesses wrong
• Generic functions need usage to infer — fn<T>() can't infer, pass a value or annotate
• Nested generics often fail — break into steps with explicit types

Discriminated Unions

• Add a literal type or kind field to each variant — enables exhaustive switch
• Exhaustive check: default: const _never: never = x — compile error if case missed
• Don't mix discriminated with optional properties — breaks narrowing

satisfies vs Type Annotation

• const x: Type = val widens to Type — loses literal info
• const x = val satisfies Type keeps literal, checks compatibility — prefer for config objects

Strict Null Handling

• Optional chaining ?. returns undefined, not null — matters for APIs expecting null
• ?? only catches null/undefined — || catches all falsy including 0 and ""
• Non-null ! should be last resort — prefer narrowing or early return

Module Boundaries

• import type for type-only imports — stripped at runtime, avoids bundler issues
• Re-exporting types: export type { X } — prevents accidental runtime dependency
• .d.ts augmentation: use declare module with exact module path