4 Wie funktioniert TypeScript? Die Vogelperspektive

Dieses Kapitel bietet einen Überblick darüber, wie TypeScript funktioniert: Wie ist die Struktur eines typischen TypeScript-Projekts aufgebaut? Was wird wie kompiliert? Wie können wir IDEs verwenden, um TypeScript zu schreiben?

4.1 Die Struktur von TypeScript-Projekten

Dies ist eine mögliche Dateistruktur für TypeScript-Projekte

typescript-project/
  dist/
  ts/
    src/
      main.ts
      util.ts
    test/
      util_test.ts
  tsconfig.json

Erläuterungen

• Das Verzeichnis ts/ enthält die TypeScript-Dateien
  • Das Unterverzeichnis ts/src/ enthält den eigentlichen Code.
  • Das Unterverzeichnis ts/test/ enthält Tests für den Code.
• Das Verzeichnis dist/ ist der Ort, an dem die Ausgabe des Compilers gespeichert wird.
• Der TypeScript-Compiler kompiliert TypeScript-Dateien in ts/ zu JavaScript-Dateien in dist/. Zum Beispiel
  • ts/src/main.ts wird zu dist/src/main.js kompiliert (und möglicherweise andere Dateien)
• tsconfig.json wird zur Konfiguration des TypeScript-Compilers verwendet.

4.1.1 tsconfig.json

Der Inhalt von tsconfig.json sieht wie folgt aus

{
  "compilerOptions": {
    "rootDir": "ts",
    "outDir": "dist",
    "module": "commonjs",
    ···
  }
}

Wir haben angegeben, dass

• Das Stammverzeichnis des TypeScript-Codes ist ts/.
• Das Verzeichnis, in dem der TypeScript-Compiler seine Ausgabe speichert, ist dist/.
• Das Modulformat der Ausgabedateien ist CommonJS.

4.2 TypeScript-Programmierung über eine integrierte Entwicklungsumgebung (IDE)

Zwei beliebte IDEs für JavaScript sind

• Visual Studio Code (kostenlos)
• WebStorm (kostenpflichtig)

Die Beobachtungen in diesem Abschnitt beziehen sich auf Visual Studio Code, können aber auch für andere IDEs gelten.

Eine wichtige Tatsache, die man wissen muss, ist, dass Visual Studio Code TypeScript-Quellcode auf zwei unabhängige Arten verarbeitet

• Überprüfung geöffneter Dateien auf Fehler: Dies geschieht über einen sogenannten Sprachserver. Sprachserver existieren unabhängig von bestimmten Editoren und stellen Visual Studio Code sprachbezogene Dienste zur Verfügung: Fehlererkennung, Refactorings, Autovervollständigungen usw. Die Kommunikation mit Servern erfolgt über ein Protokoll, das auf JSON-RPC basiert (RPC steht für Remote Procedure Calls). Die durch dieses Protokoll gebotene Unabhängigkeit bedeutet, dass Server in fast jeder Programmiersprache geschrieben werden können.
  • Wichtiger Hinweis: Der Sprachserver listet nur Fehler für aktuell geöffnete Dateien auf und kompiliert TypeScript nicht, er analysiert es nur statisch.
• Erstellung (Kompilierung von TypeScript-Dateien zu JavaScript-Dateien): Hier haben wir zwei Möglichkeiten.
  • Wir können ein Build-Tool über einen externen Befehl ausführen. Zum Beispiel hat der TypeScript-Compiler tsc einen --watch-Modus, der Eingabedateien überwacht und diese bei Änderungen zu Ausgabedateien kompiliert. Infolgedessen erhalten wir, wann immer wir eine TypeScript-Datei in der IDE speichern, sofort die entsprechenden Ausgabedateien.
  • Wir können tsc von innerhalb von Visual Studio Code ausführen. Um dies zu tun, muss es entweder innerhalb des Projekts, an dem wir gerade arbeiten, oder global (über den Node.js-Paketmanager npm) installiert sein.
  Bei der Erstellung erhalten wir eine vollständige Liste von Fehlern. Weitere Informationen zum Kompilieren von TypeScript innerhalb von Visual Studio Code finden Sie in der offiziellen Dokumentation für diese IDE.

4.3 Andere Dateien, die vom TypeScript-Compiler erzeugt werden

Ausgehend von einer TypeScript-Datei main.ts kann der TypeScript-Compiler verschiedene Arten von Artefakten erzeugen. Die gebräuchlichsten sind

• JavaScript-Datei: main.js
• Deklarationsdatei: main.d.ts (enthält Typinformationen; denken Sie an eine .ts-Datei abzüglich des JavaScript-Codes)
• Source-Map-Datei: main.js.map

TypeScript wird oft nicht über .ts-Dateien, sondern über .js-Dateien und .d.ts-Dateien geliefert

• Der JavaScript-Code enthält die eigentliche Funktionalität und kann über reines JavaScript genutzt werden.
• Die Deklarationsdateien helfen Programmiereditoren bei der Autovervollständigung und ähnlichen Diensten. Diese Informationen ermöglichen es, reines JavaScript über TypeScript zu nutzen. Wir profitieren jedoch auch davon, wenn wir mit reinem JavaScript arbeiten, da es uns eine bessere Autovervollständigung und mehr bietet.

Eine Source Map gibt für jeden Teil des Ausgabecodes in main.js an, welcher Teil des Eingabecodes in main.ts ihn erzeugt hat. Diese Informationen ermöglichen es unter anderem Laufzeitumgebungen, JavaScript-Code auszuführen und dabei die Zeilennummern des TypeScript-Codes in Fehlermeldungen anzuzeigen.

4.3.1 Um npm-Pakete aus TypeScript zu verwenden, benötigen wir Typinformationen

Das npm-Repository ist ein riesiges Repository für JavaScript-Code. Wenn wir ein JavaScript-Paket aus TypeScript verwenden möchten, benötigen wir Typinformationen dafür

• Das Paket selbst kann .d.ts-Dateien oder sogar den vollständigen TypeScript-Code enthalten.
• Wenn nicht, können wir es möglicherweise trotzdem verwenden: DefinitelyTyped ist ein Repository von Deklarationsdateien, die Leute für reine JavaScript-Pakete geschrieben haben.

Die Deklarationsdateien von DefinitelyTyped befinden sich im @types-Namespace. Daher müssen wir, wenn wir eine Deklarationsdatei für ein Paket wie lodash benötigen, das Paket @types/lodash installieren.

4.4 Verwendung des TypeScript-Compilers für reine JavaScript-Dateien

Der TypeScript-Compiler kann auch reine JavaScript-Dateien verarbeiten

• Mit der Option --allowJs kopiert der TypeScript-Compiler JavaScript-Dateien aus dem Eingabeverzeichnis in das Ausgabeverzeichnis. Vorteil: Bei der Migration von JavaScript zu TypeScript können wir mit einer Mischung aus JavaScript- und TypeScript-Dateien beginnen und langsam mehr JavaScript-Dateien in TypeScript konvertieren.

• Mit der Option --checkJs prüft der Compiler zusätzlich JavaScript-Dateien auf Typen (--allowJs muss dafür aktiviert sein). Dies geschieht so gut er kann, angesichts der begrenzten verfügbaren Informationen. Welche Dateien geprüft werden, kann über Kommentare innerhalb dieser Dateien konfiguriert werden

  • Explizites Ausschließen: Wenn eine JavaScript-Datei den Kommentar // @ts-nocheck enthält, wird sie nicht auf Typen geprüft.
  • Explizites Einbeziehen: Ohne --checkJs kann der Kommentar // @ts-check verwendet werden, um einzelne JavaScript-Dateien auf Typen zu prüfen.

• Der TypeScript-Compiler verwendet statische Typinformationen, die über JSDoc-Kommentare angegeben werden (siehe unten für ein Beispiel). Wenn wir sorgfältig vorgehen, können wir reine JavaScript-Dateien vollständig statisch typisieren und sogar Deklarationsdateien daraus ableiten.

• Mit der Option --noEmit erzeugt der Compiler keine Ausgabe, er prüft nur Dateien auf Typen.

Dies ist ein Beispiel für einen JSDoc-Kommentar, der statische Typinformationen für eine Funktion add() liefert

/**
 * @param {number} x - The first operand
 * @param {number} y - The second operand
 * @returns {number} The sum of both operands
 */
function add(x, y) {
  return x + y;
}

Weitere Informationen: Type-Checking JavaScript Files im TypeScript Handbook.