programming-typescript

name	programming-typescript
user-invocable	false
description	Internal skill invoked by /programming chain. Use when writing, reviewing, or refactoring TypeScript, React, or Next.js code — enforcing type safety, fixing immutability violations, designing API routes with Zod validation, or structuring React components and hooks. Trigger keywords: TypeScript, tsx, jsx, React, Next.js, Node, Zod, useState, useEffect, useMemo, Promise.all, interface, type.

TypeScript Patterns

Type safety eliminates runtime errors; immutability prevents state bugs. Everything else follows.

Idiomatic TypeScript patterns for React/Next.js applications with Node.js backends.

When to Use

• Writing new TypeScript code (components, hooks, API routes, utilities)
• Reviewing TypeScript/React code for type safety and correctness
• Designing API endpoints with input validation
• Refactoring JavaScript to TypeScript

When NOT to Use

• Non-TypeScript projects (Python, Swift, etc.)
• Pure Node.js without TypeScript
• Vanilla JavaScript that won't be migrated

Type Safety

Use precise types — never any

// GOOD: Discriminated union
interface Market {
  id: string
  name: string
  status: 'active' | 'resolved' | 'closed'
  created_at: Date
}

function getMarket(id: string): Promise<Market> { ... }

// BAD: any erases all safety
function getMarket(id: any): Promise<any> { ... }

Exhaustive checks with never

function handleStatus(status: Market['status']): string {
  switch (status) {
    case 'active': return 'In progress'
    case 'resolved': return 'Complete'
    case 'closed': return 'Closed'
    default: {
      const _exhaustive: never = status
      throw new Error(`Unhandled status: ${_exhaustive}`)
    }
  }
}

Immutability

// ALWAYS use spread — never mutate
const updatedUser = { ...user, name: 'New Name' }
const updatedArray = [...items, newItem]
const filtered = items.filter(x => x.id !== removeId)

// BAD: mutation
user.name = 'New Name'
items.push(newItem)
items.splice(index, 1)

Use as const for literal types and readonly for arrays/objects that shouldn't change.

Error Handling

// GOOD: handle errors, wrap with context
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 from ${url}`)
  }
}

// BAD: unhandled
async function fetchData(url: string) {
  const response = await fetch(url)
  return response.json()  // No status check, no error handling
}

Async/Await

// GOOD: parallel when independent
const [users, markets, stats] = await Promise.all([
  fetchUsers(),
  fetchMarkets(),
  fetchStats()
])

// BAD: sequential when unnecessary
const users = await fetchUsers()
const markets = await fetchMarkets()  // Waits for users first — why?
const stats = await fetchStats()

React Components

Structure

interface ButtonProps {
  children: React.ReactNode
  onClick: () => void
  disabled?: boolean
  variant?: 'primary' | 'secondary'
}

export function Button({
  children,
  onClick,
  disabled = false,
  variant = 'primary'
}: ButtonProps) {
  return (
    <button
      onClick={onClick}
      disabled={disabled}
      className={`btn btn-${variant}`}
    >
      {children}
    </button>
  )
}

Hooks

// Custom hook — reusable logic
export function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value)

  useEffect(() => {
    const handler = setTimeout(() => setDebouncedValue(value), delay)
    return () => clearTimeout(handler)
  }, [value, delay])

  return debouncedValue
}

State updates

const [count, setCount] = useState(0)

// GOOD: functional update (never stale)
setCount(prev => prev + 1)

// BAD: can be stale in async/callback contexts
setCount(count + 1)

Conditional rendering

// GOOD: clear
{isLoading && <Spinner />}
{error && <ErrorMessage error={error} />}
{data && <DataDisplay data={data} />}

// BAD: ternary nesting
{isLoading ? <Spinner /> : error ? <ErrorMessage /> : data ? <DataDisplay /> : null}

Memoization

// Memoize expensive computations
const sortedMarkets = useMemo(
  () => markets.sort((a, b) => b.volume - a.volume),
  [markets]
)

// Memoize callbacks passed to children
const handleSearch = useCallback((query: string) => {
  setSearchQuery(query)
}, [])

API Design

REST conventions

GET    /api/markets              # List
GET    /api/markets/:id          # Get one
POST   /api/markets              # Create
PUT    /api/markets/:id          # Full update
PATCH  /api/markets/:id          # Partial update
DELETE /api/markets/:id          # Delete
GET    /api/markets?status=active&limit=10&offset=0  # Filter

Response format

interface ApiResponse<T> {
  success: boolean
  data?: T
  error?: string
  meta?: { total: number; page: number; limit: number }
}

// Success
return NextResponse.json({
  success: true,
  data: markets,
  meta: { total: 100, page: 1, limit: 10 }
})

// Error
return NextResponse.json(
  { success: false, error: 'Invalid request' },
  { status: 400 }
)

Input validation with Zod

import { z } from 'zod'

const CreateMarketSchema = z.object({
  name: z.string().min(1).max(200),
  description: z.string().min(1).max(2000),
  endDate: z.string().datetime(),
  categories: z.array(z.string()).min(1)
})

export async function POST(request: Request) {
  const body = await request.json()
  try {
    const validated = CreateMarketSchema.parse(body)
    // Proceed with validated data
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { success: false, error: 'Validation failed', : error. },
        { :  }
      )
    }
  }
}

File Organization

src/
├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   └── (auth)/            # Route groups
├── components/
│   ├── ui/                # Generic UI (Button, Modal, etc.)
│   ├── forms/             # Form components
│   └── layouts/           # Layout components
├── hooks/                 # Custom React hooks
├── lib/                   # Utilities, API clients, constants
├── types/                 # TypeScript type definitions
└── styles/                # Global styles

Naming: PascalCase for components (Button.tsx), camelCase with use prefix for hooks (useAuth.ts), camelCase for utilities (formatDate.ts).

Testing

// AAA pattern: Arrange, Act, Assert
test('returns empty array when no markets match query', () => {
  // Arrange
  const vector1 = [1, 0, 0]
  const vector2 = [0, 1, 0]

  // Act
  const similarity = calculateCosineSimilarity(vector1, vector2)

  // Assert
  expect(similarity).toBe(0)
})

Test names: describe the scenario and expected outcome, not just "works" or "test search".

Common Mistakes

Mistake	Fix
Using any to silence errors	Define proper types or use unknown
Mutating state/props directly	Use spread operator or structuredClone
Sequential awaits for independent calls	Use Promise.all
useEffect with missing deps	Include all referenced values in dependency array
Returning T | undefined without checking	Use narrowing, optional chaining, or nullish coalescing
console.log left in production	Use a logger with levels, strip in builds
Functions > 50 lines	Extract sub-functions with descriptive names
Deep nesting (5+ levels)	Use early returns / guard clauses