TypeScript Best Practices: 8 Regeln mit Vorher und Nachher

Die folgenden Regeln verhindern in echtem TypeScript-Code die meisten Bugs. Jede zeigt zuerst die übliche Variante und dann die bessere, in Code, den du ausführen kannst. Die erste Regel ist die wichtigste: Hör auf, any zu verwenden.

unknown statt any verwenden

any schaltet die Typprüfung für einen Wert und alles, was daraus berechnet wird, ab. unknown akzeptiert ebenfalls jeden Wert, aber du musst ihn vor der Verwendung prüfen, und damit liegt die Prüfung dort, wo die Daten in dein Programm kommen:

// Before: any switches off checking for everything it touches.
function totalAny(items: any): number {
  return items.reduce((sum: number, item: any) => sum + item.price, 0);
}
console.log(totalAny([{ price: 2 }, { cost: 3 }])); // NaN, no error anywhere

// After: take unknown, check once at the boundary, then work with real types.
interface Item {
  price: number;
}

function isItems(value: unknown): value is Item[] {
  return Array.isArray(value) && value.every((i) => typeof i?.price === "number");
}

function total(input: unknown): number {
  if (!isItems(input)) throw new Error("Expected a list of items with prices");
  return input.reduce((sum, item) => sum + item.price, 0);
}

console.log(total([{ price: 2 }, { price: 3 }])); // 5
try {
  total([{ price: 2 }, { cost: 3 }]);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Expected a list of items with prices
}

Die Grenzen sind die Stellen, an denen Typen nicht mehr garantiert sind: JSON.parse, Antworten von fetch, localStorage, Formulareingaben, Umgebungsvariablen und Nachrichten anderer Prozesse. Validiere dort mit einem Type Guard oder einer Schema-Bibliothek, dann kann der restliche Code seinen Typen vertrauen.

strict anlassen

strict ist in TypeScript 7 der Standard; schalte es nicht ab. Ergänze die Prüfungen, die es auslässt und die die meisten Bugs finden:

{
    "compilerOptions": {
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "noImplicitOverride": true,
        "noFallthroughCasesInSwitch": true
    }
}

noUncheckedIndexedAccess lässt arr[i] und record[key] undefined enthalten, was sie bei einem fehlenden Index auch zurückgeben. noImplicitOverride verlangt, dass eine Methode einer Unterklasse override angibt, und noFallthroughCasesInSwitch lehnt einen case ab, der in den nächsten läuft.

Inferenz arbeiten lassen

Annotiere, was TypeScript nicht wissen kann: Funktionsparameter und die Rückgabetypen von Funktionen, die andere Module nutzen. Lokale Variablen und Callback-Parameter überlässt du der Inferenz. Eine unnötige Annotation ist nicht nur Rauschen; sie kann einen Typ weiter machen als den Wert:

type Status = "active" | "banned";

function setStatus(status: Status): string {
  return `status set to ${status}`;
}

const annotated: string = "active"; // annotation widens the type to string
// @ts-expect-error string is not assignable to Status
setStatus(annotated);

const inferred = "active"; // inferred as the literal type "active"
console.log(setStatus(inferred)); // status set to active

const users = [{ id: 1, name: "Ada" }, { id: 2, name: "Lin" }];
const ids = users.map((u) => u.id); // inferred: number[]
console.log(ids); // [ 1, 2 ]

Ohne den Kommentar @ts-expect-error ist setStatus(annotated) der Fehler TS2345. Die abgeleitete const behält den Literaltyp "active" und wird deshalb akzeptiert. Fahre im Editor mit der Maus über eine Variable, um zu sehen, was abgeleitet wurde, bevor du einen Typ hinzufügst.

Union-Typen statt Enums bevorzugen

Eine Union aus String-Literalen bietet Autovervollständigung und Vollständigkeitsprüfungen ohne erzeugten Code. Brauchst du die Liste der Werte auch zur Laufzeit, leite den Typ aus einem as const Array ab:

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function canEdit(role: Role): boolean {
  return role !== "viewer";
}

console.log(canEdit("editor"));     // true
console.log(ROLES.filter(canEdit)); // [ 'admin', 'editor' ]

canEdit("owner"); // error TS2345: Argument of type '"owner"' is not assignable to parameter of type '"admin" | "editor" | "viewer"'.

Ein enum Role { Admin, Viewer } wird zu einem Objekt mit Reverse Mapping kompiliert, und ein numerischer Enum-Parameter akzeptiert jede number-Variable, sogar eine mit einem Wert, den das Enum nicht aufführt. Enums laufen außerdem nicht mit dem Type Stripping von Node (TypeScript enum is not supported in strip-only mode). Die Abwägungen werden auf der Seite zu Enums verglichen.

Konfigurationsobjekte mit satisfies prüfen

Annotierst du ein Objekt mit einem weiten Typ wie Record<string, Route>, werden seine Werte geprüft, aber seine Schlüssel gehen verloren. satisfies prüft dasselbe und behält den genauen Typ:

interface Route {
  path: string;
  auth: boolean;
}

// Annotated: every string key is allowed, so typos are not caught.
const loose: Record<string, Route> = {
  home: { path: "/", auth: false },
};
console.log(loose.hmoe); // undefined, and no compile error

// satisfies: checked against Route, but the exact keys are kept.
const routes = {
  home: { path: "/", auth: false },
  admin: { path: "/admin", auth: true },
} satisfies Record<string, Route>;

console.log(routes.admin.path); // /admin
// @ts-expect-error Property 'hmoe' does not exist
routes.hmoe;

Nimm eine Annotation, wenn die Variable genau den deklarierten Typ haben soll (ein Funktionsparameter, ein Wert, den du neu zuweist). Nimm satisfies für Lookup-Tabellen, Routen-Maps, Theme-Tokens und andere konstante Objekte.

Zustand mit Discriminated Unions modellieren

Ein einzelnes Objekt mit optionalen Feldern erlaubt Zustände, die nicht vorkommen können: loading: true zusammen mit einem error oder fehlendes data nach einem Erfolg. Eine Union aus Objekten mit einem gemeinsamen Tag erlaubt nur die echten Zustände, und jeder Zweig sieht nur seine eigenen Felder:

type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "error"; message: string };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", "); // data exists only here
    case "error":
      return `Error: ${state.message}`;
    default: {
      const unreachable: never = state; // fails if a case is missing
      return unreachable;
    }
  }
}

console.log(render({ status: "success", data: ["a", "b"] })); // a, b
console.log(render({ status: "error", message: "timeout" }));  // Error: timeout

Die Zeile mit never ist die Vollständigkeitsprüfung. Fügt jemand einen Zustand hinzu und vergisst, ihn zu behandeln, bricht der Build an dieser Zeile:

// This does not compile: a new state was added but not handled.
type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "cancelled" };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", ");
    default: {
      const unreachable: never = state;
      return unreachable;
    }
  }
}

console.log(render({ status: "loading" }));

Der Fehler lautet index.ts(14,13): error TS2322: Type '{ status: "cancelled"; }' is not assignable to type 'never'. Er nennt den unbehandelten Fall. Ergänze case "cancelled":, und es kompiliert.

! und as vermeiden

Die Non-Null-Assertion x! und die Typ-Assertion x as T sagen dem Compiler, er solle aufhören zu prüfen. Keine von beiden ändert den Wert zur Laufzeit, eine falsche Assertion wird also später zu einem Absturz, weit weg von ihrer Ursache:

interface User {
  name: string;
}

const users = new Map<string, User>([["ada", { name: "Ada" }]]);

// Before: ! and as silence the compiler, and the crash moves to run time.
try {
  console.log(users.get("bob")!.name);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Cannot read properties of undefined (reading 'name')
}
const fake = {} as User;
console.log(fake.name); // undefined, typed as string

// After: handle the missing case where it can happen.
const bob = users.get("bob");
console.log(bob?.name ?? "unknown user"); // unknown user

Ersetze ! durch ?., ??, ein frühes return oder einen geworfenen Fehler mit einer hilfreichen Meldung. Ersetze as durch einen Type Guard, der den Wert tatsächlich prüft. Die eine Assertion, die immer sicher ist, ist as const, weil sie einen Typ nur enger und schreibgeschützt macht. Ein gutes Lint-Setup (no-non-null-assertion und no-explicit-any von typescript-eslint) markiert den Rest.

Daten readonly machen

Markiere Eigenschaften und Arrays als readonly, wenn Code sie nicht ändern soll. Der Compiler lehnt dann push, sort und Zuweisungen ab, und Funktionen geben neue Werte zurück, statt ihre Eingaben zu verändern:

interface Settings {
  readonly theme: "light" | "dark";
  readonly tags: readonly string[];
}

function withTag(settings: Settings, tag: string): Settings {
  // settings.tags.push(tag) would not compile
  return { ...settings, tags: [...settings.tags, tag] };
}

const before: Settings = { theme: "dark", tags: ["a"] };
const after = withTag(before, "b");
console.log(before.tags, after.tags); // [ 'a' ] [ 'a', 'b' ]

// @ts-expect-error Cannot assign to 'theme' because it is a read-only property.
before.theme = "light";

readonly wird nur beim Kompilieren geprüft und nur eine Ebene tief: Das Objekt wird zur Laufzeit nicht eingefroren. Das reicht trotzdem, um die versehentliche Veränderung gemeinsam genutzter Zustände zu finden, die die meisten dieser Bugs verursacht.