Les secrets des *.d.ts : comment TypeScript voit le code des autres

Introduction : pourquoi votre code « s’entend » avec lodash ?

Avez-vous déjà réfléchi à la façon dont TypeScript connaît les types pour une bibliothèque JavaScript ordinaire comme lodash ou jQuery ? Vous écrivez simplement import _ from 'lodash', et soudainement vous obtenez l’autocomplétion et la vérification des types. De la magie ? Non, c’est le travail des mystérieux fichiers *.d.ts.

Sur Stack Overflow, la question « About "*.d.ts" in TypeScript » a recueilli des milliers de vues — les développeurs veulent comprendre ce qui se cache derrière cette extension. Aujourd’hui, nous allons regarder sous le capot de TypeScript et analyser comment fonctionnent les déclarations de types. Vous apprendrez non seulement la théorie, mais vous obtiendrez également des exemples pratiques qui vous aideront à créer vos propres types pour n’importe quel projet JavaScript.

Qu’est-ce qu’un .d.ts en réalité ?

Les fichiers avec l’extension .d.ts sont des fichiers de déclaration TypeScript. Ils contiennent uniquement des descriptions de types, mais pas d’implémentation. Considérez-les comme un « contrat » : TypeScript regarde ce fichier et comprend quelles fonctions, classes et variables existent, et quels sont leurs types.

La différence clé avec les fichiers .ts ordinaires : .d.ts n’est pas compilé en JavaScript. Ils existent uniquement pour l’analyse statique et l’autocomplétion.

// myLibrary.d.tsexport function greet(name: string): void;export const VERSION: string;

Maintenant, si vous importez cette bibliothèque, TypeScript saura : greet prend une chaîne et ne retourne rien, et VERSION est une chaîne. Sans ce fichier, vous obtiendriez l’erreur « Could not find a declaration file for module ».

Comment TypeScript trouve-t-il les .d.ts ?

Le mécanisme de recherche des déclarations fonctionne en plusieurs étapes :

• Recherche automatique : Si un fichier .d.ts portant le même nom se trouve à côté d’un fichier .js, TypeScript le prendra automatiquement.
• Champ types ou typings dans package.json : De nombreuses bibliothèques indiquent le chemin vers leur fichier de déclaration. Par exemple : "types": "./lib/index.d.ts".
• Directive /// <reference path="" /> : Indication manuelle d’un fichier de déclaration (méthode obsolète mais encore rencontrée).
• Paquets @types : Si une bibliothèque ne contient pas ses propres types, la communauté les publie sur npm sous le nom @types/nom-de-la-bibliothèque.

Lorsque vous écrivez npm install @types/react, vous téléchargez précisément un ensemble de fichiers .d.ts qui décrivent React.

Sous le capot : comment TypeScript traite les .d.ts

Imaginons que TypeScript est un détective qui enquête sur « l’affaire des types ». Les fichiers .d.ts sont les témoignages. Ils disent : « Voici la fonction add, elle prend deux nombres et retourne un nombre ». TypeScript croit ces témoignages et ne vérifie pas si c’est vraiment le cas (car il n’y a pas d’implémentation).

Déclarations ambiantes (ambient declarations)

L’une des fonctionnalités les plus puissantes des .d.ts est la déclaration de modules ambiants. Cela permet de décrire les types pour des modules qui ne sont pas dans votre code. Par exemple, vous voulez utiliser la variable globale $ de jQuery :

// globals.d.tsdeclare var $: (selector: string) => any;

Ou décrire un module entier :

// my-custom-module.d.tsdeclare module 'my-custom-module' {    export function doSomething(x: number): string;    export interface Config {        timeout: number;    }}

Maintenant, vous pouvez écrire import { doSomething } from 'my-custom-module' — et TypeScript connaîtra les types.

Types globaux vs types modulaires

Une différence importante : les fichiers .d.ts peuvent être soit globaux (s’ils ne contiennent pas de import/export), soit modulaires (s’ils en contiennent). Les déclarations globales sont vis