typescript

TypeScript

Constraints

• Zod-First: Write Zod schemas for API/Domain contracts. Derive types via z.infer.
• Strict: Operate in strict: true mode.
• Arrays: Use T[]. Use Array<T> only for nested types.
• Enums: Use z.enum or as const objects. Native enum is forbidden.
• Immutability: Use readonly or as const.
• Return Types: Explicitly define return types for exported functions.
• Generics: Use constraints (T extends object).
• Branded Types: Use branded types for IDs to prevent mix-ups (e.g., type TaskId = string & { readonly __brand: 'TaskId' }).
• Discriminated Unions: Use discriminated unions for managing variant states.
• Prefer Addition: Avoid breaking changes; extend interfaces with optional fields rather than modifying or deleting existing ones.

Bans

• any.
• as Type (except in tests).
• ! (Non-null assertion).
• Using Interface and Type simultaneously.
• I or T prefixes (IUser).
• Type soup (Pick<Omit<Partial<...>>> nesting > 2). Exception: Deriving Form schemas from API schemas using Zod's .pick(), .omit(), or .extend() is encouraged to maintain SSOT.

Correct Implementation

// Branded Types type UserId = string & { readonly __brand: 'UserId' };

// Discriminated Unions type TaskState = | { status: 'pending' } | { status: 'completed'; completedAt: Date } | { status: 'failed'; errorReason: string };

</example>

## Incorrect Implementation

<incorrect-example>
```ts
interface IUser { id: any; }
const user = data as User;