Formations — 1 037 leçons en français

Accueil › TypeScript › Typer une bibliothèque qui ne l'est pas

Typer une bibliothèque qui ne l'est pas

Modules et déclarationsintermediaire

Avant d'écrire une déclaration, il faut savoir d'où les types pourraient venir. Trois cas, dans cet ordre.

Types groupés. Le paquet contient ses propres .d.ts, annoncés par son package.json. Rien à faire — et ils ne peuvent pas se désynchroniser, puisqu'ils suivent la bibliothèque.

{ "name": "zod", "types": "./dist/index.d.ts" }

Paquet @types/*. Les déclarations existent, maintenues par la communauté dans DefinitelyTyped, dans un paquet séparé.

npm i -D @types/express

Rien. Il faut déclarer soi-même.

Déclarer un module sans types

// vendeur.d.ts
declare module "ancien-calendrier" {
  export interface Jour { date: string; ouvre: boolean }
  export function joursOuvres(debut: string, fin: string): Jour[];
}

On décrit ce qu'on utilise, et rien de plus. La tentation est le raccourci suivant.

declare module "ancien-calendrier";   // tout devient any, partout

Il compile et supprime toute vérification à chaque point d'usage.

Élargir une déclaration existante

import "express";

declare module "express" {
  interface Request {
    utilisateur?: { id: string; role: "admin" | "membre" };
  }
}

Le module est déjà typé : le bloc rouvre sa déclaration, et les interfaces de même nom fusionnent. Le ? dit la vérité — l'intergiciel qui remplit le champ peut ne pas s'être exécuté.

Les @types peuvent être faux

Ils vivent dans un autre dépôt, avec leur propre rythme de versions. Une option ajoutée depuis, un paramètre devenu optionnel, un export renommé : la déclaration se trompe et rien ne le signale.

Les termes à connaître

`@types/*`

Les paquets de déclarations publiés depuis le dépôt DefinitelyTyped. Ils sont écrits et maintenus par la communauté, séparément de la bibliothèque qu'ils décrivent.

Types groupés

Les déclarations livrées dans le paquet lui-même, annoncées par le champ types ou par exports.types. Elles suivent la bibliothèque et ne peuvent pas se désynchroniser.

`declare module "nom"`

Un bloc qui déclare la forme d'un module entier. Pour un paquet sans types, il fournit le minimum nécessaire ; mal utilisé, il annonce des exports qui n'existent pas.

Élargissement de déclaration

Rouvrir la déclaration d'un module déjà typé pour y ajouter quelque chose — un champ sur une interface existante. Il faut viser exactement le même spécificateur, et importer le module pour que le bloc soit pris en compte.

`skipLibCheck`

Option qui supprime la vérification interne des .d.ts. Elle accélère la compilation et masque les déclarations tierces incohérentes, sans rien changer à la vérification de votre code.

Frontière non typée

L'endroit où une donnée entre sans garantie. Une déclaration la décrit, elle ne la valide pas : la seule protection reste une validation à l'exécution.

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.