Try catch w TypeScript: typy błędów i własne klasy błędów

TypeScript korzysta z try, catch, finally i throw z JavaScriptu. Specyficzna dla TypeScriptu jest zmienna w catch: przy włączonym strict ma typ unknown, więc przed jej użyciem sprawdzasz, co zostało rzucone.

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");
}

Część dotycząca działania programu (jak rozwija się stos, jakie są wbudowane typy błędów) jest opisana na stronie try/catch w JavaScripcie.

Dlaczego zmienna w catch ma typ unknown

JavaScript może rzucić wszystko: Error, string, liczbę, undefined, obiekt z biblioteki. TypeScript nie może wiedzieć, co dokładnie, więc przy strict (opcja useUnknownInCatchVariables) zmienna ma typ unknown i przed użyciem trzeba ją zawęzić:

// 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'.

Bez strict zmienna e ma typ any i ten sam kod się kompiluje, ale psuje się w czasie działania, gdy zostanie rzucony string: e.message jest wtedy undefined, a wszystko głębiej, na przykład e.message.length, rzuca TypeError. Adnotacja typu też tu nie pomoże: catch (e: Error) to błąd TS1196 (Catch clause variable type annotation must be 'any' or 'unknown' if specified).

Zawężanie błędu

instanceof Error obejmuje wszystko, co jest zbudowane na Error, w tym TypeError, SyntaxError, RangeError i twoje własne podklasy. W pozostałych przypadkach zamień wartość na string. Mała funkcja pomocnicza skraca kod w miejscach wywołania:

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}

Blok catch, który obsługuje tylko niektóre błędy, powinien rzucić resztę dalej: if (!(e instanceof ValidationError)) throw e;. Połykanie nieznanych błędów ukrywa prawdziwe bugi.

Rzucanie błędów

throw przyjmuje dowolne wyrażenie i TypeScript tego nie ogranicza. Mimo to rzucaj obiekty Error: mają ślad stosu, a każde sprawdzenie instanceof Error w kodzie od tego zależy.

Funkcja, która zawsze rzuca błąd, ma typ zwracany never, a TypeScript wykorzystuje go do zawężania po jej wywołaniu:

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
}

Od ES2022 Error przyjmuje drugi argument z polem cause, które łączy błąd niskiego poziomu z tym, który rzucasz: throw new Error("could not load settings", { cause: e }). Wywołujący może odczytać err.cause (typ unknown).

Własne klasy błędów

Podklasa Error pozwala wywołującym rozróżniać porażki przez instanceof i przenosić dodatkowe dane. Ustaw name, bo odziedziczona wartość to "Error", a pojawia się ona w logach i w 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

Najpierw sprawdzaj najbardziej szczegółową klasę, bo NotFoundError jest też HttpError. Modyfikator override jest tu opcjonalny, chyba że włączone jest noImplicitOverride.

Starsze poradniki dodają Object.setPrototypeOf(this, new.target.prototype) do każdego konstruktora błędu. Było to potrzebne przy kompilowaniu klas do funkcji ES5, gdzie instanceof nie działał dla podklas Error. TypeScript 7 nie obsługuje już target: "es5" (zgłasza TS5108: Option 'target=ES5' has been removed), a przy ES2015 i nowszych natywne class ... extends Error działa, tak jak powyżej.

Wzorzec Result

TypeScript nie śledzi, jakie błędy może rzucić funkcja, więc nic nie przypomina wywołującym o ich obsłudze. Dla porażek, których się spodziewasz (błędne dane wejściowe, brakujący rekord), zwracanie wartości mówiącej „sukces albo porażka” wprowadza błąd do systemu typów:

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

Odczytanie r.value przed sprawdzeniem r.ok to błąd kompilacji i właśnie o to chodzi. Wyjątków używaj dla rzeczy nieoczekiwanych (bugi, zerwane połączenie), a wartości Result dla wyników, o których musi zdecydować wywołujący.

Błędy w kodzie asynchronicznym

Odrzucona obietnica staje się rzuconym błędem w miejscu await, więc try/catch wokół await działa tak samo, a zmienna znowu ma typ unknown. Jedyna różnica to .catch() na obietnicy: parametr jego callbacku ma typ any, a nie unknown, więc dodaj adnotację samodzielnie (.catch((e: unknown) => ...)). Przykłady znajdziesz na stronie o async/await.

Częste błędy

• Odczytywanie e.message bez zawężenia. Przy strict to się nie kompiluje; bez strict psuje się, gdy rzucone zostanie coś innego niż Error.
• Łapanie wszystkiego i kontynuowanie. Obsługuj błędy, których się spodziewasz, a resztę rzucaj dalej.
• Brak name we własnych błędach. Wtedy logi pokazują Error dla każdego z nich.
• Rzucanie stringów. throw "failed" nie ma śladu stosu i nie przechodzi sprawdzeń instanceof Error.