Skill de Tipos TypeScript no Frontend
Propósito: Orientação para criação de definições de tipos TypeScript seguindo padrões existentes em frontend/types/index.ts.
Visão Geral
Todos os tipos TypeScript são definidos em frontend/types/index.ts. Os tipos correspondem à estrutura de resposta da API de backend e fornecem segurança de tipos em toda a aplicação frontend.
Padrões de Tipos de frontend/types/index.ts
1. Tipos de Usuário
export interface User {
id: string;
email: string;
name: string;
createdAt?: string;
updatedAt?: string;
}
export interface UserCredentials {
email: string;
password: string;
}
export interface UserSignupData extends UserCredentials {
name: string;
}
Padrão:
- Use
interfacepara tipos de objeto - Marque campos opcionais com
? - Use
extendspara herança de tipos - Use camelCase para tipos do frontend (mesmo que o backend use snake_case)
2. Tipos de Tarefa
export type TaskStatus = "pending" | "completed";
export type TaskPriority = "low" | "medium" | "high";
export interface Task {
id: number;
user_id: string;
title: string;
description?: string;
completed: boolean;
priority: TaskPriority;
due_date?: string;
tags: string[];
created_at: string;
updated_at: string;
}
export interface TaskFormData {
title: string;
description?: string;
priority?: TaskPriority;
due_date?: string;
tags?: string[];
}
export interface TaskQueryParams {
status?: "all" | "pending" | "completed";
sort?: "created" | "title" | "updated" | "priority" | "due_date";
search?: string;
page?: number;
limit?: number;
}
Padrão:
- Use
typepara tipos de união (literais de string) - Use
interfacepara tipos de objeto - Corresponda aos nomes de campos do backend (snake_case para campos da API como
user_id,due_date,created_at) - Crie tipos separados para dados de formulário (todos opcionais, exceto campos obrigatórios)
- Crie tipos separados para parâmetros de consulta (todos opcionais)
3. Tipos de Resposta da API
export interface ApiResponse<T = unknown> {
data?: T;
success: boolean;
message?: string;
error?: {
code: string;
message: string;
details?: unknown;
};
}
export interface PaginatedResponse<T> {
data: T[];
meta: {
total: number;
page: number;
limit: number;
totalPages: number;
};
}
Padrão:
- Use tipos genéricos
<T>para estruturas reutilizáveis - Forneça um parâmetro de tipo padrão (
<T = unknown>) - Inclua um sinalizador booleano
success - Inclua campos opcionais
data,messageeerror - Crie um tipo separado para respostas paginadas com objeto
meta
4. Tipos de Autenticação
export interface AuthResponse {
success: boolean;
token: string;
user: User;
}
export interface Session {
user: User;
token: string;
expiresAt: number;
}
Padrão:
- Inclua booleano
success - Inclua string
token - Inclua objeto
user(tipo User) - Inclua timestamp
expiresAtpara sessão
5. Tipos de Erro
export interface AppError {
message: string;
code?: string;
statusCode?: number;
field?: string;
}
export interface FormErrors {
[key: string]: string | undefined;
}
Padrão:
- Use
interfacepara objetos de erro - Marque campos opcionais com
? - Use assinatura de índice
[key: string]para tipos de objeto dinâmicos (FormErrors)
6. Tipos de UI
export type LoadingState = "idle" | "loading" | "success" | "error";
export type ToastType = "success" | "error" | "warning" | "info";
export interface ToastMessage {
id: string;
type: ToastType;
message: string;
duration?: number;
}
Padrão:
- Use
typepara tipos de união (literais de string) - Use
interfacepara tipos de objeto - Inclua
idpara identificação única - Marque campos opcionais com
?
7. Tipos de Exportação/Importação
export type ExportFormat = "csv" | "json";
export interface ImportResult {
imported: number;
errors: number;
errorDetails?: string[];
}
Padrão:
- Use
typepara tipos de união (literais de string) - Use
interfacepara objetos de resultado - Inclua contagens para rastreamento de sucesso/erro
- Inclua array opcional de detalhes de erro
Convenções de Nomenclatura de Tipos
Interfaces
- PascalCase:
User,Task,ApiResponse - Nomes descritivos:
TaskFormData,UserSignupData
Tipos (Tipos de União)
- PascalCase:
TaskStatus,TaskPriority,LoadingState - Nomes descritivos:
ToastType,ExportFormat
Tipos de Props
- ComponentName + Props:
TaskItemProps,ProtectedRouteProps - Exemplo:
interface TaskItemProps { task: Task; }
Tipos de Dados de Formulário
- EntityName + FormData:
TaskFormData,UserSignupData - Exemplo:
interface TaskFormData { title: string; description?: string; }
Tipos de Parâmetros de Consulta
- EntityName + QueryParams:
TaskQueryParams - Exemplo:
interface TaskQueryParams { status?: "all" | "pending" | "completed"; }
Correspondência com o Esquema do Backend
Mapeamento de Nomes de Campos
Backend (snake_case) → Frontend (camelCase para dados de formulário, snake_case para resposta da API)
// Resposta da API do backend (corresponde exatamente ao backend)
export interface Task {
id: number;
user_id: string; // snake_case do backend
title: string;
due_date?: string; // snake_case do backend
created_at: string; // snake_case do backend
updated_at: string; // snake_case do backend
}
// Dados de formulário do frontend (camelCase para uso mais fácil)
export interface TaskFormData {
title: string;
dueDate?: string; // camelCase para o frontend
tags?: string[];
}
Padrão:
- Os tipos de resposta da API correspondem exatamente ao backend (snake_case)
- Os tipos de dados de formulário usam camelCase para uso mais fácil no frontend
- Converta entre formatos ao enviar/receber da API
Campos Obrigatórios vs Opcionais
// Resposta da API do backend (todos os campos do backend)
export interface Task {
id: number; // Obrigatório (do backend)
user_id: string; // Obrigatório (do backend)
title: string; // Obrigatório (do backend)
description?: string; // Opcional (do backend)
completed: boolean; // Obrigatório (do backend)
priority: TaskPriority; // Obrigatório (do backend)
due_date?: string; // Opcional (do backend)
tags: string[]; // Obrigatório (do backend, pode ser array vazio)
created_at: string; // Obrigatório (do backend)
updated_at: string; // Obrigatório (do backend)
}
// Dados de formulário do frontend (apenas campos que o usuário pode editar)
export interface TaskFormData {
title: string; // Obrigatório (usuário deve fornecer)
description?: string; // Opcional
priority?: TaskPriority; // Opcional (tem valor padrão)
due_date?: string; // Opcional
tags?: string[]; // Opcional (pode ser array vazio)
}
Padrão:
- Os tipos de resposta da API incluem todos os campos do backend
- Os tipos de dados de formulário incluem apenas campos que o usuário pode editar
- Marque campos opcionais com
? - Campos obrigatórios não têm
?
Padrões de Estrutura de Tipos
1. Use interface para Objetos
export interface User {
id: string;
email: string;
}
Quando usar: Tipos de objeto com propriedades
2. Use type para Uniões, Interseções ou Apelidos
export type TaskStatus = "pending" | "completed";
export type TaskPriority = "low" | "medium" | "high";
Quando usar: Tipos de união, interseções ou apelidos de tipo
3. Use Tipos Genéricos para Estruturas Reutilizáveis
export interface ApiResponse<T = unknown> {
data?: T;
success: boolean;
}
Quando usar: Estruturas reutilizáveis que funcionam com diferentes tipos
4. Marque Propriedades Opcionais com ?
export interface Task {
title: string; // Obrigatório
description?: string; // Opcional
}
Quando usar: Campos que podem não existir
Exemplo Completo: Adicionando Novos Tipos
Passo 1: Definir Tipo da Entidade (corresponde ao backend)
export interface Category {
id: number;
user_id: string;
name: string;
color?: string;
created_at: string;
updated_at: string;
}
Passo 2: Definir Tipo de Dados do Formulário (para entrada do usuário)
export interface CategoryFormData {
name: string;
color?: string;
}
Passo 3: Definir Tipo de Parâmetros de Consulta (para consultas da API)
export interface CategoryQueryParams {
search?: string;
page?: number;
limit?: number;
}
Passo 4: Usar no Cliente API
async getCategories(
userId: string,
queryParams?: CategoryQueryParams
): Promise<ApiResponse<PaginatedResponse<Category>>> {
// Implementação
}
Requisitos Constitucionais
- FR-030: Interfaces TypeScript tipadas para todas as chamadas de API ✅
- FR-037: Modo estrito TypeScript ✅
Referências
- Especificação:
specs/002-frontend-todo-app/spec.md- Definições de entidade - Plano:
specs/002-frontend-todo-app/plan.md- Contratos de API com tipos - Arquivo de Tipos:
frontend/types/index.ts- Definições completas de tipos
Resumo de Padrões Comuns
- ✅ Use
interfacepara tipos de objeto - ✅ Use
typepara tipos de união (literais de string) - ✅ Use tipos genéricos
<T>para estruturas reutilizáveis - ✅ Marque campos opcionais com
? - ✅ Corresponda aos nomes de campos do backend (snake_case para respostas da API)
- ✅ Use camelCase para tipos de dados de formulário
- ✅ Crie tipos separados para dados de formulário e parâmetros de consulta
- ✅ Use nomes descritivos (EntityFormData, EntityQueryParams)
- ✅ Inclua todos os campos obrigatórios do backend
- ✅ Forneça parâmetros de tipo padrão para genéricos (
<T = unknown>)