ts-best-practices

name

ts-best-practices

description

TypeScript type safety guidelines for writing maximally type-safe code. Apply these patterns when writing or reviewing any TypeScript: discriminated unions, type narrowing, type guards, exhaustiveness checks, avoiding `as` casts, preferring `unknown` over `any`, and making impossible states unrepresentable. Use this skill whenever writing TypeScript code, reviewing TypeScript for type safety issues, or when the user mentions type safety, type narrowing, discriminated unions, or asks to make types stricter/more explicit.

Type Safety

This project's TypeScript policy. Apply when writing or reviewing TypeScript.

Rule	Summary
No as casts	Every as is a potential runtime crash. Validate at boundaries, then cast only if earned. Prefer Zod/Valibot over manual validation.
unknown over any	any disables type checking for everything it touches. External data is always unknown.
Discriminated unions	Model variants with a shared literal discriminant. No optional-field bags.
Narrowing hierarchy	Prefer: discriminated union switch > in operator > typeof/instanceof > type guard > as
Type guards	Must actually verify the claim. Name them isX or hasX. Prefer discriminant narrowing when possible.
Exhaustiveness checks	Always add default: never arm to switches over discriminated unions. Use an absurd() helper to reduce boilerplate.
satisfies over as	When verifying a value matches a type without widening, use satisfies to preserve literal types.
Impossible states	If a bug requires asking "can this combination happen?" the type is too loose. Tighten it.
Omit return types	Don't annotate return types unless they add value (e.g. public API, recursive functions, overloads). Let inference do the work.

Read references/patterns.md for code examples of each rule.