Réponse.

Historique de la question :

De nombreuses bibliothèques de l'écosystème JavaScript ne fournissent que des fichiers js sources, ne disposant pas de leurs propres types. Pour décrire les types des bibliothèques tierces ou personnalisées, ainsi que des variables globales, TypeScript met en œuvre un format spécial de fichiers avec l'extension .d.ts (fichiers de déclaration). Ils sont devenus la norme pour garantir l'information de type et la sécurité des types dans les projets utilisant n'importe quels modules js.

Problème :

Si les types pour les modules JS tiers ne sont pas définis, TypeScript est contraint d'interpréter ces imports comme any, ce qui signifie que vous perdez tous les avantages de la typage statique : les erreurs dans les appels, les champs inexistants, des paramètres incorrects passent logiquement la compilation et ne sont détectés qu'après l'exécution du code. Il est également impossible de faire de l'autocomplétion et de la navigation dans les types.

Solution :

Avec les fichiers de déclaration, vous pouvez manuellement décrire les types pour n'importe quel code JS : fonctions, classes, objets, espaces de noms et même constantes globales. Ainsi, le projet reste typé en toute sécurité, quelle que soit l'origine de la bibliothèque externe.

Exemple de code :

// hello.d.ts
declare module 'hello' {
  export function sayHello(name: string): string;
}
// app.ts
import { sayHello } from 'hello';
sayHello('TypeScript'); // Type sûr

Caractéristiques clés :

Sépare la description des signatures et des structures de types de l'implémentation (code JS source) ;
Permet d'intégrer une typage stricte même dans des builds tiers/obsolètes ;
Dans les fichiers .d.ts, l'implémentation est interdite, seules les signatures/descriptions sont autorisées.

Questions pièges.

Peut-on déclarer les implémentations de fonctions directement dans le fichier de déclaration ?

Non, dans les fichiers de déclaration, seules les déclarations de structures et de signatures sont autorisées, et non leur implémentation. Tout corps de fonction, constructeur entraînera une erreur de compilation.

// Pas autorisé :
declare function sum(a: number, b: number) { return a + b; }

Où chercher des types pour des modules npm populaires, s'ils ne sont pas dans le paquet source ?

Dans le dépôt DefinitelyTyped (paquet npm @types/<lib>) : presque tous les paquets populaires ont des types actuels sous forme de modules npm séparés.

Peut-on décrire des variables globales (sans import) en utilisant un fichier .d.ts ?

Oui, via le mécanisme des déclarations ambiantes, par exemple, declare var VERSION: string ;. C'est pratique pour décrire window.X, des constantes et variables globales.

Erreurs typiques et anti-patrons

Écrire des corps de fonctions et de classes dans les fichiers .d.ts ;
Décrire des signatures incomplètes ou obsolètes, provoquant un conflit avec la structure réelle ;
Connecter différents types pour un module/variable globale, provoquant un conflit de types.

Exemple de la vie réelle

** Cas négatif Dans le projet, une bibliothèque JS est utilisée sans typages. Les développeurs ont oublié le fichier .d.ts et accèdent à l'API via any. Des bugs surviennent lors de la mise à jour de la bibliothèque : les anciens appels se cassent, mais le compilateur ne le remarque pas.

Avantages :

Démarrage rapide, aucune description supplémentaire requise.

Inconvénients :

Erreurs cachées, comportement implicite, débogage complexe sur de grands volumes de code.

** Cas positif Un fichier .d.ts a été développé pour la bibliothèque actuelle, les signatures sont maintenues à jour, l'autocomplétion et la navigation IDE sont utilisées.