Antwort.

Historie der Frage:

Viele Bibliotheken des JavaScript-Ökosystems bieten nur Quell-js-Dateien an, ohne eigene Typen. Um die Typen von Drittanbieter- oder benutzerdefinierten Bibliotheken sowie von globalen Variablen zu beschreiben, hat TypeScript ein spezielles Format von Dateien mit der Erweiterung .d.ts (Declaration Files) implementiert. Diese sind zum Standard geworden, um Typinformationen und Typensicherheit in Projekten über beliebigen js-Modulen zu gewährleisten.

Problem:

Wenn die Typen für externe JS-Module nicht definiert sind, ist TypeScript gezwungen, solche Importe als any zu interpretieren, was bedeutet, dass Sie alle Vorteile der statischen Typisierung verlieren: Fehler bei Aufrufen, nicht existierenden Feldern und falschen Parametern werden logisch kompiliert und erst nach dem Ausführen des Codes erkannt. Außerdem ist es unmöglich, Autokomplettierung und Navigation durch Typen durchzuführen.

Lösung:

Mit Hilfe von Declaration Files kann man manuell Typen für jeden JS-Code beschreiben: Funktionen, Klassen, Objekte, Namensräume und sogar globale Konstanten. So bleibt das Projekt typensicher, unabhängig vom Ursprung der externen Bibliothek.

Code-Beispiel:

// hello.d.ts
declare module 'hello' {
  export function sayHello(name: string): string;
}
// app.ts
import { sayHello } from 'hello';
sayHello('TypeScript'); // Typ ist sicher

Kernmerkmale:

Trennt die Beschreibung von Signaturen und Typstrukturen von der Implementierung (Quell-JS-Code);
Ermöglicht strenge Typisierung sogar in externen/ungleichen Builds;
In .d.ts-Dateien ist die Implementierung verboten, nur Signaturen/Beschreibung.

Trickfragen.

Kann man Implementierungen von Funktionen direkt in der Declaration-Datei deklarieren?

Nein, in Declaration-Dateien sind nur die Deklaration von Strukturen und Signaturen erlaubt, nicht deren Implementierung. Jegliche Funktionskörper oder Konstruktoren würden einen Kompilierungsfehler auslösen.

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

Wo findet man Typen für beliebte npm-Module, wenn sie im Quellpaket nicht vorhanden sind?

Im Repository DefinitelyTyped (npm-Paket @types/<lib>): Fast alle beliebten Pakete haben aktuelle Typen in Form von separaten npm-Modulen.

Kann man globale Variablen (nicht über import) mit d.ts-Dateien beschreiben?

Ja, über den Mechanismus der ambient declarations, beispielsweise declare var VERSION: string;. Dies ist nützlich zur Beschreibung von window.X, globalen Konstanten und Variablen.

Typische Fehler und Anti-Pattern

Funktions- und Klassentextkörper in d.ts-Dateien schreiben;
Unvollständige oder veraltete Signaturen beschreiben, die Konflikte mit der tatsächlichen Struktur verursachen;
Verschiedene Typen für ein Modul/eine globale Variable anschließen, was Typkonflikte verursacht.

Beispiel aus der Praxis

** Negativer Fall In einem Projekt wird eine JS-Bibliothek ohne Typen verwendet. Die Entwickler haben die d.ts-Datei vergessen und rufen die API über any auf. Bei einem Update der Bibliothek treten Bugs auf: alte Aufrufe brechen, aber der Compiler erkennt das nicht.

Vorteile:

Schneller Start, keine zusätzliche Beschreibung erforderlich.

Nachteile:

Verborgene Fehler, unvorhersehbares Verhalten, schwieriges Debugging bei großen Code-Mengen.

** Positiver Fall Eine eigene d.ts-Datei für die aktuelle Bibliothek wurde entwickelt, die Signaturen werden aktuell gehalten, IDE verwendet Autocompletion und Typnavigation.