sgse-app/.agent/rules/convex-typing.md

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:

// 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:

// 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:

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