Antwoord.

Achtergrond:

Veel bibliotheken in het JavaScript-ecosysteem bieden alleen bron js-bestanden aan, zonder eigen types. Voor het beschrijven van types van externe of aangepaste bibliotheken, evenals globale variabelen, heeft TypeScript een speciaal bestandsformaat geïmplementeerd met de extensie .d.ts (declaration files). Ze zijn de standaard geworden voor het waarborgen van type-informatie en typeveiligheid in projecten bovenop elke js-module.

Probleem:

Als types voor externe JS-modules niet zijn gedefinieerd, is TypeScript gedwongen dergelijke imports als any te behandelen, wat betekent dat je alle voordelen van statische typechecking verliest: fouten in aanroepen, niet-bestaande velden en verkeerde parameters worden logischerwijs gecompileerd en worden alleen na het uitvoeren van de code ontdekt. Het is ook onmogelijk om autocompletion en navigatie op types te doen.

Oplossing:

Met declaration files kun je handmatig types beschrijven voor elke JS-code: functies, classes, objecten, namespaces en zelfs globale constanten. Op deze manier blijft het project typeveilig, ongeacht de herkomst van de externe bibliotheek.

Voorbeeldcode:

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

Kernkenmerken:

Scheidt het beschrijven van signatures en structuren van types van de implementatie (bron JS-code);
Stelt strikte typing mogelijk, zelfs in externe/oudere builds;
In .d.ts-bestanden is implementatie verboden, alleen signatures/beschrijvingen.

Vragen met een valstrik.

Kan je implementaties van functies rechtstreeks in een declaration-file verklaren?

Nee, in declaration-files is alleen het verklaren van structuren en signatures toegestaan, niet hun implementatie. Elke functie-body, constructor zal een compilatiefout veroorzaken.

// Niet toegestaan:
declare function sum(a: number, b: number) { return a + b; }

Waar vind je types voor populaire npm-modules, als ze niet in de originele package zitten?

In de DefinitelyTyped repository (npm-pakket @types/<lib>): bijna alle populaire pakketten hebben actuele typings in de vorm van afzonderlijke npm-modules.

Kun je globale variabelen beschrijven (niet via import), met behulp van een d.ts-bestand?

Ja, via het mechanisme van ambient declarations, bijvoorbeeld, declare var VERSION: string;. Dit is handig voor het beschrijven van window.X, globale constanten en variabelen.

Typfouten en antidocpatronen

Functie- en class bodies in d.ts-bestanden opnemen;
Onvolledige of verouderde signatures beschrijven, wat conflicten met de werkelijke structuur oproept;
Verschillende typings voor één module/globale variabele aansluiten, wat typeconflicten veroorzaakt.

Voorbeeld uit het leven

** Negatieve case In het project wordt een JS-bibliotheek zonder typings gebruikt. De ontwikkelaars zijn de d.ts-file vergeten en benaderen de API via any. Er ontstaan bugs bij het updaten van de bibliotheek: oude aanroepen breken, maar de compiler merkt dit niet op.

Voordelen:

Snelle start, geen extra beschrijving vereist.

Nadelen:

Verborgen fouten, impliciet gedrag, moeilijke debugging bij grote codevolumes.

** Positieve case Een eigen d.ts-bestand is ontwikkeld voor de huidige bibliotheek, signatures worden up-to-date gehouden, IDE-autocompletion en navigatie worden gebruikt.