Augmentation des modules TypeScript et gestion des fichiers JavaScript imbriqués

TypeScript a été une addition précieuse à l'écosystème JavaScript depuis plus d'une décennie, gagnant en popularité grâce à sa capacité à offrir une sécurité des types pour le code JavaScript.

Types pour les paquets JavaScript#

Pour assurer une compatibilité ascendante et une flexibilité, TypeScript permet aux auteurs de paquets de fournir des définitions de types pour leurs paquets JavaScript. Ces définitions de types sont généralement stockées dans le dépôt "DefinitelyTyped". Vous pouvez utiliser la portée @types pour installer ces définitions de types, par exemple, @types/react est la définition de type pour le paquet React.

Après avoir installé ces définitions de types, vous pouvez utiliser le paquet en toute confiance avec une sécurité des types. Voici un exemple de définition d'un composant React avec une sécurité des types :

Augmentation des modules#

Bien que la plupart des paquets JavaScript populaires aient des définitions de types facilement disponibles dans la portée @types, certains paquets peuvent ne pas avoir de définitions de types ou peuvent avoir des définitions obsolètes. Dans ces cas, TypeScript offre une fonctionnalité puissante appelée "augmentation des modules" pour ajouter des définitions de types à ces paquets. Prenons un exemple :

Maintenant, vous pouvez utiliser cette définition de type augmentée dans votre code :

L'augmentation des modules vous permet non seulement d'ajouter des définitions de types pour les paquets, mais aussi d'étendre les définitions de types existantes. Par exemple, vous pouvez ajouter une nouvelle propriété à l'objet window :

Et l'utiliser dans votre code :

Dans un article précédent, nous avons parlé d'un problème de type dans la bibliothèque React Router, et nous avons dû surmonter cet impact en étendant et augmentant le type existant via un fichier de déclaration personnalisé.

N'oubliez pas que lorsque vous utilisez l'augmentation des modules, il est crucial de garantir l'exactitude de vos définitions de types en inspectant de près le code source JavaScript. Des définitions de types incorrectes peuvent entraîner des erreurs d'exécution. Dans l'exemple ci-dessus, la propriété window.foo doit être une chaîne de caractères qui existe sur l'objet window.

Augmentation globale#

Parfois, vous pouvez rencontrer des scripts qui introduisent des variables globales, et vous pouvez vouloir fournir des définitions de types pour ces variables globales afin de les utiliser dans votre code TypeScript. Par exemple, si vous avez un script qui définit une variable globale appelée __DEV__ :

Vous pouvez ajouter des définitions de types pour cette variable globale comme ceci :

Maintenant, vous pouvez l'utiliser dans votre code TypeScript :

En combinant l'augmentation des modules et l'augmentation globale, vous pouvez même étendre les définitions de types pour les prototypes JavaScript. Cependant, cela est généralement déconseillé car cela peut polluer l'espace global.

La puissance de l'augmentation des modules permet de telles extensions, mais soyez prudent pour éviter de polluer l'espace global.

Fichiers JavaScript imbriqués#

Dans les exemples mentionnés précédemment, nous avons supposé que les imports pouvaient être résolus via le fichier d'entrée du paquet. Cependant, certains paquets exportent des fichiers JavaScript imbriqués sans définitions de types correspondantes. Considérons un paquet appelé foo avec la structure suivante :

Le paquet foo exporte le fichier index.js comme point d'entrée et exporte également le répertoire bar.

Pour augmenter les définitions de types pour le paquet foo, vous pouvez créer un fichier foo.d.ts :

Cependant, si vous essayez d'importer le fichier baz.js dans TypeScript, vous rencontrerez une erreur :

Pour augmenter les définitions de types pour le fichier baz.js, vous devez créer un fichier baz.d.ts séparé :

Cela garantit que TypeScript peut localiser le module et ses définitions de types associées :

Pour maintenir des définitions de types organisées, vous pouvez imiter la structure du paquet dans vos fichiers de définitions de types :

Cette approche permet de garder votre code TypeScript structuré et sûr en termes de types, même lorsque vous traitez des fichiers JavaScript imbriqués.