TypeScript Best Practices for Production Applications

Frontend Client

import type { GenerateDemandLetterRequest, GenerateDemandLetterResponse } from '@/types/api';

async function generateDemandLetter(data: GenerateDemandLetterRequest) {
  const response = await fetch('/api/generate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  });

  // Fully typed response!
  const result: GenerateDemandLetterResponse = await response.json();

  if (result.success) {
    console.log(`Generated doc: ${result.documentId}`);
    console.log(`Cost: $${result.costUsd}`);
  }
}

import { z } from 'zod';

// Define schema
const DemandLetterRequestSchema = z.object({
  caseId: z.string().uuid(),
  clientName: z.string().min(1).max(100),
  medicalRecords: z.array(z.instanceof(File)).min(1).max(50),
  model: z.enum(['gpt-4', 'claude-3']).optional().default('gpt-4')
});

// Infer TypeScript type from Zod schema
type DemandLetterRequest = z.infer<typeof DemandLetterRequestSchema>;

// API route with validation
export async function POST(request: Request) {
  const body = await request.json();

  // Validate runtime data
  const result = DemandLetterRequestSchema.safeParse(body);

  if (!result.success) {
    return Response.json({
      error: 'Invalid request',
      code: 'INVALID_INPUT',
      details: result.error.flatten()
    }, { status: 400 });
  }

  // result.data is fully typed and validated!
  const { caseId, clientName, medicalRecords, model } = result.data;
}

// Define all possible states
type AsyncState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: string };

// Usage
function DemandLetterGenerator() {
  const [state, setState] = useState<AsyncState<string>>({ status: 'idle' });

  // TypeScript knows which properties exist based on status
  if (state.status === 'success') {
    console.log(state.data); // ✓ data exists
    // console.log(state.error); // ✗ TypeScript error!
  }

  if (state.status === 'error') {
    console.log(state.error); // ✓ error exists
    // console.log(state.data); // ✗ TypeScript error!
  }

  return (
    <div>
      {state.status === 'idle' && <button>Generate</button>}
      {state.status === 'loading' && <Spinner />}
      {state.status === 'success' && <Document content={state.data} />}
      {state.status === 'error' && <Error message={state.error} />}
    </div>
  );
}

// Type guard function
function isApiError(response: unknown): response is ApiError {
  return (
    typeof response === 'object' &&
    response !== null &&
    'error' in response &&
    'code' in response
  );
}

// Usage
async function callApi() {
  const response = await fetch('/api/generate');
  const data = await response.json();

  // Type guard narrows the type
  if (isApiError(data)) {
    // TypeScript knows data is ApiError here
    console.error(`Error ${data.code}: ${data.error}`);

    if (data.retryAfter) {
      setTimeout(() => callApi(), data.retryAfter * 1000);
    }
  } else {
    // TypeScript knows data is success response here
    console.log('Success:', data.documentId);
  }
}

// Reusable type guard for arrays
function isNonEmptyArray<T>(arr: T[]): arr is [T, ...T[]] {
  return arr.length > 0;
}

const files = uploadedFiles.filter(f => f.size > 0);
if (isNonEmptyArray(files)) {
  // TypeScript knows files has at least one element
  const firstFile = files[0]; // No undefined check needed!
}

// Generic API call wrapper
async function apiCall<TRequest, TResponse>(
  endpoint: string,
  data: TRequest
): Promise<TResponse> {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    throw new Error(`API call failed: ${response.statusText}`);
  }

  return response.json() as Promise<TResponse>;
}

// Fully typed usage
const result = await apiCall<GenerateDemandLetterRequest, GenerateDemandLetterResponse>(
  '/api/generate',
  {
    caseId: '123',
    clientName: 'John Doe',
    medicalRecords: files
  }
);

// result is typed as GenerateDemandLetterResponse
console.log(result.documentId, result.tokensUsed);

// Generic state hook
function useAsyncState<T>() {
  const [state, setState] = useState<AsyncState<T>>({ status: 'idle' });

  const execute = async (promise: Promise<T>) => {
    setState({ status: 'loading' });
    try {
      const data = await promise;
      setState({ status: 'success', data });
    } catch (error) {
      setState({ status: 'error', error: String(error) });
    }
  };

  return { state, execute };
}

// Usage
const { state, execute } = useAsyncState<string>();
await execute(generateDemandLetter(data));