¿Qué hace Conocimiento de Tipos TypeScript del Frontend?
Propósito: Guía para crear definiciones de tipos TypeScript siguiendo los patrones existentes de frontend/types/index.ts.
Resumen
Todos los tipos de TypeScript se definen en frontend/types/index.ts. Los tipos coinciden con la estructura de respuesta de la API del backend y proporcionan seguridad de tipos en toda la aplicación frontend.
Patrones de Tipos de frontend/types/index.ts
1. Tipos de Usuario
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;
}
Patrón:
- Usar
interfacepara tipos de objeto - Marcar campos opcionales con
? - Usar
extendspara herencia de tipos - Usar camelCase para tipos del frontend (incluso si el backend usa snake_case)
2. Tipos de Tarea
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;
}
Patrón:
- Usar
typepara tipos unión (literales de cadena) - Usar
interfacepara tipos de objeto - Coincidir con los nombres de campo del backend (snake_case para campos de API como
user_id,due_date,created_at) - Crear tipos separados para datos de formulario (todos opcionales excepto los campos requeridos)
- Crear tipos separados para parámetros de consulta (todos opcionales)
3. Tipos de Respuesta de 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;
};
}
Patrón:
- Usar tipos genéricos
<T>para estructuras reutilizables - Proporcionar un parámetro de tipo por defecto (
<T = unknown>) - Incluir un indicador booleano
success - Incluir campos opcionales
data,messageyerror - Crear un tipo separado para respuestas paginadas con un objeto
meta
4. Tipos de Autenticación
export interface AuthResponse {
success: boolean;
token: string;
user: User;
}
export interface Session {
user: User;
token: string;
expiresAt: number;
}
Patrón:
- Incluir booleano
success - Incluir cadena
token - Incluir objeto
user(tipo User) - Incluir
expiresAtcomo marca de tiempo para la sesión
5. Tipos de Error
export interface AppError {
message: string;
code?: string;
statusCode?: number;
field?: string;
}
export interface FormErrors {
[key: string]: string | undefined;
}
Patrón:
- Usar
interfacepara objetos de error - Marcar campos opcionales con
? - Usar firma de índice
[key: string]para tipos dinámicos de objeto (FormErrors)
6. Tipos de IU
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;
}
Patrón:
- Usar
typepara tipos unión (literales de cadena) - Usar
interfacepara tipos de objeto - Incluir
idpara identificación única - Marcar campos opcionales con
?
7. Tipos de Exportación/Importación
export type ExportFormat = "csv" | "json";
export interface ImportResult {
imported: number;
errors: number;
errorDetails?: string[];
}
Patrón:
- Usar
typepara tipos unión (literales de cadena) - Usar
interfacepara objetos de resultado - Incluir contadores para seguimiento de éxito/error
- Incluir arreglo opcional de detalles de error
Convenciones de Nomenclatura de Tipos
Interfaces
- PascalCase:
User,Task,ApiResponse - Nombres descriptivos:
TaskFormData,UserSignupData
Tipos (Tipos Unión)
- PascalCase:
TaskStatus,TaskPriority,LoadingState - Nombres descriptivos:
ToastType,ExportFormat
Tipos de Props
- NombreDelComponente + Props:
TaskItemProps,ProtectedRouteProps - Ejemplo:
interface TaskItemProps { task: Task; }
Tipos de Datos de Formulario
- NombreDeLaEntidad + FormData:
TaskFormData,UserSignupData - Ejemplo:
interface TaskFormData { title: string; description?: string; }
Tipos de Parámetros de Consulta
- NombreDeLaEntidad + QueryParams:
TaskQueryParams - Ejemplo:
interface TaskQueryParams { status?: "all" | "pending" | "completed"; }
Coincidencia con el Esquema del Backend
Mapeo de Nombres de Campo
Backend (snake_case) → Frontend (camelCase para datos de formulario, snake_case para respuesta de API)
// Respuesta de API del backend (coincide exactamente con el backend)
export interface Task {
id: number;
user_id: string; // snake_case del backend
title: string;
due_date?: string; // snake_case del backend
created_at: string; // snake_case del backend
updated_at: string; // snake_case del backend
}
// Datos de formulario del frontend (camelCase para uso más fácil)
export interface TaskFormData {
title: string;
dueDate?: string; // camelCase para el frontend
tags?: string[];
}
Patrón:
- Los tipos de respuesta de API coinciden exactamente con el backend (snake_case)
- Los tipos de datos de formulario usan camelCase para un uso más fácil en el frontend
- Convertir entre formatos al enviar/recibir desde la API
Campos Requeridos vs Opcionales
// Respuesta de API del backend (todos los campos del backend)
export interface Task {
id: number; // Requerido (del backend)
user_id: string; // Requerido (del backend)
title: string; // Requerido (del backend)
description?: string; // Opcional (del backend)
completed: boolean; // Requerido (del backend)
priority: TaskPriority; // Requerido (del backend)
due_date?: string; // Opcional (del backend)
tags: string[]; // Requerido (del backend, puede ser arreglo vacío)
created_at: string; // Requerido (del backend)
updated_at: string; // Requerido (del backend)
}
// Datos de formulario del frontend (solo campos que el usuario puede editar)
export interface TaskFormData {
title: string; // Requerido (el usuario debe proporcionarlo)
description?: string; // Opcional
priority?: TaskPriority; // Opcional (tiene valor por defecto)
due_date?: string; // Opcional
tags?: string[]; // Opcional (puede ser arreglo vacío)
}
Patrón:
- Los tipos de respuesta de API incluyen todos los campos del backend
- Los tipos de datos de formulario solo incluyen campos que el usuario puede editar
- Marcar campos opcionales con
? - Los campos requeridos no tienen
?
Patrones de Estructura de Tipos
1. Usar interface para Objetos
export interface User {
id: string;
email: string;
}
Cuándo usar: Tipos de objeto con propiedades
2. Usar type para Uniones, Intersecciones o Alias
export type TaskStatus = "pending" | "completed";
export type TaskPriority = "low" | "medium" | "high";
Cuándo usar: Tipos unión, intersecciones o alias de tipos
3. Usar Tipos Genéricos para Estructuras Reutilizables
export interface ApiResponse<T = unknown> {
data?: T;
success: boolean;
}
Cuándo usar: Estructuras reutilizables que funcionan con diferentes tipos
4. Marcar Propiedades Opcionales con ?
export interface Task {
title: string; // Requerido
description?: string; // Opcional
}
Cuándo usar: Campos que pueden no existir
Ejemplo Completo: Agregar Nuevos Tipos
Paso 1: Definir el Tipo de Entidad (coincide con el backend)
export interface Category {
id: number;
user_id: string;
name: string;
color?: string;
created_at: string;
updated_at: string;
}
Paso 2: Definir el Tipo de Datos de Formulario (para entrada del usuario)
export interface CategoryFormData {
name: string;
color?: string;
}
Paso 3: Definir el Tipo de Parámetros de Consulta (para consultas de API)
export interface CategoryQueryParams {
search?: string;
page?: number;
limit?: number;
}
Paso 4: Usar en el Cliente de API
async getCategories(
userId: string,
queryParams?: CategoryQueryParams
): Promise<ApiResponse<PaginatedResponse<Category>>> {
// Implementación
}
Requisitos de la Constitución
- FR-030: Interfaces TypeScript con tipos para todas las llamadas a la API ✅
- FR-037: Modo estricto de TypeScript ✅
Referencias
- Especificación:
specs/002-frontend-todo-app/spec.md- Definiciones de entidad - Plan:
specs/002-frontend-todo-app/plan.md- Contratos de API con tipos - Archivo de Tipos:
frontend/types/index.ts- Definiciones de tipos completas
Resumen de Patrones Comunes
- ✅ Usar
interfacepara tipos de objeto - ✅ Usar
typepara tipos unión (literales de cadena) - ✅ Usar tipos genéricos
<T>para estructuras reutilizables - ✅ Marcar campos opcionales con
? - ✅ Coincidir con los nombres de campo del backend (snake_case para respuestas de API)
- ✅ Usar camelCase para tipos de datos de formulario
- ✅ Crear tipos separados para datos de formulario y parámetros de consulta
- ✅ Usar nombres descriptivos (EntityFormData, EntityQueryParams)
- ✅ Incluir todos los campos requeridos del backend
- ✅ Proporcionar parámetros de tipo por defecto para genéricos (
<T = unknown>)