TypeScript try catch: Fehlertypen und eigene Errors

TypeScript verwendet try, catch, finally und throw von JavaScript. Der TypeScript-spezifische Teil ist die catch-Variable: Mit aktivem strict hat sie den Typ unknown, also prüfst du, was geworfen wurde, bevor du sie verwendest.

function parsePort(text: string): number {
    const port = Number(text);
    if (!Number.isInteger(port) || port < 1 || port > 65535) {
        throw new RangeError(`invalid port: "${text}"`);
    }
    return port;
}

try {
    console.log(parsePort("8080")); // 8080
    console.log(parsePort("http")); // throws
} catch (e) {
    // e: unknown
    if (e instanceof Error) {
        console.log(`${e.name}: ${e.message}`); // RangeError: invalid port: "http"
    }
} finally {
    console.log("done");
}

Die Seite zur Laufzeit (wie sich der Stack abbaut, welche eingebauten Fehlertypen es gibt) wird unter try/catch in JavaScript behandelt.

Warum die catch-Variable unknown ist

JavaScript kann alles werfen: einen Error, einen String, eine Zahl, undefined, ein Objekt aus einer Bibliothek. TypeScript kann nicht wissen, was, daher ist die Variable unter strict (dem Flag useUnknownInCatchVariables) unknown, und du musst sie vor der Verwendung einengen:

// This does not compile: e is unknown, so e.message is not allowed.
try {
    JSON.parse("{ broken");
} catch (e) {
    console.log("parse failed:", e.message);
}

index.ts(5,34): error TS18046: 'e' is of type 'unknown'.

Ohne strict ist e any, und derselbe Code kompiliert und geht dann zur Laufzeit schief, wenn ein String geworfen wird: e.message ist undefined, und alles Tiefere, etwa e.message.length, wirft einen TypeError. Mit einer Annotation kommst du auch nicht heraus: catch (e: Error) ist der Fehler TS1196 (Catch clause variable type annotation must be 'any' or 'unknown' if specified).

Den Fehler einengen

instanceof Error deckt alles ab, was auf Error aufbaut, einschließlich TypeError, SyntaxError, RangeError und deiner eigenen Unterklassen. Für alles andere wandelst du den Wert ersatzweise in einen String um. Eine kleine Hilfsfunktion hält die Aufrufstellen kurz:

function toError(value: unknown): Error {
    if (value instanceof Error) return value;
    if (typeof value === "string") return new Error(value);
    return new Error(`non-error thrown: ${JSON.stringify(value)}`);
}

const throwers: Array<() => void> = [
    () => JSON.parse("{"),
    () => { throw "plain string"; },
    () => { throw { code: 42 }; },
];

for (const run of throwers) {
    try {
        run();
    } catch (e) {
        const err = toError(e);
        console.log(err.constructor.name, "|", err.message);
    }
}
// SyntaxError | Expected property name or '}' in JSON at position 1 (line 1 column 2)
// Error | plain string
// Error | non-error thrown: {"code":42}

Ein catch, der nur manche Fehler behandelt, sollte den Rest erneut werfen: if (!(e instanceof ValidationError)) throw e;. Unbekannte Fehler zu verschlucken verdeckt echte Bugs.

Fehler werfen

throw akzeptiert jeden Ausdruck, und TypeScript schränkt das nicht ein. Wirf trotzdem Error-Objekte: Sie tragen einen Stacktrace, und jede Prüfung mit instanceof Error in der Codebasis hängt davon ab.

Eine Funktion, die immer wirft, hat den Rückgabetyp never, den TypeScript für das Narrowing nach dem Aufruf nutzt:

function fail(message: string): never {
    throw new Error(message);
}

function getEnv(env: Record<string, string | undefined>, key: string): string {
    const value = env[key];
    if (value === undefined) fail(`missing ${key}`);
    return value; // value: string, because fail() never returns
}

const env = { HOME: "/home/ada" };
console.log(getEnv(env, "HOME")); // /home/ada
try {
    getEnv(env, "PORT");
} catch (e) {
    if (e instanceof Error) console.log(e.message); // missing PORT
}

Seit ES2022 nimmt Error ein zweites Argument mit cause, das einen Fehler auf niedrigerer Ebene mit dem verbindet, den du wirfst: throw new Error("could not load settings", { cause: e }). Der Aufrufer kann err.cause lesen (typisiert als unknown).

Eigene Fehlerklassen

Eine Unterklasse von Error lässt Aufrufer Fehlschläge mit instanceof unterscheiden und trägt zusätzliche Daten. Setze name, denn der geerbte ist "Error" und erscheint in Logs und in String(err):

class HttpError extends Error {
    override name = "HttpError";

    constructor(readonly status: number, message: string, options?: ErrorOptions) {
        super(message, options);
    }
}

class NotFoundError extends HttpError {
    override name = "NotFoundError";

    constructor(resource: string) {
        super(404, `${resource} not found`);
    }
}

function handle(e: unknown): string {
    if (e instanceof NotFoundError) return `404 page for: ${e.message}`;
    if (e instanceof HttpError) return `HTTP ${e.status}: ${e.message}`;
    if (e instanceof Error) return `unexpected: ${e.message}`;
    return "unknown failure";
}

console.log(handle(new NotFoundError("user 7"))); // 404 page for: user 7 not found
console.log(handle(new HttpError(503, "maintenance"))); // HTTP 503: maintenance
console.log(handle(new TypeError("oops")));        // unexpected: oops

const wrapped = new HttpError(500, "db down", { cause: new Error("timeout") });
const cause = wrapped.cause; // unknown
console.log(String(wrapped), "| cause:", cause instanceof Error ? cause.message : cause);
// HttpError: db down | cause: timeout

Prüfe die spezifischste Klasse zuerst, da ein NotFoundError auch ein HttpError ist. Der Modifikator override ist hier optional, außer noImplicitOverride ist aktiv.

Ältere Anleitungen fügen jedem Fehlerkonstruktor Object.setPrototypeOf(this, new.target.prototype) hinzu. Das war nötig, als Klassen zu ES5-Funktionen herunterkompiliert wurden, wodurch instanceof bei Unterklassen von Error nicht mehr funktionierte. TypeScript 7 unterstützt target: "es5" nicht mehr (es meldet TS5108: Option 'target=ES5' has been removed), und mit ES2015 oder neuer funktioniert das native class ... extends Error, wie oben.

Das Result-Muster

TypeScript verfolgt nicht, welche Fehler eine Funktion werfen kann, also erinnert nichts Aufrufer daran, sie zu behandeln. Bei erwarteten Fehlschlägen (ungültige Eingabe, ein fehlender Datensatz) bringt ein Rückgabewert, der Erfolg oder Fehlschlag meldet, den Fehler ins Typsystem:

type Result<T, E = string> =
    | { ok: true; value: T }
    | { ok: false; error: E };

function parseAge(input: string): Result<number> {
    const n = Number(input);
    if (!Number.isInteger(n)) return { ok: false, error: `"${input}" is not a whole number` };
    if (n < 0 || n > 150) return { ok: false, error: `${n} is out of range` };
    return { ok: true, value: n };
}

for (const input of ["36", "abc", "200"]) {
    const r = parseAge(input);
    if (r.ok) {
        console.log("age:", r.value + 1); // r.value only exists when ok is true
    } else {
        console.log("error:", r.error);
    }
}
// age: 37
// error: "abc" is not a whole number
// error: 200 is out of range

r.value vor der Prüfung von r.ok zu lesen ist ein Compilerfehler, und genau darum geht es. Nimm Exceptions für das Unerwartete (Bugs, eine abgebrochene Verbindung) und Result-Werte für Ergebnisse, über die der Aufrufer entscheiden muss.

Fehler in asynchronem Code

Ein abgelehntes Promise wird beim await zu einem geworfenen Fehler, also funktioniert try/catch um await genauso, und die Variable ist wieder unknown. Der einzige Unterschied ist .catch() auf einem Promise: Dessen Callback-Parameter ist als any typisiert, nicht als unknown, annotiere ihn also selbst (.catch((e: unknown) => ...)). Beispiele stehen unter async/await.

Häufige Fehler

• e.message ohne Einengen lesen. Unter strict kompiliert es nicht; ohne strict bricht es, wenn etwas anderes als ein Error geworfen wird.
• Alles fangen und weitermachen. Behandle die Fehler, die du erwartest, und wirf den Rest erneut.
• name bei eigenen Fehlern vergessen. Dann steht in den Logs bei allen Error.
• Strings werfen. throw "failed" hat keinen Stacktrace und besteht keine Prüfung mit instanceof Error.