TypeScript any vs unknown: Unterschiede und wann was

any und unknown akzeptieren beide jeden Wert. Der Unterschied liegt darin, was du danach mit dem Wert tun kannst: any lässt dich alles tun und prüft nichts, während unknown dich fast nichts tun lässt, bis du beweist, was der Wert ist.

let a: any = "hello";
let u: unknown = "hello";

console.log(a.toUpperCase()); // HELLO: any allows every operation

// @ts-expect-error: 'u' is of type 'unknown'.
u.toUpperCase();

if (typeof u === "string") {
  console.log(u.toUpperCase()); // HELLO: u is a string inside this block
}

Ohne die Zeile mit @ts-expect-error ist u.toUpperCase() der Compilerfehler TS18046. Die Prüfung mit typeof engt u auf string ein, und in diesem Block ist jede String-Methode verfügbar.

any vs unknown im Überblick

Typtheoretisch ist unknown der Top Type: Jeder Typ ist ihm zuweisbar, und er selbst ist nur unknown und any zuweisbar. any ist ein Notausgang, der in beide Richtungen zuweisbar ist, zu allem außer never.

any schaltet die Typprüfung ab

Einem als any typisierten Wert wird blind vertraut. Der Compiler akzeptiert Tippfehler, falsche Typen und fehlende Eigenschaften, und die Fehler tauchen stattdessen zur Laufzeit auf.

const user: any = { name: "Ada" };

const total: number = user.name; // compiles: any is assignable to number
console.log(typeof total);       // string

const city = user.adress;        // typo, still compiles
console.log(city);               // undefined

try {
  console.log(user.address.city); // compiles, throws at runtime
} catch (e) {
  console.log((e as Error).message);
}

Die Ausgabe zeigt das Problem: Eine als number annotierte Variable enthält einen String, und die letzte Zeile wirft Cannot read properties of undefined (reading 'city'). any breitet sich außerdem aus. user.name ist any, also ist jeder daraus berechnete Wert any, und ein einziger untypisierter Wert kann die Prüfung weit entfernt von der Stelle abschalten, an der er hereinkam.

unknown zwingt dich zuerst zu prüfen

Bei unknown verweigert der Compiler jede Operation, bis der Code den Wert einengt. Das Einengen nutzt gewöhnliche JavaScript-Prüfungen, und in jedem Zweig hat der Wert den geprüften Typ.

function describe(value: unknown): string {
  if (typeof value === "string") return `string of length ${value.length}`;
  if (typeof value === "number") return `number ${value.toFixed(2)}`;
  if (Array.isArray(value)) return `array of ${value.length}`;
  if (value instanceof Date) return `date ${value.toISOString()}`;
  if (value === null) return "null";
  if (typeof value === "object" && "id" in value) return `object with id ${String(value.id)}`;
  return typeof value;
}

console.log(describe("hi"));                               // string of length 2
console.log(describe(3.14159));                            // number 3.14
console.log(describe([1, 2, 3]));                          // array of 3
console.log(describe(new Date("2024-03-15T10:30:00Z")));   // date 2024-03-15T10:30:00.000Z
console.log(describe({ id: 7 }));                          // object with id 7
console.log(describe(undefined));                          // undefined

Die Prüfung value === null muss vor der Objektprüfung stehen, weil typeof null gleich "object" ist. Nach "id" in value weiß TypeScript, dass das Objekt eine Eigenschaft id hat, typisiert als unknown, da nichts sagt, was sie enthält. String() macht daraus ausdrücklich Text; um sie als Zahl zu verwenden, würdest du sie zuerst mit typeof prüfen.

Du kannst die Prüfung auch mit einer Assertion überspringen, value as string, und der Compiler akzeptiert das. Das ist ein Versprechen ohne Prüfung zur Laufzeit dahinter, bevorzuge also eine echte Prüfung; siehe Typ-Assertions.

JSON mit unknown validieren

JSON.parse ist so deklariert, dass es any zurückgibt, sein Ergebnis schaltet die Prüfung also stillschweigend ab. Annotiere das Ergebnis als unknown und schreibe einen Type Guard, der die Form prüft, bevor der restliche Code ihr vertraut.

interface Settings {
  theme: string;
  fontSize: number;
}

function isSettings(v: unknown): v is Settings {
  return (
    typeof v === "object" && v !== null &&
    "theme" in v && typeof v.theme === "string" &&
    "fontSize" in v && typeof v.fontSize === "number"
  );
}

const inputs = ['{"theme":"dark","fontSize":14}', '{"theme":"dark"}'];

for (const text of inputs) {
  const data: unknown = JSON.parse(text);
  if (isSettings(data)) {
    console.log(`${data.theme} at ${data.fontSize}px`);
  } else {
    console.log("invalid settings:", text);
  }
}

Die erste Eingabe gibt dark at 14px aus, die zweite wird abgelehnt, weil fontSize fehlt. Mit any wäre die zweite Eingabe als Settings mit undefiniertem fontSize durchgelaufen. Bei großen Schemas erledigt eine Validierungsbibliothek dieselbe Aufgabe und leitet den Typ für dich ab.

noImplicitAny

any kommt nicht nur von Leuten, die es schreiben. Ein Parameter ohne Annotation und ohne Kontext, aus dem sich ableiten ließe, wäre ebenfalls any. Die Option noImplicitAny, die strict einschaltet, meldet das als Fehler:

// This does not compile: x has no type
function double(x) {
  return x * 2;
}

console.log(double(4));

index.ts(2,17): error TS7006: Parameter 'x' implicitly has an 'any' type.

Die Lösung ist eine Annotation, function double(x: number). Ausdrücklich x: any zu schreiben kompiliert auch, und genau darum geht es: any bleibt im Code sichtbar und lässt sich suchen und prüfen.

Wo sich any trotzdem einschleicht

Selbst unter strict erzeugen diese Quellen any, ohne dass das Wort in deinem Code steht:

Die Variable in catch ist unter strict unknown, weil alles geworfen werden kann, nicht nur Error-Objekte. Enge sie mit e instanceof Error ein, bevor du e.message liest.

Wann any in Ordnung ist

any ist nicht verboten, aber jedes davon ist eine Stelle, die der Compiler nicht mehr schützt. Vernünftige Einsätze:

• Die Migration einer JavaScript-Codebasis, in der any markiert, was noch nicht typisiert ist.
• Code, den das Typsystem nicht gut ausdrücken kann, klein gehalten und hinter einer typisierten Funktionssignatur.
• Testcode, der absichtlich fehlerhafte Daten übergibt.

Für alles andere deckt unknown denselben Fall „ich kenne diesen Typ nicht“ ab und behält die Prüfungen. Viele Teams setzen das mit der Lint-Regel @typescript-eslint/no-explicit-any durch. Ein verwandter Typ, Record<string, unknown>, ist die übliche Wahl für „irgendein Objekt mit unbekannten Werten“.