TypeScript as: Type Assertions und Casting erklärt

value as Type ist eine Typ-Assertion: Sie sagt TypeScript, value als Type zu behandeln. Man nennt das oft Cast, aber es ist nur eine Anweisung an den Compiler. Sie wird aus der JavaScript-Ausgabe entfernt, wandelt nichts um und prüft zur Laufzeit nichts.

interface Config {
  port: number;
  host: string;
}

const text = '{"port": 8080, "host": "localhost"}';

// JSON.parse returns any; the assertion gives the result a useful type
const config = JSON.parse(text) as Config;

console.log(config.port + 1);            // 8081
console.log(config.host.toUpperCase());  // LOCALHOST

Das ist der typische Einsatz: Du weißt über einen Wert mehr als der Compiler (hier die Form von JSON-Daten) und sagst es ihm. Liegst du falsch, warnt dich nichts. Die nächsten Abschnitte zeigen, was das bedeutet und wann eine Prüfung zur Laufzeit die bessere Wahl ist.

as und die Syntax mit spitzen Klammern

Es gibt zwei Schreibweisen derselben Assertion:

const someValue: unknown = "hello";
const a = someValue as string;   // as syntax
const b = <string>someValue;     // angle-bracket syntax, same meaning

Die Form mit spitzen Klammern ist in .tsx-Dateien nicht erlaubt, wo <string> als JSX-Tag gelesen würde. Nimm überall as, dann stellt sich die Frage nie. Assertions binden schwach, setze sie also in Klammern, wenn der Ausdruck weitergeht: (value as string).length.

Assertions wandeln keine Werte um

Genau das verursacht echte Bugs. Eine Assertion ändert, was der Compiler über einen Wert glaubt, nicht den Wert selbst:

const input: unknown = "42";

const asserted = input as number;  // compiles: unknown can be asserted to anything
const converted = Number(input);   // an actual conversion

console.log(asserted + 1);   // 421 (string concatenation: it is still "42")
console.log(converted + 1);  // 43
console.log(typeof asserted, typeof converted); // string number

Der Compiler glaubt, asserted sei eine number, also besteht asserted + 1 die Typprüfung als Rechnung. Zur Laufzeit ist es weiterhin der String "42", und JavaScript verkettet. Um den Typ eines Werts zu ändern, wandle ihn um: Number(x), String(x), Boolean(x), BigInt(x), new Date(x). Die Seite String in Zahl umwandeln vergleicht die Umwandlungsfunktionen.

Was der Compiler erlaubt

as ist nicht unbegrenzt. TypeScript erlaubt x as T, wenn einer der Typen dem anderen zuweisbar ist: Erweitern ("a" as string, dog as Animal) und Einengen (animal as Dog, unknown as User) sind beide in Ordnung. Überschneiden sich die Typen gar nicht, verweigert es:

// This does not compile: string and number do not overlap.
const input = "42";
const n = input as number;

console.log(n);

Der Compiler meldet index.ts(3,11): error TS2352: Conversion of type 'string' to type 'number' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first. Die Meldung nennt selbst den Notausgang: input as unknown as number. Diese doppelte Assertion kompiliert und ist zur Laufzeit genauso falsch wie das Beispiel oben. Wenn du sie zu brauchen glaubst, ist die richtige Lösung meist eine Umwandlung (Number(input)) oder ein anderer Typ.

Die Regel zur Überschneidung ist bei Objekten locker. Ein Objektliteral, das einige der Eigenschaften hat, wird akzeptiert, und so lässt as still unvollständige Objekte durch:

interface User {
  name: string;
  email: string;
}

const draft = { name: "Ada" } as User; // compiles: email is missing
const empty = {} as User;              // compiles too

console.log(draft.name);               // Ada
console.log(typeof draft.email);       // undefined, although the type says string
console.log(empty.name?.length);       // undefined

Eine Annotation (const draft: User = { name: "Ada" }) oder satisfies User würde das fehlende email melden (TS2741). Nimm as bei einem Objektliteral nur, wenn du es wirklich später füllen willst, und baue lieber das vollständige Objekt.

as const ist etwas anderes

as const sieht aus wie eine Assertion, bewirkt aber das Gegenteil von Lockern: Es macht ein Literal so eng wie möglich. Strings bleiben Literaltypen, Arrays werden zu readonly Tupeln, und Objekteigenschaften werden readonly.

const sizes = ["small", "medium", "large"] as const;
type Size = (typeof sizes)[number]; // "small" | "medium" | "large"

const point = { x: 1, y: 2 } as const; // { readonly x: 1; readonly y: 2 }

function isSize(value: string): value is Size {
  return (sizes as readonly string[]).includes(value);
}

console.log(isSize("medium"), isSize("huge")); // true false
console.log(point.x + point.y);                // 3

Das ist sicher, weil es das Literal genau beschreibt, statt etwas zu behaupten, was der Compiler nicht sehen kann. (Das sizes as readonly string[] in isSize ist eine erweiternde Assertion und ebenfalls sicher: Sie lässt includes jeden String akzeptieren.) Mehr dazu unter Literaltypen.

Wann ein Type Guard das bessere Werkzeug ist

as ist eine Behauptung; ein Type Guard ist eine Prüfung. An einer Grenze, an der Daten von außerhalb deines Codes kommen (JSON, fetch, localStorage, Benutzereingaben, eine Nachricht), kann die Behauptung falsch sein, und eine Assertion macht aus einem klaren Fehler an der Grenze einen verwirrenden an ganz anderer Stelle.

interface Point {
  x: number;
  y: number;
}

function isPoint(v: unknown): v is Point {
  return typeof v === "object" && v !== null &&
    "x" in v && typeof v.x === "number" &&
    "y" in v && typeof v.y === "number";
}

const raw: unknown = JSON.parse('{"x": 3, "y": "4"}');

// With as: compiles, and the bug surfaces later
const p1 = raw as Point;
console.log(p1.x + p1.y); // 34 (a string snuck in)

// With a guard: the bad data is caught where it enters
if (isPoint(raw)) console.log(raw.x + raw.y);
else console.log("invalid point");

Eine grobe Orientierung zu den ähnlich aussehenden Werkzeugen:

Zwei gute Einsätze von as bleiben: etwas einengen, dem der Compiler nicht folgen kann (ein Map-Eintrag, den du zwei Zeilen vorher gesetzt hast, ein Wert aus einer untypisierten Bibliothek), und Testcode, der unvollständige Fixtures baut. Halte sie klein und nah an der Stelle, an der du weißt, dass die Behauptung stimmt.