typescript-type-safe-api-contracts

# TypeScript Type-Safe API Contracts ## Core Principle: Explicit Return Types (Mandatory) ```tsx // ❌ BAD: Implicit return type export function getUser(id: string) { return db.user.findUnique({ where: { id } }); } // ✅ GOOD: Explicit return type export async function getUser(id: string): Promise<User | null> { return db.user.findUnique({ where: { id } }); } ``` ## Interface vs Type **Use `interface` for object shapes**: ```tsx interface User { id: string; name: string; email: string; } interface ApiResponse<T> { success: boolean; data: T; } ``` **Use `type` for unions, intersections, utilities**: ```tsx type Status = 'pending' | 'active' | 'archived'; type ApiResult<T> = | { success: true; data: T } | { success: false; error: string }; ``` ## Generic API Response Wrapper ```tsx // types/api/common.ts export type ApiResponse<T> = | ApiSuccessResponse<T> | ApiErrorResponse; export interface ApiSuccessResponse<T> { success: true; data: T; } export interface ApiErrorResponse { success: false; error: { code: string; message: string; details?: Record<string, string[]>; }; } // Usage export async function createUser(data: CreateUserInput): Promise<ApiResponse<User>> { // ... } ``` ## Zod Integration (Runtime Validation) ```tsx import { z } from 'zod'; // 1. Define Zod schema const userSchema = z.object({ name: z.string().min(1, 'Name required').max(100), email: z.string().email('Invalid email'), age: z.number().in...