typescript_skill

Overview

This skill documents strict TypeScript patterns and best practices for defining types, interfaces, and generics. It focuses on maintainable, type-safe code: const-backed unions, flat interfaces, avoiding any, utility types, type guards, and import-time type syntax. Use it as a checklist when writing or reviewing TypeScript in strict mode.

How this skill works

Define runtime constant objects first and derive union types from them to keep a single source of truth and enable autocomplete. Keep interfaces flat by extracting nested shapes into their own interfaces. Replace any with unknown, type guards, or generics. Leverage built-in utility types and import types explicitly to keep type-only imports clear.

When to use it

• When creating enumerated string unions that must match runtime values
• When designing domain models with nested objects or inheritance
• When you need safe parsing or validation of external data
• When writing reusable functions that require flexible typing via generics
• When importing types across modules to avoid runtime overhead

Best practices

• Create const objects and derive union types: const X = { ... } as const; type T = (typeof X)[keyof typeof X];
• Keep interfaces one level deep; extract nested objects into named interfaces for reuse and clarity
• Never use any; prefer unknown + type guards or generics for safe flexibility
• Use built-in utility types (Pick, Omit, Partial, Required, Readonly, Record, Extract, Exclude, NonNullable, ReturnType, Parameters) to express intent
• Write type guards (value is Type) for runtime checks and safe narrowing
• Use import type and inline type imports to separate type-only dependencies from runtime code

Example use cases

• Defining status or role enums where values must exist at runtime and be exhaustively referenced
• Modeling domain objects (User, Address, Admin) with reusable sub-interfaces and derived types
• Implementing safe parsers for JSON input using unknown and type guards before casting
• Creating generic utilities like first<T>(arr: T[]): T | undefined to preserve type information
• Refactoring code safely: change a const value and have derived types and autocomplete update automatically