Presque toutes   nécessitent la sérialisation des données. Ce besoin survient dans des situations telles que : les applications Web  Transfert de données sur le réseau (par exemple requêtes HTTP, WebSockets)  Intégrer des données en HTML (pour l'hydratation, par exemple)  Stockage des données dans un stockage persistant (comme LocalStorage)  Partage de données entre processus (comme les Web Workers ou postMessage)  Dans de nombreux cas, la perte ou la corruption de données peut entraîner de graves conséquences. Il est donc essentiel de fournir un mécanisme de sérialisation pratique et sûr permettant de détecter autant d'erreurs que possible pendant la phase de développement. À ces fins, il est pratique d'utiliser   comme format de transfert de données et TypeScript pour la vérification du code statique pendant le développement. JSON  TypeScript sert de sur-ensemble de JavaScript, ce qui devrait permettre une utilisation transparente de fonctions telles que   et   , n'est-ce pas ? Il s'avère que, malgré tous ses avantages, TypeScript ne comprend pas naturellement ce qu'est JSON ni quels types de données sont sûrs pour la sérialisation et la désérialisation en JSON. JSON.stringify JSON.parse  Illustrons cela avec un exemple.  Le problème avec JSON dans TypeScript  Prenons, par exemple, une fonction qui enregistre certaines données dans LocalStorage. Comme LocalStorage ne peut pas stocker d'objets, nous utilisons ici la sérialisation JSON :   interface PostComment { authorId: string; text: string; updatedAt: Date; } function saveComment(comment: PostComment) { const serializedComment = JSON.stringify(comment); localStorage.setItem('draft', serializedComment); }  Nous aurons également besoin d'une fonction pour récupérer les données de LocalStorage.   function restoreComment(): PostComment | undefined { const text = localStorage.getItem('draft'); return text ? JSON.parse(text) : undefined; }  Quel est le problème avec ce code ? Le premier problème est que lors de la restauration du commentaire, nous obtiendrons un type   au lieu de   pour le champ   . string Date updatedAt  Cela se produit parce que JSON n'a que quatre types de données primitifs (   ,   ,   ,   ), ainsi que des tableaux et des objets. Il n'est pas possible de sauvegarder un objet   en JSON, ainsi que d'autres objets que l'on trouve en JavaScript : fonctions, Map, Set, etc. null string number boolean Date  Lorsque   rencontre une valeur qui ne peut pas être représentée au format JSON, une conversion de type se produit. Dans le cas d'un objet   , nous obtenons une chaîne car l'objet   implémente la méthode   , qui renvoie une chaîne au lieu d'un objet   . JSON.stringify Date Date toJson() Date   const date = new Date('August 19, 1975 23:15:30 UTC'); const jsonDate = date.toJSON(); console.log(jsonDate); // Expected output: "1975-08-19T23:15:30.000Z" const isEqual = date.toJSON() === JSON.stringify(date); console.log(isEqual); // Expected output: true  Le deuxième problème est que la fonction   renvoie le type   , dans lequel le champ date est de type   . Mais nous savons déjà qu'au lieu de   , nous recevrons un type   . TypeScript pourrait nous aider à trouver cette erreur, mais pourquoi pas ? saveComment PostComment Date Date string  Il s'avère que dans la bibliothèque standard de TypeScript, la fonction   est saisie comme   . En raison de l'utilisation de   , la vérification de type est essentiellement désactivée. Dans notre exemple, TypeScript nous a simplement cru sur parole que la fonction renverrait un   contenant un objet   . JSON.parse (text: string) => any any PostComment Date  Ce comportement TypeScript est peu pratique et dangereux. Notre application peut planter si nous essayons de traiter une chaîne comme un objet   . Par exemple, cela pourrait échouer si nous appelons   . Date comment.updatedAt.toLocaleDateString()  En effet, dans notre petit exemple, nous pourrions simplement remplacer l'objet   par un horodatage numérique, ce qui fonctionne bien pour la sérialisation JSON. Cependant, dans les applications réelles, les objets de données peuvent être volumineux, les types peuvent être définis à plusieurs emplacements et l'identification d'une telle erreur pendant le développement peut s'avérer une tâche difficile. Date  Et si nous pouvions améliorer la compréhension de TypeScript de JSON ?  Gérer la sérialisation  Pour commencer, voyons comment faire comprendre à TypeScript quels types de données peuvent être sérialisés en toute sécurité dans JSON. Supposons que nous souhaitions créer une fonction   , où TypeScript vérifiera le format des données d'entrée pour garantir qu'il est sérialisable en JSON. safeJsonStringify   function safeJsonStringify(data: JSONValue) { return JSON.stringify(data); }  Dans cette fonction, la partie la plus importante est le type   , qui représente toutes les valeurs possibles pouvant être représentées au format JSON. La mise en œuvre est assez simple : JSONValue   type JSONPrimitive = string | number | boolean | null | undefined; type JSONValue = JSONPrimitive | JSONValue[] | { [key: string]: JSONValue; };  Tout d’abord, nous définissons le type   , qui décrit tous les types de données JSON primitifs. Nous incluons également le type   basé sur le fait que lors de la sérialisation, les clés avec la valeur   seront omises. Lors de la désérialisation, ces clés n'apparaîtront tout simplement pas dans l'objet, ce qui revient dans la plupart des cas à la même chose. JSONPrimitive undefined undefined  Ensuite, nous décrivons le type   . Ce type utilise la capacité de TypeScript à décrire les types récursifs, qui sont des types qui font référence à eux-mêmes. Ici,   peut être un   , un tableau de   ou un objet où toutes les valeurs sont du type   . Par conséquent, une variable de ce type   peut contenir des tableaux et des objets avec une imbrication illimitée. La compatibilité des valeurs contenues dans celles-ci sera également vérifiée avec le format JSON. JSONValue JSONValue JSONPrimitive JSONValue JSONValue JSONValue  Nous pouvons maintenant tester notre fonction   à l'aide des exemples suivants : safeJsonStringify   // No errors safeJsonStringify({ updatedAt: Date.now() }); // Yields an error: // Argument of type '{ updatedAt: Date; }' is not assignable to parameter of type 'JSONValue'. // Types of property 'updatedAt' are incompatible. // Type 'Date' is not assignable to type 'JSONValue'. safeJsonStringify({ updatedAt: new Date(); });  Tout semble fonctionner correctement. La fonction nous permet de transmettre la date sous forme de nombre mais génère une erreur si nous passons l'objet   . Date  Mais considérons un exemple plus réaliste, dans lequel les données transmises à la fonction sont stockées dans une variable et ont un type décrit.   interface PostComment { authorId: string; text: string; updatedAt: number; }; const comment: PostComment = {...}; // Yields an error: // Argument of type 'PostComment' is not assignable to parameter of type 'JSONValue'. // Type 'PostComment' is not assignable to type '{ [key: string]: JSONValue; }'. // Index signature for type 'string' is missing in type 'PostComment'. safeJsonStringify(comment);  Maintenant, les choses deviennent un peu délicates. TypeScript ne nous permet pas d'attribuer une variable de type   à un paramètre de fonction de type   , car "La signature d'index pour le type 'string' est manquante dans le type 'PostComment'". PostComment JSONValue  Alors, qu’est-ce qu’une signature d’index et pourquoi manque-t-elle ? Rappelez-vous comment nous avons décrit les objets pouvant être sérialisés au format JSON ?   type JSONValue = { [key: string]: JSONValue; };  Dans ce cas,   est la signature d'index. Cela signifie "cet objet peut avoir n'importe quelle clé sous forme de chaînes dont les valeurs ont le type   ". Il s'avère donc que nous devons ajouter une signature d'index au type   , n'est-ce pas ? [key: string] JSONValue PostComment   interface PostComment { authorId: string; text: string; updatedAt: number; // Don't do this: [key: string]: JSONValue; };  Cela impliquerait que le commentaire pourrait contenir des champs arbitraires, ce qui n'est généralement pas le résultat souhaité lors de la définition de types de données dans une application.  La véritable solution au problème de la signature d'index vient des   , qui permettent une itération récursive sur les champs, même pour les types pour lesquels aucune signature d'index n'est définie. Combinée aux génériques, cette fonctionnalité permet de convertir n'importe quel type de données   en un autre type   , compatible avec le format JSON. Mapped Types T JSONCompatible<T>   type JSONCompatible<T> = unknown extends T ? never : { [P in keyof T]: T[P] extends JSONValue ? T[P] : T[P] extends NotAssignableToJson ? never : JSONCompatible<T[P]>; }; type NotAssignableToJson = | bigint | symbol | Function;  Le type   est un type mappé qui vérifie si un type   donné peut être sérialisé en toute sécurité dans JSON. Pour ce faire, il parcourt chaque propriété de type   et effectue les opérations suivantes : JSONCompatible<T> T T  Le   le type conditionnel vérifie si le type de la propriété est compatible avec le type   , garantissant qu'il peut être converti en toute sécurité en JSON. Lorsque c'est le cas, le type de propriété reste inchangé. T[P] extends JSONValue ? T[P] : ... JSONValue  Le   le type conditionnel vérifie si le type de la propriété n'est pas attribuable à JSON. Dans ce cas, le type de la propriété est converti en   , filtrant ainsi la propriété du type final. T[P] extends NotAssignableToJson ? never : ... never  Si aucune de ces conditions n’est remplie, le type est vérifié récursivement jusqu’à ce qu’une conclusion puisse être tirée. De cette façon, cela fonctionne même si le type n'a pas de signature d'index.  L'   check au début est utilisé pour empêcher le type   d'être converti en un type d'objet vide   , qui est essentiellement équivalent à   type. unknown extends T ? never :... unknown {} any  Un autre aspect intéressant est le type   . Il se compose de deux primitives TypeScript (bigint et symbol) et du type   , qui décrit toute fonction possible. Le type   est crucial pour filtrer toutes les valeurs qui ne sont pas attribuables à JSON. En effet, tout objet complexe en JavaScript est basé sur le type Object et possède au moins une fonction dans sa chaîne de prototypes (par exemple,   ). Le type   parcourt toutes ces fonctions, donc la vérification des fonctions est suffisante pour filtrer tout ce qui n'est pas sérialisable en JSON. NotAssignableToJson Function Function toString() JSONCompatible  Utilisons maintenant ce type dans la fonction de sérialisation :   function safeJsonStringify<T>(data: JSONCompatible<T>) { return JSON.stringify(data); }  Désormais, la fonction utilise un paramètre générique   et accepte l'argument   . Cela signifie qu'il prend un argument   de type   , qui doit être un type compatible JSON. Nous pouvons désormais utiliser la fonction avec des types de données sans signature d'index. T JSONCompatible<T> data T  La fonction utilise désormais un paramètre générique   qui s'étend du type   . Cela signifie qu'il accepte un argument   de type   , qui doit être un type compatible JSON. En conséquence, nous pouvons utiliser la fonction avec des types de données dépourvus de signature d’index. T JSONCompatible<T> data T   interface PostComment { authorId: string; text: string; updatedAt: number; } function saveComment(comment: PostComment) { const serializedComment = safeJsonStringify(comment); localStorage.setItem('draft', serializedComment); }  Cette approche peut être utilisée chaque fois que la sérialisation JSON est nécessaire, comme le transfert de données sur le réseau, l'intégration de données dans HTML, le stockage de données dans localStorage, le transfert de données entre travailleurs, etc. De plus, l'assistant   peut être utilisé lorsqu'un objet strictement typé sans une signature d'index doit être attribuée à une variable de type   . toJsonValue JSONValue   function toJsonValue<T>(value: JSONCompatible<T>): JSONValue { return value; } const comment: PostComment = {...}; const data: JSONValue = { comment: toJsonValue(comment) };  Dans cet exemple, l'utilisation   nous permet de contourner l'erreur liée à la signature d'index manquante dans le type   . toJsonValue PostComment  Gérer la désérialisation  En ce qui concerne la désérialisation, le défi est à la fois plus simple et plus complexe car il implique à la fois des contrôles d'analyse statique et des contrôles d'exécution pour le format des données reçues.  Du point de vue du système de types de TypeScript, le défi est assez simple. Considérons l'exemple suivant :   function safeJsonParse(text: string) { return JSON.parse(text) as unknown; } const data = JSON.parse(text); // ^? unknown  Dans ce cas, nous remplaçons le type de retour   par le type   . Pourquoi choisir   ? Essentiellement, une chaîne JSON peut contenir n'importe quoi, pas seulement les données que nous espérons recevoir. Par exemple, le format des données peut changer entre différentes versions de l'application ou une autre partie de l'application peut écrire des données sur la même clé LocalStorage. Par conséquent,   est le choix le plus sûr et le plus précis. any unknown unknown unknown  Cependant, travailler avec un type   est moins pratique que simplement spécifier le type de données souhaité. Outre la conversion de type, il existe plusieurs façons de convertir le type   en type de données requis. L'une de ces méthodes consiste à utiliser la bibliothèque   pour valider les données au moment de l'exécution et générer des erreurs détaillées si les données ne sont pas valides. unknown unknown Superstruct   import { create, object, number, string } from 'superstruct'; const PostComment = object({ authorId: string(), text: string(), updatedAt: number(), }); // Note: we no longer need to manually specify the return type function restoreDraft() { const text = localStorage.getItem('draft'); return text ? create(JSON.parse(text), PostComment) : undefined; }  Ici, la fonction   agit comme une protection de type,   le type à l'interface   souhaitée. Par conséquent, nous n’avons plus besoin de spécifier manuellement le type de retour. create limitant Comment  La mise en œuvre d’une option de désérialisation sécurisée ne représente que la moitié de l’histoire. Il est également crucial de ne pas oublier de l'utiliser lors de la prochaine tâche du projet. Cela devient particulièrement difficile si une grande équipe travaille sur le projet, car il peut être difficile de garantir que tous les accords et les meilleures pratiques sont respectés.    peut vous aider dans cette tâche. Cet outil permet d'identifier tous les cas   utilisation dangereuse. Plus précisément, toutes les utilisations de   peuvent être trouvées et il est possible de garantir que le format des données reçues est vérifié. Pour en savoir plus sur l'élimination de   type dans une base de code, consultez l'article   . Typescript-eslint any JSON.parse any Making TypeScript Truly "Strongly Typed"  Conclusion  Voici les fonctions et types d'utilitaires finaux conçus pour faciliter la sérialisation et la désérialisation JSON en toute sécurité. Vous pouvez les tester dans le   préparé. TS Playground   type JSONPrimitive = string | number | boolean | null | undefined; type JSONValue = JSONPrimitive | JSONValue[] | { [key: string]: JSONValue; }; type NotAssignableToJson = | bigint | symbol | Function; type JSONCompatible<T> = unknown extends T ? never : { [P in keyof T]: T[P] extends JSONValue ? T[P] : T[P] extends NotAssignableToJson ? never : JSONCompatible<T[P]>; }; function toJsonValue<T>(value: JSONCompatible<T>): JSONValue { return value; } function safeJsonStringify<T>(data: JSONCompatible<T>) { return JSON.stringify(data); } function safeJsonParse(text: string): unknown { return JSON.parse(text); }  Ceux-ci peuvent être utilisés dans toutes les situations où la sérialisation JSON est nécessaire.  J'utilise cette stratégie dans mes projets depuis plusieurs années maintenant et elle a démontré son efficacité en détectant rapidement les erreurs potentielles lors du développement d'applications.  J'espère que cet article vous a fourni de nouvelles informations. Merci pour la lecture!  Liens utiles   Rendre TypeScript vraiment "fortement typé"   Amélioration des types de bibliothèques standard de TypeScript   La bibliothèque de superstructures   Aire de jeux TS

The code in this story is for educational purposes. The readers are solely responsible for whatever they build with it.

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

This story contains AI-generated text. The author has used AI either for research, to generate outlines, or write the text itself. 

Maîtriser la sérialisation JSON Type-Safe dans TypeScript

About Author

COMMENTAIRES

ÉTIQUETTES

CET ARTICLE A ÉTÉ PARU DANS

Related Stories

Comment améliorer votre flux de travail par 10 : 17 applications essentielles

Appuyez pour gagner : Telegram pourrait intégrer les 10 prochains milliards d'utilisateurs de crypto avant Solana

Créer des produits cryptographiques centrés sur l'utilisateur : l'importance des retours clients

Le modèle Bitcoin UTXO, alimentant un écosystème unique

Comment améliorer votre flux de travail par 10 : 17 applications essentielles

Appuyez pour gagner : Telegram pourrait intégrer les 10 prochains milliards d'utilisateurs de crypto avant Solana

Créer des produits cryptographiques centrés sur l'utilisateur : l'importance des retours clients

Le modèle Bitcoin UTXO, alimentant un écosystème unique

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps