Compétence de Types TypeScript Frontend
Objectif : Guide pour la création de définitions de types TypeScript en suivant les modèles existants de frontend/types/index.ts.
Vue d'ensemble
Tous les types TypeScript sont définis dans frontend/types/index.ts. Les types correspondent à la structure des réponses API backend et assurent la sécurité de typage dans toute l'application frontend.
Modèles de types de frontend/types/index.ts
1. Types utilisateur
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;
}
Modèle :
- Utiliser
interfacepour les types objet - Marquer les champs facultatifs avec
? - Utiliser
extendspour l'héritage de types - Utiliser camelCase pour les types frontend (même si le backend utilise snake_case)
2. Types de tâches
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;
}
Modèle :
- Utiliser
typepour les types union (littéraux de chaîne) - Utiliser
interfacepour les types objet - Faire correspondre les noms de champs du backend (snake_case pour les champs API comme
user_id,due_date,created_at) - Créer des types séparés pour les données de formulaire (tous facultatifs sauf les champs obligatoires)
- Créer des types séparés pour les paramètres de requête (tous facultatifs)
3. Types de réponse 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;
};
}
Modèle :
- Utiliser des types génériques
<T>pour les structures réutilisables - Fournir un paramètre de type par défaut (
<T = unknown>) - Inclure un indicateur booléen
success - Inclure les champs facultatifs
data,messageeterror - Créer un type séparé pour les réponses paginées avec l'objet
meta
4. Types d'authentification
export interface AuthResponse {
success: boolean;
token: string;
user: User;
}
export interface Session {
user: User;
token: string;
expiresAt: number;
}
Modèle :
- Inclure le booléen
success - Inclure la chaîne
token - Inclure l'objet
user(type User) - Inclure le timestamp
expiresAtpour la session
5. Types d'erreurs
export interface AppError {
message: string;
code?: string;
statusCode?: number;
field?: string;
}
export interface FormErrors {
[key: string]: string | undefined;
}
Modèle :
- Utiliser
interfacepour les objets d'erreur - Marquer les champs facultatifs avec
? - Utiliser la signature d'index
[key: string]pour les types d'objets dynamiques (FormErrors)
6. Types d'interface utilisateur
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;
}
Modèle :
- Utiliser
typepour les types union (littéraux de chaîne) - Utiliser
interfacepour les types objet - Inclure
idpour l'identification unique - Marquer les champs facultatifs avec
?
7. Types d'exportation/importation
export type ExportFormat = "csv" | "json";
export interface ImportResult {
imported: number;
errors: number;
errorDetails?: string[];
}
Modèle :
- Utiliser
typepour les types union (littéraux de chaîne) - Utiliser
interfacepour les objets de résultat - Inclure des compteurs pour le suivi des succès/erreurs
- Inclure un tableau de détails d'erreurs facultatif
Conventions de nommage des types
Interfaces
- PascalCase :
User,Task,ApiResponse - Noms descriptifs :
TaskFormData,UserSignupData
Types (types union)
- PascalCase :
TaskStatus,TaskPriority,LoadingState - Noms descriptifs :
ToastType,ExportFormat
Types de propriétés (Props)
- NomDuComposant + Props :
TaskItemProps,ProtectedRouteProps - Exemple :
interface TaskItemProps { task: Task; }
Types de données de formulaire
- NomEntité + FormData :
TaskFormData,UserSignupData - Exemple :
interface TaskFormData { title: string; description?: string; }
Types de paramètres de requête
- NomEntité + QueryParams :
TaskQueryParams - Exemple :
interface TaskQueryParams { status?: "all" | "pending" | "completed"; }
Correspondance avec le schéma backend
Mappage des noms de champs
Backend (snake_case) → Frontend (camelCase pour les données de formulaire, snake_case pour les réponses API)
// Réponse API backend (correspond exactement au backend)
export interface Task {
id: number;
user_id: string; // snake_case du backend
title: string;
due_date?: string; // snake_case du backend
created_at: string; // snake_case du backend
updated_at: string; // snake_case du backend
}
// Données de formulaire frontend (camelCase pour une utilisation plus facile)
export interface TaskFormData {
title: string;
dueDate?: string; // camelCase pour le frontend
tags?: string[];
}
Modèle :
- Les types de réponse API correspondent exactement au backend (snake_case)
- Les types de données de formulaire utilisent camelCase pour une utilisation plus facile en frontend
- Convertir entre les formats lors de l'envoi/réception depuis l'API
Champs obligatoires vs facultatifs
// Réponse API backend (tous les champs du backend)
export interface Task {
id: number; // Obligatoire (provenant du backend)
user_id: string; // Obligatoire (provenant du backend)
title: string; // Obligatoire (provenant du backend)
description?: string; // Facultatif (provenant du backend)
completed: boolean; // Obligatoire (provenant du backend)
priority: TaskPriority; // Obligatoire (provenant du backend)
due_date?: string; // Facultatif (provenant du backend)
tags: string[]; // Obligatoire (provenant du backend, peut être un tableau vide)
created_at: string; // Obligatoire (provenant du backend)
updated_at: string; // Obligatoire (provenant du backend)
}
// Données de formulaire frontend (uniquement les champs que l'utilisateur peut modifier)
export interface TaskFormData {
title: string; // Obligatoire (l'utilisateur doit fournir)
description?: string; // Facultatif
priority?: TaskPriority; // Facultatif (a une valeur par défaut)
due_date?: string; // Facultatif
tags?: string[]; // Facultatif (peut être un tableau vide)
}
Modèle :
- Les types de réponse API incluent tous les champs du backend
- Les types de données de formulaire n'incluent que les champs que l'utilisateur peut modifier
- Marquer les champs facultatifs avec
? - Les champs obligatoires n'ont pas de
?
Modèles de structure de types
1. Utiliser interface pour les objets
export interface User {
id: string;
email: string;
}
Quand utiliser : Types objet avec propriétés
2. Utiliser type pour les unions, intersections ou alias
export type TaskStatus = "pending" | "completed";
export type TaskPriority = "low" | "medium" | "high";
Quand utiliser : Types union, intersections ou alias de types
3. Utiliser des types génériques pour les structures réutilisables
export interface ApiResponse<T = unknown> {
data?: T;
success: boolean;
}
Quand utiliser : Structures réutilisables fonctionnant avec différents types
4. Marquer les propriétés facultatives avec ?
export interface Task {
title: string; // Obligatoire
description?: string; // Facultatif
}
Quand utiliser : Champs qui peuvent ne pas exister
Exemple complet : Ajout de nouveaux types
Étape 1 : Définir le type d'entité (correspond au backend)
export interface Category {
id: number;
user_id: string;
name: string;
color?: string;
created_at: string;
updated_at: string;
}
Étape 2 : Définir le type de données de formulaire (pour la saisie utilisateur)
export interface CategoryFormData {
name: string;
color?: string;
}
Étape 3 : Définir le type de paramètres de requête (pour les requêtes API)
export interface CategoryQueryParams {
search?: string;
page?: number;
limit?: number;
}
Étape 4 : Utiliser dans le client API
async getCategories(
userId: string,
queryParams?: CategoryQueryParams
): Promise<ApiResponse<PaginatedResponse<Category>>> {
// Implémentation
}
Exigences de la Constitution
- FR-030 : Interfaces TypeScript typées pour tous les appels API ✅
- FR-037 : Mode strict TypeScript ✅
Références
- Spécification :
specs/002-frontend-todo-app/spec.md- Définitions d'entités - Plan :
specs/002-frontend-todo-app/plan.md- Contrats API avec types - Fichier de types :
frontend/types/index.ts- Définitions de types complètes
Résumé des modèles courants
- ✅ Utiliser
interfacepour les types objet - ✅ Utiliser
typepour les types union (littéraux de chaîne) - ✅ Utiliser des types génériques
<T>pour les structures réutilisables - ✅ Marquer les champs facultatifs avec
? - ✅ Faire correspondre les noms de champs du backend (snake_case pour les réponses API)
- ✅ Utiliser camelCase pour les types de données de formulaire
- ✅ Créer des types séparés pour les données de formulaire et les paramètres de requête
- ✅ Utiliser des noms descriptifs (EntityFormData, EntityQueryParams)
- ✅ Inclure tous les champs obligatoires du backend
- ✅ Fournir des paramètres de type par défaut pour les génériques (
<T = unknown>)