Tipar Request e Response no Express 2026

// Interfaces do domínio
interface CreateProductBody {
  name: string;
  price: number;
  category: string;
  stock: number;
}

interface UpdateProductBody {
  name?: string;
  price?: number;
  category?: string;
  stock?: number;
}

// POST - body completo
app.post('/products',
  (req: Request<{}, {}, CreateProductBody>, res: Response) => {
    const { name, price, category, stock } = req.body;
    // Todos os campos com tipo correto e autocomplete
    console.log(name.toUpperCase()); // OK: name é string
    console.log(price.toFixed(2));   // OK: price é number
  }
);

// PUT - body parcial
app.put('/products/:id',
  (req: Request<{ id: string }, {}, UpdateProductBody>, res: Response) => {
    const { name, price } = req.body;
    // name e price podem ser undefined (campos opcionais)
    if (name) console.log(name.toUpperCase());
  }
);

// Params da rota
interface ProductParams {
  id: string;
  categorySlug: string;
}

// Query string
interface ProductQuery {
  page?: string;
  limit?: string;
  sort?: 'price' | 'name' | 'createdAt';
  order?: 'asc' | 'desc';
}

// Rota com params + query tipados
app.get('/categories/:categorySlug/products/:id',
  (req: Request<ProductParams, {}, {}, ProductQuery>, res: Response) => {
    const { id, categorySlug } = req.params;
    const { page, limit, sort, order } = req.query;

    // sort só aceita 'price' | 'name' | 'createdAt'
    // order só aceita 'asc' | 'desc'
    const pageNum = parseInt(page || '1', 10);
    const limitNum = parseInt(limit || '20', 10);

    res.json({ id, categorySlug, pageNum, limitNum, sort, order });
  }
);

// src/@types/express/index.d.ts
declare global {
  namespace Express {
    interface Request {
      userId?: string;
      userRole?: 'admin' | 'editor' | 'viewer';
      tenantId?: string;
      permissions?: string[];
    }
  }
}

export {}; // Necessário pra transformar em módulo

// Middleware de autenticação injeta os dados
app.use('/admin', (req: Request, res: Response, next) => {
  const decoded = verifyToken(req.headers.authorization);
  req.userId = decoded.sub;
  req.userRole = decoded.role;
  req.tenantId = decoded.tenantId;
  next();
});

// Handler usa os dados com tipo correto
app.get('/admin/dashboard', (req: Request, res: Response) => {
  // req.userId é string | undefined
  // req.userRole é 'admin' | 'editor' | 'viewer' | undefined
  if (req.userRole !== 'admin') {
    return res.status(403).json({ error: 'Acesso negado' });
  }
  res.json({ userId: req.userId, dashboard: '...' });
});

// Tipo de resposta padrão da API
interface ApiSuccess<T> {
  success: true;
  data: T;
  meta?: {
    page: number;
    total: number;
    limit: number;
  };
}

interface ApiError {
  success: false;
  error: string;
  code: number;
}

type ApiResponse<T> = ApiSuccess<T> | ApiError;

// Produto tipado
interface Product {
  id: string;
  name: string;
  price: number;
}

// Response tipado garante formato consistente
app.get('/products/:id',
  (req: Request<{ id: string }>, res: Response<ApiResponse<Product>>) => {
    const product = findProduct(req.params.id);

    if (!product) {
      // O compilador valida: precisa ter success, error e code
      return res.status(404).json({
        success: false,
        error: 'Produto nao encontrado',
        code: 404
      });
    }

    // Também valida: precisa ter success e data do tipo Product
    res.json({
      success: true,
      data: product
    });
  }
);

// Tipo auxiliar que simplifica a declaração
type TypedRequest<
  TBody = {},
  TParams = {},
  TQuery = {}
> = Request<TParams, {}, TBody, TQuery>;

// Agora os handlers ficam mais limpos
app.post('/orders',
  (req: TypedRequest<CreateOrderBody>, res: Response) => {
    const { items, address } = req.body;
    // Limpo e tipado
  }
);

app.get('/orders/:id',
  (req: TypedRequest<{}, { id: string }, { include?: string }>, res: Response) => {
    const { id } = req.params;
    const { include } = req.query;
    // Tudo tipado com helper
  }
);