# TypeScript & React Patterns ## Variable Naming ```typescript // ✅ GOOD: Descriptive names const marketSearchQuery = 'election' const isUserAuthenticated = true const totalRevenue = 1000 // ❌ BAD: Unclear names const q = 'election' const flag = true const x = 1000 ``` ## Function Naming ```typescript // ✅ GOOD: Verb-noun pattern async function fetchMarketData(marketId: string) { } function calculateSimilarity(a: number[], b: number[]) { } function isValidEmail(email: string): boolean { } // ❌ BAD: Unclear or noun-only async function market(id: string) { } function similarity(a, b) { } function email(e) { } ``` ## Immutability Pattern (CRITICAL) ```typescript // ✅ ALWAYS use spread operator const updatedUser = { ...user, name: 'New Name' } const updatedArray = [...items, newItem] // ❌ NEVER mutate directly user.name = 'New Name' // BAD items.push(newItem) // BAD ``` ## Error Handling ```typescript // ✅ GOOD: Comprehensive error handling async function fetchData(url: string) { try { const response = await fetch(url) if (!response.ok) { throw new Error(`HTTP ${response.status}: ${response.statusText}`) } return await response.json() } catch (error) { console.error('Fetch failed:', error) throw new Error('Failed to fetch data') } } // ❌ BAD: No error handling async function fetchData(url) { const response = await fetch(url) return response.json() } ``` ## Async/Await Best Practices ```typescript // ✅ GOOD: Parallel execution when possible const [users, markets, stats] = await Promise.all([ fetchUsers(), fetchMarkets(), fetchStats() ]) // ❌ BAD: Sequential when unnecessary const users = await fetchUsers() const markets = await fetchMarkets() const stats = await fetchStats() ``` ## Type Safety ```typescript // ✅ GOOD: Proper types interface Market { id: string name: string status: 'active' | 'resolved' | 'closed' created_at: Date } function getMarket(id: string): Promise { // Implementation } // ❌ BAD: Using 'any' function getMarket(id: any): Promise { // Implementation } ``` ## React Component Structure ```typescript // ✅ GOOD: Functional component with types interface ButtonProps { children: React.ReactNode onClick: () => void disabled?: boolean variant?: 'primary' | 'secondary' } export function Button({ children, onClick, disabled = false, variant = 'primary' }: ButtonProps) { return ( ) } // ❌ BAD: No types, unclear structure export function Button(props) { return } ``` ## Custom Hooks ```typescript // ✅ GOOD: Reusable custom hook export function useDebounce(value: T, delay: number): T { const [debouncedValue, setDebouncedValue] = useState(value) useEffect(() => { const handler = setTimeout(() => { setDebouncedValue(value) }, delay) return () => clearTimeout(handler) }, [value, delay]) return debouncedValue } ``` ## State Management ```typescript // ✅ GOOD: Functional update for state based on previous state const [count, setCount] = useState(0) setCount(prev => prev + 1) // ❌ BAD: Direct state reference (can be stale in async scenarios) setCount(count + 1) ``` ## Conditional Rendering ```typescript // ✅ GOOD: Clear conditional rendering {isLoading && } {error && } {data && } // ❌ BAD: Ternary hell {isLoading ? : error ? : data ? : null} ``` ## Performance ### Memoization ```typescript import { useMemo, useCallback } from 'react' const sortedMarkets = useMemo(() => { return markets.sort((a, b) => b.volume - a.volume) }, [markets]) const handleSearch = useCallback((query: string) => { setSearchQuery(query) }, []) ``` ### Lazy Loading ```typescript import { lazy, Suspense } from 'react' const HeavyChart = lazy(() => import('./HeavyChart')) export function Dashboard() { return ( }> ) } ``` ## File Naming ``` components/Button.tsx # PascalCase for components hooks/useAuth.ts # camelCase with 'use' prefix lib/formatDate.ts # camelCase for utilities types/market.types.ts # camelCase with .types suffix ``` ## Comments ```typescript // ✅ GOOD: Explain WHY, not WHAT // Use exponential backoff to avoid overwhelming the API during outages const delay = Math.min(1000 * Math.pow(2, retryCount), 30000) // ❌ BAD: Stating the obvious // Increment counter by 1 count++ ``` ## JSDoc for Public APIs ```typescript /** * Searches markets using semantic similarity. * * @param query - Natural language search query * @param limit - Maximum number of results (default: 10) * @returns Array of markets sorted by similarity score * @throws {Error} If API fails or service unavailable */ export async function searchMarkets( query: string, limit: number = 10 ): Promise { // Implementation } ```