Signatures d'assertion TypeScript : Validation de type à l'exécution pour un code robuste

TypeScript offre une excellente vérification statique des types pendant le développement, interceptant les erreurs potentielles avant l'exécution. Cependant, il est parfois nécessaire de garantir la sécurité des types à l'exécution. C'est là que les signatures d'assertion entrent en jeu. Elles vous permettent de définir des fonctions qui non seulement vérifient le type d'une valeur, mais informent également TypeScript que le type de cette valeur a été affiné en fonction du résultat de la vérification.

Que sont les signatures d'assertion ?

Une signature d'assertion est un type spécial de signature de fonction en TypeScript qui utilise le mot-clé asserts. Elle indique à TypeScript que si la fonction se termine sans lever d'erreur, alors une condition spécifique sur le type d'un argument est garantie d'être vraie. Cela vous permet d'affiner les types d'une manière que le compilateur comprend, même lorsqu'il ne peut pas inférer automatiquement le type en se basant sur le code.

La syntaxe de base est :

            function assertsCondition(argument: Type): asserts argument is NarrowedType {
  // ... implémentation qui vérifie la condition et lève une erreur si elle est fausse ...
}

            

              
                Copy
              
            
          

• assertsCondition : Le nom de votre fonction.
• argument: Type : L'argument dont vous voulez vérifier le type.
• asserts argument is NarrowedType : C'est la signature d'assertion. Elle indique à TypeScript que si assertsCondition(argument) se termine sans lever d'erreur, alors TypeScript peut traiter argument comme ayant le type NarrowedType.

Pourquoi utiliser les signatures d'assertion ?

Les signatures d'assertion offrent plusieurs avantages :

• Validation de type à l'exécution : Elles vous permettent de valider le type d'une valeur à l'exécution, prévenant ainsi les erreurs inattendues qui pourraient provenir de données incorrectes.
• Amélioration de la sécurité du code : En appliquant des contraintes de type à l'exécution, vous pouvez réduire le risque de bogues et améliorer la fiabilité globale de votre code.
• Affinement de type (Type Narrowing) : Les signatures d'assertion permettent à TypeScript d'affiner le type d'une variable en fonction du résultat d'une vérification à l'exécution, permettant une vérification de type plus précise dans le code qui suit.
• Lisibilité du code améliorée : Elles rendent votre code plus explicite quant aux types attendus, ce qui le rend plus facile à comprendre et à maintenir.

Exemples pratiques

Exemple 1 : Vérifier si une valeur est une chaîne de caractères

Créons une fonction qui affirme qu'une valeur est une chaîne de caractères. Si ce n'est pas le cas, elle lève une erreur.

            function assertIsString(value: any): asserts value is string {
  if (typeof value !== 'string') {
    throw new Error(`Expected a string, but received ${typeof value}`);
  }
}

function processString(input: any) {
  assertIsString(input);
  // TypeScript sait maintenant que 'input' est de type string
  console.log(input.toUpperCase());
}

processString("hello"); // Fonctionne sans problème
// processString(123); // Lève une erreur à l'exécution

            

              
                Copy
              
            
          

Dans cet exemple, assertIsString vérifie si la valeur d'entrée est une chaîne de caractères. Si ce n'est pas le cas, elle lève une erreur. Si la fonction se termine sans lever d'erreur, TypeScript sait que input est une chaîne de caractères, vous permettant d'appeler en toute sécurité des méthodes de chaîne comme toUpperCase().

Exemple 2 : Vérifier une structure d'objet spécifique

Supposons que vous travaillez avec des données récupérées d'une API et que vous voulez vous assurer qu'elles respectent une structure d'objet spécifique avant de les traiter. Imaginons que vous attendiez un objet avec les propriétés name (string) et age (number).

            interface Person {
  name: string;
  age: number;
}

function assertIsPerson(value: any): asserts value is Person {
  if (typeof value !== 'object' || value === null) {
    throw new Error(`Expected an object, but received ${typeof value}`);
  }

  if (!('name' in value) || typeof value.name !== 'string') {
    throw new Error(`Expected a string 'name' property`);
  }

  if (!('age' in value) || typeof value.age !== 'number') {
    throw new Error(`Expected a number 'age' property`);
  }
}

function processPerson(data: any) {
  assertIsPerson(data);
  // TypeScript sait maintenant que 'data' est de type Person
  console.log(`Name: ${data.name}, Age: ${data.age}`);
}

processPerson({ name: "Alice", age: 30 }); // Fonctionne sans problème
// processPerson({ name: "Bob", age: "30" }); // Lève une erreur à l'exécution
// processPerson({ name: "Charlie" }); // Lève une erreur à l'exécution

            

              
                Copy
              
            
          

Ici, assertIsPerson vérifie si la valeur d'entrée est un objet avec les propriétés et les types requis. Si une vérification échoue, elle lève une erreur. Sinon, TypeScript traite data comme un objet de type Person.

Exemple 3 : Vérifier une valeur d'énumération spécifique

Considérons une énumération représentant différents statuts de commande.

            enum OrderStatus {
  PENDING = "PENDING",
  PROCESSING = "PROCESSING",
  SHIPPED = "SHIPPED",
  DELIVERED = "DELIVERED",
}

function assertIsOrderStatus(value: any): asserts value is OrderStatus {
  if (!Object.values(OrderStatus).includes(value)) {
    throw new Error(`Expected OrderStatus, but received ${value}`);
  }
}

function processOrder(status: any) {
  assertIsOrderStatus(status);
  // TypeScript sait maintenant que 'status' est de type OrderStatus
  console.log(`Order status: ${status}`);
}

processOrder(OrderStatus.SHIPPED); // Fonctionne sans problème
// processOrder("CANCELLED"); // Lève une erreur à l'exécution

            

              
                Copy
              
            
          

Dans cet exemple, assertIsOrderStatus s'assure que la valeur d'entrée est une valeur valide de l'énumération OrderStatus. Si ce n'est pas le cas, elle lève une erreur. Cela aide à empêcher le traitement de statuts de commande non valides.

Exemple 4 : Utiliser des prédicats de type avec des fonctions d'assertion

Il est possible de combiner les prédicats de type et les fonctions d'assertion pour une plus grande flexibilité.

            function isString(value: any): value is string {
    return typeof value === 'string';
}

function assertString(value: any): asserts value is string {
    if (!isString(value)) {
        throw new Error(`Expected a string, but received ${typeof value}`);
    }
}

function processValue(input: any) {
    assertString(input);
    console.log(input.toUpperCase());
}

processValue("TypeScript"); // Fonctionne
// processValue(123); // Lève une erreur

            

              
                Copy
              
            
          

Meilleures pratiques

• Gardez les assertions concises : Concentrez-vous sur la validation des propriétés ou conditions essentielles au bon fonctionnement de votre code. Évitez les assertions trop complexes qui pourraient ralentir votre application.
• Fournissez des messages d'erreur clairs : Incluez des messages d'erreur informatifs qui aident les développeurs à identifier rapidement la cause de l'erreur et comment la corriger. Utilisez un langage spécifique qui guide l'utilisateur. Par exemple, au lieu de dire "Données invalides", dites "Attendu un objet avec les propriétés 'name' et 'age'".
• Utilisez des prédicats de type pour les vérifications complexes : Si votre logique de validation est complexe, envisagez d'utiliser des prédicats de type pour encapsuler la logique de vérification de type et améliorer la lisibilité du code.
• Considérez les implications sur les performances : La validation de type à l'exécution ajoute une surcharge à votre application. Utilisez les signatures d'assertion judicieusement et uniquement lorsque cela est nécessaire. La vérification statique des types doit être privilégiée lorsque c'est possible.
• Gérez les erreurs avec élégance : Assurez-vous que votre application gère correctly les erreurs levées par les fonctions d'assertion, en évitant les plantages et en offrant une bonne expérience utilisateur. Pensez à encapsuler le code potentiellement défaillant dans des blocs try-catch.
• Documentez vos assertions : Documentez clairement le but et le comportement de vos fonctions d'assertion, en expliquant les conditions qu'elles vérifient et les types attendus. Cela aidera les autres développeurs à comprendre et à utiliser correctement votre code.

Cas d'utilisation dans différents secteurs

Les signatures d'assertion peuvent être bénéfiques dans divers secteurs :

• E-commerce : Valider les entrées utilisateur lors du paiement pour s'assurer que les adresses de livraison, les informations de paiement et les détails de la commande sont corrects.
• Finance : Vérifier les données financières provenant de sources externes, telles que les cours des actions ou les taux de change, avant de les utiliser dans des calculs ou des rapports.
• Santé : S'assurer que les données des patients sont conformes à des formats et des normes spécifiques, comme les dossiers médicaux ou les résultats de laboratoire.
• Industrie manufacturière : Valider les données provenant de capteurs et de machines pour s'assurer que les processus de production se déroulent sans heurts et de manière efficace.
• Logistique : Vérifier que les données d'expédition, telles que les numéros de suivi et les adresses de livraison, sont exactes et complètes.

Alternatives aux signatures d'assertion

Bien que les signatures d'assertion soient un outil puissant, il existe également d'autres approches pour la validation de type à l'exécution en TypeScript :

• Gardes de type (Type Guards) : Les gardes de type sont des fonctions qui retournent une valeur booléenne indiquant si une valeur est d'un type spécifique. Elles peuvent être utilisées pour affiner le type d'une variable au sein d'un bloc conditionnel. Cependant, contrairement aux signatures d'assertion, elles ne lèvent pas d'erreurs lorsque la vérification de type échoue.
• Bibliothèques de vérification de type à l'exécution : Des bibliothèques comme io-ts, zod, et yup offrent des capacités complètes de vérification de type à l'exécution, y compris la validation de schémas et la transformation de données. Ces bibliothèques peuvent être particulièrement utiles lorsque l'on traite des structures de données complexes ou des API externes.

Conclusion

Les signatures d'assertion de TypeScript offrent un mécanisme puissant pour imposer la validation de type à l'exécution, améliorant la fiabilité du code et prévenant les erreurs inattendues. En définissant des fonctions qui affirment le type d'une valeur, vous pouvez améliorer la sécurité des types, affiner les types et rendre votre code plus explicite et maintenable. Bien qu'il existe des alternatives, les signatures d'assertion offrent un moyen léger et efficace d'ajouter des vérifications de type à l'exécution à vos projets TypeScript. En suivant les meilleures pratiques et en considérant attentivement les implications sur les performances, vous pouvez tirer parti des signatures d'assertion pour construire des applications plus robustes et fiables.

N'oubliez pas que les signatures d'assertion sont plus efficaces lorsqu'elles sont utilisées conjointement avec les fonctionnalités de vérification statique des types de TypeScript. Elles doivent être utilisées pour compléter, et non remplacer, la vérification statique des types. En combinant la validation de type statique et à l'exécution, vous pouvez atteindre un haut niveau de sécurité du code et prévenir de nombreuses erreurs courantes.