Maîtrise Architecturale de TypeScript pour les Systèmes d'Information Critiques

Ce cours transforme votre approche de TypeScript d'un simple vérificateur de syntaxe vers un outil d'architecture logicielle robuste. Vous apprendrez à structurer des types complexes pour sécuriser les flux de données administratifs et garantir la maintenabilité des systèmes de digitalisation. À la fin de ce parcours, vous serez capable de concevoir des bases de code résilientes aux évolutions métier sans compromettre la sécurité des types. Nous allons dépasser la syntaxe de base pour toucher aux mécanismes internes du compilateur et aux patterns d'ingénierie logicielle appliqués aux données sensibles.

Sommaire

1. Types Avancés et Inférence Contextuelle
2. Utilitaires de Types pour la Gestion de Formulaires
3. Génériques Contraints et Architecture de Repository
4. Unions Discriminées pour les Machines à États
5. Types Mappés et Matrices de Permissions
6. Fichiers de Déclaration et Intégration Legacy
7. Validation Runtime versus Sécurité Compile-time
8. Optimisation des Performances de Compilation
9. Architecture Modulaire et Isolation des Types
10. Stratégie de Migration Progressive JavaScript vers TypeScript

1. Types Avancés et Inférence Contextuelle

Definition approfondie

L'inférence de types dans TypeScript ne se limite pas à deviner le type d'une variable simple. Au niveau intermédiaire, il s'agit de comprendre comment le compilateur déduit les types à partir des flux de contrôle, des retours de fonctions et des structures de données complexes sans annotation explicite. L'inférence contextuelle permet de réduire la verbosité du code tout en maintenant une sécurité stricte. Elle analyse l'utilisation d'une expression pour déterminer son type, ce qui est crucial lors de la manipulation de réponses API ou de transformations de données issues de bases de legacy. Comprendre ce mécanisme permet d'éviter les annotations redondantes qui alourdissent la maintenance tout en s'assurant que les erreurs de typage sont capturées dès l'écriture du code.

Explication avec analogie

Imaginez un guichet administratif intelligent. Lorsque vous présentez une carte d'identité, le guichetier n'a pas besoin de vous demander votre nationalité ou votre date de naissance ; il déduit ces informations à partir du document fourni. De la même manière, l'inférence contextuelle observe le "document" (la valeur ou la structure) que vous passez à une fonction et déduit les "informations" (les types) nécessaires pour traiter la demande. Si vous essayez de passer un passeport là où une carte d'identité est attendue, le système le détecte immédiatement sans que vous ayez à écrire une note explicative sur chaque champ du formulaire.

// Définition d'une structure de données citoyenne stricte
interface Citoyen {
  id: string;
  nom: string;
  statutResidence: 'permanent' | 'temporaire';
}
// Le compilateur infère le type de retour basé sur l'objet retourné
function creerProfilCitoyen(nom: string, id: string) {
  // Inférence automatique de l'objet littéral comme compatible avec Citoyen
  return {
    id: id, // Correspond au type string défini dans l'interface
    nom: nom, // Correspond au type string défini dans l'interface
    statutResidence: 'permanent' // Littéral de type union valide
  };
}
// Utilisation : le type de 'profil' est inféré comme Citoyen
const profil = creerProfilCitoyen("Dupont", "FR-12345");
// Erreur capturée : propriété manquante ou type incorrect
const profilInvalide = {
  id: 123, // Erreur : number attendu, string requis
  nom: "Durand"
  // statutResidence manquant provoquera une erreur si typé explicitement
};

Cas usage reel

Dans la digitalisation des services publics, les réponses des API backend sont souvent transformées avant d'être affichées. Utiliser l'inférence permet de s'assurer que les transformateurs de données respectent le contrat de type sans dupliquer les définitions. Par exemple, lors de la conversion d'un dossier papier numérisé en objet JSON, chaque étape de transformation doit préserver l'intégrité des données critiques comme les numéros de sécurité sociale ou les dates de validité.

Astuce : Utilisez l'option noImplicitAny dans votre tsconfig.json pour forcer le compilateur à lever une erreur lorsque l'inférence échoue et retombe sur any.

Attention : L'inférence peut parfois être trop large si les structures de retour ne sont pas contraintes. Assurez-vous que les fonctions retournent des objets cohérents pour éviter des inférences de types union indésirables.

2. Utilitaires de Types pour la Gestion de Formulaires

Definition approfondie

Les types utilitaires natifs de TypeScript (Partial, Pick, Omit, Required) sont des outils de transformation de types essentiels pour modéliser les états intermédiaires des données. Dans un système d'information, une entité complète n'est jamais remplie d'un coup. Un formulaire de demande d'allocation peut être sauvegardé en brouillon, partiellement rempli, puis complété. Partial<T> rend toutes les propriétés optionnelles, idéal pour les brouillons. Pick<T, K> extrait un sous-ensemble de propriétés, utile pour les vues sommaires. Omit<T, K> exclut des propriétés, pertinent pour masquer des données sensibles avant envoi au client. Maîtriser ces utilitaires évite de créer des interfaces redondantes pour chaque état d'une même entité métier.

Explication avec analogie

Considérez un dossier administratif physique. Le dossier complet contient toutes les pièces (identité, revenus, justificatifs). Cependant, lors d'une première visite au guichet, l'agent ne prend qu'une copie de la pièce d'identité (Pick). Si le dossier est en cours de constitution, il peut manquer des pièces (Partial). Enfin, lorsque le dossier est archivé, on retire les documents temporaires de travail (Omit). Les utilitaires de types sont comme les tampons administratifs qui modifient la validité du dossier selon l'étape de traitement sans avoir à créer un nouveau dossier physique pour chaque situation.

// Interface complète représentant le dossier administratif final
interface DossierAllocation {
  id: string;
  demandeurNom: string;
  revenusAnnuels: number;
  piecesJustificatives: string[];
  dateSoumission: Date;
}
// Type pour un brouillon : tous les champs sont optionnels
type BrouillonDossier = Partial;
// Type pour l'affichage public : on exclut les revenus sensibles
type DossierPublic = Omit;
// Fonction acceptant un brouillon pour mise à jour progressive
function sauvegarderBrouillon(donnees: BrouillonDossier): void {
  // Logique de persistance partielle
  console.log("Brouillon sauvegardé", donnees);
}
// Utilisation correcte : seulement quelques champs fournis
sauvegarderBrouillon({ demandeurNom: "Martin" });
// Utilisation correcte : exclusion automatique des champs sensibles
const vuePublique: DossierPublic = {
  id: "1",
  demandeurNom: "Martin",
  revenusAnnuels: 0, // Erreur : propriété exclue par Omit
  piecesJustificatives: [],
  dateSoumission: new Date()
};

Cas usage reel

Lors de la conception d'un portail citoyen, les données ne sont pas toujours complètes. Un utilisateur peut commencer une demande, se déconnecter, et revenir plus tard. Utiliser Partial permet de typer le state du formulaire frontend sans créer une interface DossierAllocationDraft distincte qui divergerait de la source de vérité. De plus, Omit est crucial pour la conformité RGPD, en s'assurant typiquement que les données sensibles ne transitent jamais vers le navigateur client dans les objets de réponse typés.

Astuce : Combinez les utilitaires, par exemple Partial<Pick<Dossier, 'nom' | 'email'>>, pour créer des types très spécifiques aux besoins d'un composant UI précis.

Attention : Omit peut parfois produire des résultats inattendus si les clés exclues n'existent pas dans le type original. Vérifiez toujours les clés utilisées dans Exclude ou Omit.

3. Génériques Contraints et Architecture de Repository

Definition approfondie

Les génériques permettent de créer des composants réutilisables qui fonctionnent avec une variété de types tout en conservant la sécurité du typage. Les génériques contraints (extends) ajoutent une couche de validation en s'assurant que le type passé respecte une structure minimale. Dans l'architecture de repository pour l'accès aux données, cela permet de créer un gestionnaire de base de données unique capable de gérer différentes entités (Citoyens, Dossiers, Paiements) tout en garantissant que chaque entité possède un identifiant unique et des métadonnées de base. Cela réduit la duplication de code pour les opérations CRUD tout en empêchant l'utilisation de types incompatibles avec la couche de persistance.

Explication avec analogie

Imaginez un système de classement archiviste universel. Ce système peut accepter n'importe quel type de dossier (médical, fiscal, urbain), mais il impose une règle : chaque dossier doit avoir une étiquette extérieure avec un numéro de référence et une date de création. Le générique contraint est cette règle d'archivage. Vous pouvez mettre n'importe quel contenu à l'intérieur du dossier, mais si l'étiquette extérieure ne respecte pas le format standard, le système de classement refuse de l'accepter. Cela garantit que quel que soit le contenu, vous pouvez toujours retrouver le dossier par son numéro.

// Contrainte de base : toute entité doit avoir un ID et une date
interface EntiteBase {
  id: string;
  createdAt: Date;
}
// Repository générique contraint pour gérer n'importe quelle entité
class Repository {
  private storage: Map = new Map();
  // Méthode sauvegarde typée selon l'entité passée
  save(entity: T): void {
    // Vérification implicite que entity.id existe grâce à extends
    this.storage.set(entity.id, entity);
  }
  // Méthode de récupération retournant le type exact T
  findById(id: string): T | undefined {
    return this.storage.get(id);
  }
}
// Définition d'une entité spécifique respectant la contrainte
interface DossierUrbanisme extends EntiteBase {
  adresse: string;
  permisValide: boolean;
}
// Instanciation du repository pour les dossiers d'urbanisme
const dossierRepo = new Repository();
// Utilisation : sauvegarde typée
dossierRepo.save({
  id: "URB-001",
  createdAt: new Date(),
  adresse: "10 Rue de la Paix",
  permisValide: true
});

Cas usage reel

Dans la digitalisation des services, vous avez souvent plusieurs tables de base de données avec des structures similaires (id, created_at, updated_at). Créer un repository générique permet d'unifier la logique d'accès aux données. Si demain une nouvelle entité "DemandeSubvention" est créée, il suffit de définir son interface étendant EntiteBase pour qu'elle soit immédiatement compatible avec le repository existant, sans réécrire la logique de stockage ou de récupération.

Astuce : Utilisez des contraintes multiples si nécessaire, par exemple T extends EntiteBase & Serializable, pour imposer plusieurs contrats simultanément à vos types génériques.

Attention : Les contraintes trop complexes peuvent rendre les messages d'erreur du compilateur illisibles. Gardez les interfaces de contrainte simples et focalisées sur les propriétés indispensables.

4. Unions Discriminées pour les Machines à États

Definition approfondie

Les unions discriminées (ou tagged unions) permettent de modéliser des états mutuellement exclusifs de manière sûre. En combinant un champ littéral (le discriminant) avec une union de types, TypeScript peut réduire le type dans les blocs conditionnels. C'est l'outil idéal pour gérer les cycles de vie des dossiers administratifs (Brouillon, EnInstruction, Validé, Rejeté). Chaque état peut avoir des propriétés spécifiques qui n'existent pas dans les autres états. Le compilateur assure qu'on ne tente pas d'accéder à une propriété spécifique à un état valide tant que le discriminant n'a pas été vérifié, éliminant ainsi les erreurs runtime liées à des propriétés undefined.

Explication avec analogie

Pensez à un feu tricolore. Il ne peut être que Rouge, Orange ou Vert. Chaque couleur autorise des actions spécifiques : au Rouge, vous devez vous arrêter ; au Vert, vous pouvez passer. Vous ne pouvez pas avoir un feu qui est à la fois Rouge et Vert. De plus, certaines informations ne sont pertinentes que pour une couleur (ex: un compte à rebours pour le Rouge). L'union discriminée est le mécanisme qui vous oblige à vérifier la couleur avant d'entreprendre une action, vous empêchant d'essayer de passer au travers d'un feu Rouge parce que le système sait que dans cet état, l'action "passer" n'existe pas.

// États possibles d'une demande de passeport
type EtatDemande = 
  | { statut: 'BROUILLON'; donnees: Partial }
  | { statut: 'SOUMIS'; dateSoumission: Date; reference: string }
  | { statut: 'VALIDE'; dateValidation: Date; numeroPasseport: string }
  | { statut: 'REJETE'; motif: string; dateRejet: Date };
interface Demande {
  nom: string;
  prenom: string;
}
// Fonction de traitement sécurisée par le discriminant 'statut'
function traiterDemande(demande: EtatDemande): void {
  // TypeScript réduit le type selon la valeur de 'statut'
  if (demande.statut === 'VALIDE') {
    // Accès sûr à numeroPasseport uniquement dans ce bloc
    console.log(`Passeport émis : ${demande.numeroPasseport}`);
  } else if (demande.statut === 'REJETE') {
    // Accès sûr à motif uniquement dans ce bloc
    console.warn(`Demande rejetée : ${demande.motif}`);
  } else {
    // Gestion des autres cas (BROUILLON, SOUMIS)
    console.log("En attente de validation finale");
  }
}

Cas usage reel

Les workflows administratifs sont par nature étatiques. Un dossier ne peut pas être "Validé" et "Rejeté" en même temps. Utiliser des unions discriminées permet de coder ces règles métier directement dans le type. Si un développeur essaie d'accéder au numeroPasseport alors que le statut est BROUILLON, TypeScript levera une erreur immédiatement. Cela sécurise les logiques métier critiques contre les régressions lors de refactoring.

Astuce : Utilisez le switch sur le champ discriminant pour bénéficier de l'exhaustivité. TypeScript vous avertira si un cas de l'union n'est pas traité dans le switch.

Attention : Assurez-vous que le champ discriminant est un littéral de type ('STATUT') et non une chaîne générique string, sinon la réduction de type ne fonctionnera pas.

5. Types Mappés et Matrices de Permissions

Definition approfondie

Les types mappés permettent de créer de nouveaux types en transformant les propriétés d'un type existant via une boucle au niveau du type. C'est une fonctionnalité puissante pour générer dynamiquement des structures basées sur des clés d'objet. Dans le contexte de la gestion des droits d'accès (RBAC), on peut générer une matrice de permissions où chaque rôle possède un état booléen pour chaque action possible sur une ressource. Cela évite de définir manuellement des interfaces énormes pour chaque combinaison de permissions et permet d'ajuster la granularité des droits centralisée en un seul endroit.

Explication avec analogie

Imaginez un tableau de contrôle centralisé dans un bâtiment public. Chaque ligne représente un employé, chaque colonne représente une porte (Archives, Serveurs, Accueil). Plutôt que de construire un tableau unique pour chaque employé, vous avez un modèle de tableau vide. Vous appliquez ce modèle à chaque employé pour générer leur badge d'accès spécifique. Les types mappés font exactement cela : ils prennent la liste des portes (clés) et génèrent la structure de badge (propriétés) pour chaque employé (type), assurant que personne n'a une clé pour une porte qui n'existe pas dans le modèle.

// Liste des actions possibles sur un dossier
type ActionDossier = 'lire' | 'ecrire' | 'supprimer' | 'valider';
// Type mappé : crée un objet avec une clé par action, valeur booléenne
type PermissionsDossier = {
  [K in ActionDossier]: boolean;
};
// Type mappé avancé : rend certaines actions optionnelles selon le contexte
type PermissionsPartielles = {
  [K in ActionDossier]?: boolean;
};
// Implémentation concrète pour un rôle Administrateur
const adminPerms: PermissionsDossier = {
  lire: true,
  ecrire: true,
  supprimer: true,
  valider: true
};
// Fonction de vérification typée
function verifierAccess(action: ActionDossier, perms: PermissionsDossier): boolean {
  // Accès sûr à la propriété dynamique grâce au type indexé
  return perms[action];
}

Cas usage reel

Dans les systèmes d'information publics, les rôles sont complexes (Agent, Responsable, Admin, Auditeur). Au lieu de coder en dur les vérifications if (role === 'admin'), on utilise une matrice de permissions générée par types mappés. Cela permet de modifier les droits d'accès simplement en changeant la configuration des données, tandis que le code reste statique et typé. Si une nouvelle action 'archiver' est ajoutée au type ActionDossier, TypeScript forcera la mise à jour de toutes les matrices de permissions existantes.

Astuce : Combinez les types mappés avec Readonly pour créer des configurations de permissions immuables : { readonly [K in Action]: boolean }.

Attention : Les types mappés complexes peuvent augmenter significativement le temps de compilation. Évitez de les imbriquer profondément dans des génériques récursifs.

6. Fichiers de Déclaration et Intégration Legacy

Definition approfondie

Les fichiers de déclaration (.d.ts) permettent d'intégrer du code JavaScript existant ou des bibliothèques externes non typées dans un projet TypeScript sécurisé. Ils servent de contrat de type pour du code dont vous ne possédez pas les sources ou qui n'a pas été écrit en TypeScript. Dans la modernisation de systèmes legacy, il est fréquent de devoir interagir avec d'anciennes bibliothèques de traitement de données ou des API internes. Créer des déclarations précises permet de bénéficier de l'autocomplétion et de la vérification de type sans réécrire immédiatement l'intégralité du code legacy, facilitant une migration progressive et sûre.

Explication avec analogie

Considérez l'importation de documents papier anciens dans un nouveau système numérique. Vous ne pouvez pas modifier le texte original des archives papier, mais vous pouvez créer un index numérique qui décrit ce que contient chaque document. Le fichier .d.ts est cet index numérique. Il ne change pas le contenu du document original (le code JS), mais il permet au nouveau système (TypeScript) de savoir comment interagir avec lui sans ouvrir chaque dossier physiquement. Si l'index est erroné, le système vous avertit avant même d'essayer de lire le document.

// Fichier : legacy-api.d.ts
// Déclaration d'une fonction existante en JavaScript pur
declare module './legacy-utils' {
  // Fonction non typée à l'origine, maintenant sécurisée
  export function calculerIndiceFiscal(data: any): number;
  // Objet global ajouté par un script legacy
  export const VERSION_SYSTEME: string;
  // Interface pour un objet complexe retourné
  export interface ReponseLegacy {
    code: number;
    message: string;
    // Propriété optionnelle souvent absente
    data?: unknown;
  }
}
// Utilisation dans le code TypeScript moderne
import { calculerIndiceFiscal } from './legacy-utils';
// Appel typé malgré l'implémentation JS sous-jacente
const indice = calculerIndiceFiscal({ revenu: 50000 });

Cas usage reel

Lors de la digitalisation, il est courant de devoir wrapper des librairies de génération de PDF ou de signature électronique écrites il y a 10 ans en JS vanilla. Au lieu de les migrer entièrement, on crée un fichier .d.ts qui décrit leur API. Cela permet aux nouveaux développeurs d'utiliser ces fonctions avec l'autocomplétion IDE. Si la librairie legacy change, on met à jour le fichier de déclaration, et TypeScript signalera toutes les incompatibilités dans le code moderne qui l'utilise.

Astuce : Utilisez l'outil dts-gen pour générer automatiquement une ébauche de fichier de déclaration à partir d'une librairie JS, puis affinez-le manuellement.

Attention : Évitez d'utiliser any dans les fichiers de déclaration. Si le type est inconnu, utilisez unknown pour forcer une vérification de type au point d'utilisation.

7. Validation Runtime versus Sécurité Compile-time

Definition approfondie

TypeScript assure la sécurité des types uniquement à la compilation, pas à l'exécution. Les données entrantes (API, formulaires, bases de données) ne sont pas fiables et doivent être validées à runtime. Il est crucial de distinguer le typage statique (confiance dans le code) de la validation dynamique (confiance dans les données). Utiliser des bibliothèques de schéma comme Zod ou io-ts permet de définir un schéma de validation qui génère automatiquement le type TypeScript associé. Cela garantit que si la validation runtime passe, les données sont conformes au type TypeScript, éliminant la duplication de logique de validation et de définition de types.

Explication avec analogie

Le typage TypeScript est comme un plan d'architecte : il garantit que le bâtiment est conçu correctement sur le papier. La validation runtime est comme l'inspection des matériaux sur le chantier : elle garantit que le béton utilisé correspond bien aux spécifications du plan. Vous pouvez avoir un plan parfait (code typé), mais si le béton est faux (données API incorrectes), le bâtiment s'effondre. Les deux sont nécessaires : le plan pour guider la construction, l'inspection pour assurer la solidité réelle face aux éléments extérieurs.

import { z } from 'zod';
// Schéma de validation runtime qui infère le type TS
const SchemaCitoyen = z.object({
  id: z.string().uuid(),
  nom: z.string().min(2),
  email: z.string().email(),
  role: z.enum(['ADMIN', 'USER'])
});
// Inférence du type TypeScript depuis le schéma Zod
type Citoyen = z.infer;
// Fonction de traitement avec garantie de type après validation
function traiterDonneesBrutes(data: unknown): Citoyen {
  // Parse lance une erreur si les données ne correspondent pas
  const result = SchemaCitoyen.parse(data);
  // 'result' est typé comme Citoyen ici garantie par Zod
  return result;
}
// Utilisation avec gestion d'erreur
try {
  const citoyen = traiterDonneesBrutes({ id: "invalid", nom: "A", email: "bad" });
} catch (error) {
  // Gestion centralisée des erreurs de validation
  console.error("Données entrantes non conformes");
}

Cas usage reel

Les API externes ou les webhooks reçus dans un système d'information public ne respectent pas toujours le contrat attendu. Un champ peut être manquant ou d'un type différent. En liant la validation runtime au typage statique, on s'assure que dès que les données passent la frontière de confiance (API vers Core), elles sont sûres. Cela protège le cœur du système des injections de types ou des erreurs de format qui pourraient causer des plantages ou des corruptions de données.

Astuce : Placez les schémas de validation près des points d'entrée (Controllers, API Routes) et utilisez les types inférés pour le reste de l'application.

Attention : La validation runtime a un coût performance. Ne validez pas les données internes qui ont déjà été validées à l'entrée du système, sauf en cas de doute sur la mutabilité.

8. Optimisation des Performances de Compilation

Definition approfondie

À mesure que la base de code grandit, le temps de compilation TypeScript peut devenir un goulot d'étranglement. L'optimisation passe par la configuration du tsconfig.json, l'utilisation de la compilation incrémentale et la structuration des types pour éviter les calculs complexes inutiles. Les types conditionnels lourds, les mappings profonds et les dépendances circulaires augmentent exponentiellement le temps d'analyse. Pour les grands systèmes d'information, il est vital de configurer des références de projet (Project References) pour compiler uniquement les modules modifiés, assurant une expérience développeur fluide même sur des milliers de fichiers.

Explication avec analogie

Imaginez une grande administration où chaque modification de règle nécessite de relire tous les archives de la ville. C'est inefficace. L'optimisation de compilation consiste à découper la ville en quartiers indépendants. Si une règle change dans le quartier Nord, on ne vérifie que les archives du Nord. La compilation incrémentale est comme un archiviste qui note quels dossiers ont changé depuis la dernière visite et ne met à jour que ceux-là, laissant les autres intactes pour gagner un temps précieux.

// Configuration tsconfig.json optimisée
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "incremental": true, // Active la cache de compilation
    "tsBuildInfoFile": "./node_modules/.cache/tsbuildinfo.json",
    "skipLibCheck": true, // Ignore la vérification des fichiers .d.ts externes
    "isolatedModules": true // Garantit que chaque fichier peut être transpilé seul
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Cas usage reel

Dans un projet de digitalisation à grande échelle avec des centaines de modules, le temps de build peut passer de 10 secondes à 5 minutes. En activant incremental et en utilisant project references pour séparer le shared kernel, l'API et le Frontend, on réduit le temps de feedback à quelques secondes. Cela impacte directement la productivité des équipes de développement qui peuvent itérer plus rapidement sur les fonctionnalités critiques sans attendre le build complet.

Astuce : Utilisez l'option --explainFiles pour comprendre pourquoi TypeScript inclut certains fichiers dans la compilation et identifier les dépendances inutiles.

Attention : skipLibCheck peut masquer des erreurs de types dans les bibliothèques externes. Assurez-vous que vos dépendances majeures sont bien maintenues avant de l'activer.

9. Architecture Modulaire et Isolation des Types

Definition approfondie

Une architecture modulaire robuste sépare les définitions de types de leur implémentation logique. Les types doivent être exportés depuis des fichiers dédiés (ex: types.ts ou domain.ts) pour éviter les dépendances circulaires et faciliter la réutilisation. L'isolation des types permet de changer l'implémentation d'un service sans impacter les consommateurs qui ne dépendent que des interfaces. Dans les systèmes complexes, il est recommandé d'utiliser des "Barrel files" (index.ts) pour centraliser les exports publics, tout en gardant les types internes privés au module pour réduire la surface d'attaque de l'API publique.

Explication avec analogie

Considérez la construction d'un immeuble administratif. Les plans électriques et de plomberie (types) sont séparés des murs et de la décoration (implémentation). Si vous changez la couleur des murs, les plans électriques ne changent pas. Si vous changez le type de prise électrique, vous devez mettre à jour le plan, mais pas nécessairement refaire tout le mur. L'isolation des types assure que les équipes travaillant sur l'interface utilisateur n'ont pas besoin de connaître les détails de la base de données, tant que le "plan de connexion" (interface) reste stable.

// Fichier: domain/types.ts
// Exportation pure des types sans logique
export interface IUser {
  id: string;
  email: string;
}
// Fichier: domain/service.ts
// Implémentation dépendant seulement des types
import { IUser } from './types';
export class UserService {
  // Méthode publique utilisant l'interface
  public getUser(id: string): Promise {
    // Logique interne cachée
    return Promise.resolve({ id, email: "test@example.com" });
  }
}
// Fichier: index.ts (Barrel file)
// Exposition contrôlée de l'API publique du module
export { IUser } from './domain/types';
export { UserService } from './domain/service';
// Le type interne de la DB n'est pas exporté

Cas usage reel

Lors du développement de microservices ou de modules npm internes pour l'administration, la stabilité des types publics est cruciale. En isolant les types, on permet aux équipes de faire évoluer la logique métier (optimisation SQL, cache) sans forcer les équipes consommatrices à recompiler ou adapter leur code, tant que le contrat de type IUser reste inchangé. Cela favorise le découplage et la maintenabilité à long terme.

Astuce : Préférez exporter des interfaces plutôt que des types alias pour les objets publics, car les interfaces sont extensibles (declaration merging) par les consommateurs si nécessaire.

Attention : Les barrel files peuvent parfois causer des problèmes de chargement circulaire si mal structurés. Importez directement depuis le fichier source dans le code interne du module.

10. Stratégie de Migration Progressive JavaScript vers TypeScript

Definition approfondie

La migration d'une base de code JavaScript existante vers TypeScript ne doit pas être un "Big Bang". La stratégie progressive permet de convertir fichier par fichier tout en maintenant le système fonctionnel. L'option allowJs du compilateur permet de mélanger les deux langages. L'approche recommandée consiste à commencer par les fichiers de configuration et les types, puis les utilitaires purs, et enfin la logique métier complexe. L'utilisation de JSDoc dans les fichiers JS avant conversion permet d'introduire du typage progressif sans changer l'extension du fichier, préparant le terrain pour une conversion finale sans douleur.

Explication avec analogie

Rénover un bâtiment administratif en activité ne se fait pas en fermant tout l'immeuble d'un coup. On rénove étage par étage. Pendant les travaux, certains bureaux sont en béton brut (JS), d'autres sont finis (TS). Les escaliers (imports) doivent fonctionner entre les deux états. JSDoc est comme poser des étiquettes provisoires sur les bureaux en travaux pour indiquer leur fonction, avant de remplacer complètement les murs par la nouvelle structure TypeScript. Cela assure la continuité du service public pendant la transition technique.

// Fichier JS avec JSDoc pour typage progressif
// fichier: legacy-logic.js
/**
 * @param {string} id - L'identifiant du dossier
 * @param {number} montant - Le montant à valider
 * @returns {boolean} Résultat de la validation
 */
function validerBudget(id, montant) {
  // Logique existante préservée
  return montant > 0 && id.length > 5;
}
// Fichier TypeScript consommant le JS typé
// fichier: new-service.ts
import { validerBudget } from './legacy-logic';
// TypeScript comprend les types grâce à JSDoc
const estValide = validerBudget("DOSSIER-123", 5000); 
// estValide est inféré comme boolean

Cas usage reel

Pour un service public disposant de 5 ans de code JavaScript legacy, une réécriture totale est trop risquée et coûteuse. En activant checkJs, on peut commencer à vérifier les types dans les fichiers JS existants. On convertit d'abord les fichiers les moins dépendants. Cette méthode permet de livrer de nouvelles fonctionnalités en TypeScript tout en stabilisant l'ancien code progressivement, sans arrêt de production ni bug majeur dû à une migration brutale.

Astuce : Commencez la migration par les fichiers de configuration et les utilitaires purs (sans effets de bord) car ils sont les plus faciles à typer et apportent une valeur immédiate.

Attention : Ne bloquez pas le déploiement tant que la couverture de type n'est pas à 100%. Visez une amélioration continue plutôt qu'une perfection immédiate qui stopperait le développement.

Conclusion

Tu as maintenant maitrise :

• OK L'inférence de types contextuelle pour réduire la verbosité
• OK Les utilitaires de types pour gérer les états de formulaires
• OK Les génériques contraints pour une architecture de données robuste
• OK Les unions discriminées pour sécuriser les machines à États
• OK Les types mappés pour générer des matrices de permissions
• OK L'intégration de code legacy via les fichiers de déclaration
• OK La distinction entre validation runtime et sécurité compile-time
• OK L'optimisation des performances de compilation TypeScript
• OK L'architecture modulaire pour isoler les contrats de types
• OK La stratégie de migration progressive depuis JavaScript

Etape suivante recommandée : Implémenter une bibliothèque de schémas de validation (comme Zod) dans votre prochain module de service public pour lier directement la validation des données entrantes à vos interfaces TypeScript.