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. 

Cet audio est produit dans la langue originale de l'histoire !

Trop long; Pour lire

Making security fun one episode at a time

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

Trop long; Pour lire

Maksim Zemskov

STORY’S CREDIBILITY

Code License

Guide

AI-assisted

About Author

ÉTIQUETTES

Languages

CET ARTICLE A ÉTÉ PARU DANS...

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

Trop long; Pour lire

Maksim Zemskov

STORY’S CREDIBILITY

Code License

Guide

AI-assisted

About Author

ÉTIQUETTES

Languages

CET ARTICLE A ÉTÉ PARU DANS...

HISTOIRES CONNEXES