When working with React components (.tsx, .jsx files or @react imports), always load react-best-practices alongside this skill. This skill covers TypeScript fundamentals; React-specific patterns (effects, hooks, refs, component design) are in the dedicated React skill.
Type-First Development
Types define the contract before implementation. Follow this workflow:
Define the data model - types, interfaces, and schemas first
Define function signatures - input/output types before logic
Implement to satisfy types - let the compiler guide completeness
Validate at boundaries - runtime checks where data enters the system
Make Illegal States Unrepresentable
Use the type system to prevent invalid states at compile time.
Discriminated unions for mutually exclusive states:
// Good: only valid combinations possible
type RequestState<T> =
| { status: 'idle' }
| { status: 'loading' }
| { status: 'success'; data: T }
| { status: 'error'; error: Error };
// Bad: allows invalid combinations like { loading: true, error: Error }
type RequestState<T> = {
loading: boolean;
data?: T;
error?: Error;
};
type UserId = string & { readonly __brand: 'UserId' };
type OrderId = string & { readonly __brand: 'OrderId' };
// 编译器阻止在期望 UserId 的地方传递 OrderId
function getUser(id: UserId): Promise<User> { /* ... */ }
function createUserId(id: string): UserId {
return id as UserId;
}
使用常量断言表示字面量联合：
const ROLES = ['admin', 'user', 'guest'] as const;
type Role = typeof ROLES[number]; // 'admin' | 'user' | 'guest'
// 数组和类型自动保持同步
function isValidRole(role: string): role is Role {
return ROLES.includes(role as Role);
}
必需字段与可选字段 - 明确指定：
// 创建：某些字段必需
type CreateUser = {
email: string;
name: string;
};
// 更新：所有字段可选
type UpdateUser = Partial<CreateUser>;
// 数据库行：所有字段都存在
type User = CreateUser & {
id: UserId;
createdAt: Date;
};
type UserId = string & { readonly __brand: 'UserId' };
type OrderId = string & { readonly __brand: 'OrderId' };
// Compiler prevents passing OrderId where UserId expected
function getUser(id: UserId): Promise<User> { /* ... */ }
function createUserId(id: string): UserId {
return id as UserId;
}
Const assertions for literal unions:
const ROLES = ['admin', 'user', 'guest'] as const;
type Role = typeof ROLES[number]; // 'admin' | 'user' | 'guest'
// Array and type stay in sync automatically
function isValidRole(role: string): role is Role {
return ROLES.includes(role as Role);
}
Required vs optional fields - be explicit:
// Creation: some fields required
type CreateUser = {
email: string;
name: string;
};
// Update: all fields optional
type UpdateUser = Partial<CreateUser>;
// Database row: all fields present
type User = CreateUser & {
id: UserId;
createdAt: Date;
};
Module Structure
Prefer smaller, focused files: one component, hook, or utility per file. Split when a file handles multiple concerns or exceeds ~200 lines. Colocate tests with implementation (foo.test.ts alongside foo.ts). Group related files by feature rather than by type.
Functional Patterns
Prefer const over let; use readonly and Readonly<T> for immutable data.
Use array.map/filter/reduce over for loops; chain transformations in pipelines.
Write pure functions for business logic; isolate side effects in dedicated modules.
Avoid mutating function parameters; return new objects/arrays instead.
Instructions
Enable strict mode; model data with interfaces and types. Strong typing catches bugs at compile time.
Every code path returns a value or throws; use exhaustive switch with never checks in default. Unhandled cases become compile errors.
Propagate errors with context; catching requires re-throwing or returning a meaningful result. Hidden failures delay debugging.
