Typen für Bibliotheken und Deklarationsdateien

Woher kommen die Typen einer Bibliothek?

Wenn du ein JavaScript-Paket importierst, braucht TypeScript dessen Typen. Es gibt drei Fälle:

1. Das Paket bringt Typen mit (Feld types in der package.json): nichts zu tun. Das gilt heute für die meisten modernen Pakete.
2. Typen kommen aus DefinitelyTyped: Installiere npm install -D @types/<paket>, zum Beispiel @types/node, @types/express, @types/lodash.
3. Es gibt keine Typen: Dann meldet TypeScript "Could not find a declaration file". Du schreibst selbst eine Deklaration oder behilfst dich mit declare module "paket"; (alles wird any).

Deklarationsdateien (.d.ts)

Eine .d.ts-Datei enthält nur Typen, keinen Code. Sie beschreibt, was in einer JavaScript-Datei oder Bibliothek steckt:

// mathe-lib.d.ts
declare module "mathe-lib" {
  export function addiere(a: number, b: number): number;
  export const PI: number;
  export interface Optionen { runden?: boolean }
  export default function rechne(ausdruck: string, optionen?: Optionen): number;
}

Mit declare sagst du: "Das gibt es, ich beschreibe nur seine Form."

Eigene Bibliothek mit Typen veröffentlichen

Wenn du in TypeScript schreibst, erzeugt der Compiler die Typen automatisch:

{
  "compilerOptions": { "declaration": true, "outDir": "dist" }
}

In der package.json verweist "types": "dist/index.d.ts" darauf. Neuere Projekte beschreiben das über das Feld exports.

Typ-Importe von Werten trennen

import type { IncomingMessage } from "node:http";      // nur Typ

function methode(a: IncomingMessage): string | undefined {
  return a.method;
}
console.log(typeof methode);

function

Module erweitern (Augmentation)

Manche Bibliotheken lassen sich um eigene Eigenschaften erweitern, etwa Express um req.user:

// types/express.d.ts
import "express";
declare module "express-serve-static-core" {
  interface Request { user?: { id: number; rolle: string } }
}

Typen testen

Auch Typen kann man testen: Prüfe, dass ein Typ das ist, was du erwartest. Mit einem Hilfstyp schlägt der Compiler Alarm, wenn sich ein Typ ändert:

type Gleich<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
type Erwartet<T extends true> = T;

type Test1 = Erwartet<Gleich<Awaited<Promise<number>>, number>>;      // kompiliert
// type Test2 = Erwartet<Gleich<string, number>>;                      // Fehler: false erfüllt true nicht
const ok: Test1 = true;
console.log(ok);

true

Fertige Hilfen bieten Werkzeuge wie tsd, expect-type oder vitest --typecheck.

Häufige Fehlermeldungen verstehen

Lies lange Fehlermeldungen von unten nach oben: Die letzte Zeile nennt meist die eigentliche Ursache.

interface Benutzer { name: string; adresse?: { stadt: string } }
const b: Benutzer = { name: "Mia" };
console.log(b.adresse.stadt);

error TS18048: 'b.adresse' is possibly 'undefined'.

Notausgänge, mit Verstand

Sparsam einsetzen, immer mit Kommentar, warum.