---
trigger: glob
description: Regras de tipagem para queries e mutations do Convex
globs: *.svelte.ts,*.svelte
---

# Regras de Tipagem do Convex

## Regra Principal

**NUNCA** crie anotações de tipo manuais para queries ou mutations do Convex. Os tipos já são inferidos automaticamente pelo Convex.

### ❌ Errado - Não faça isso:

```typescript
// NÃO crie tipos manuais para o retorno de queries
type Funcionario = {
	_id: Id<'funcionarios'>;
	nome: string;
	email: string;
	// ... outras propriedades
};

const funcionarios: Funcionario[] = useQuery(api.funcionarios.getAll) ?? [];
```

### ✅ Correto - Use inferência automática:

```typescript
// O tipo já vem inferido automaticamente
const funcionarios = useQuery(api.funcionarios.getAll);
```

---

## Quando Tipar É Necessário

Em situações onde você **realmente precisa** de um tipo explícito (ex: props de componentes, variáveis de estado, etc.), use `FunctionReturnType` para inferir o tipo:

```typescript
import { FunctionReturnType } from 'convex/server';
import { api } from '$convex/_generated/api';

// Infere o tipo de retorno da query
type FuncionariosQueryResult = FunctionReturnType<typeof api.funcionarios.getAll>;

// Agora pode usar em props de componentes
interface Props {
	funcionarios: FuncionariosQueryResult;
}
```

### Casos de Uso Válidos para `FunctionReturnType`:

1. **Props de componentes** - quando um componente filho recebe dados de uma query
2. **Variáveis derivadas** - quando precisa tipar uma transformação dos dados
3. **Funções auxiliares** - quando cria funções que operam sobre os dados da query
4. **Stores/Estado global** - quando armazena dados em estado externo ao componente

---

## Resumo

| Situação                    | Abordagem                                         |
| --------------------------- | ------------------------------------------------- |
| Usar `useQuery` diretamente | Deixe o tipo ser inferido automaticamente         |
| Props de componentes        | Use `FunctionReturnType<typeof api.module.query>` |
| Transformações de dados     | Use `FunctionReturnType<typeof api.module.query>` |
| Anotações manuais de tipo   | **NUNCA** - sempre infira do Convex               |