Try catch в TypeScript: типы ошибок и собственные ошибки

TypeScript использует try, catch, finally и throw из JavaScript. Особенность TypeScript в переменной catch: при включённом strict она имеет тип unknown, поэтому перед использованием нужно проверить, что было выброшено.

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

Сторона времени выполнения (как раскручивается стек, какие встроенные типы ошибок существуют) описана в разделе try/catch в JavaScript.

Почему переменная catch имеет тип unknown

JavaScript может выбросить что угодно: Error, строку, число, undefined, объект из библиотеки. TypeScript не может знать, что именно, поэтому при strict (флаг useUnknownInCatchVariables) переменная имеет тип unknown, и её нужно сузить перед использованием:

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

Без strict e имеет тип any, и тот же код компилируется, а затем ломается во время выполнения, когда выброшена строка: e.message равно undefined, а всё, что глубже, например e.message.length, выбрасывает TypeError. Выкрутиться аннотацией тоже нельзя: catch (e: Error) это ошибка TS1196 (Catch clause variable type annotation must be 'any' or 'unknown' if specified).

Сужение ошибки

instanceof Error покрывает всё, что построено на Error, включая TypeError, SyntaxError, RangeError и ваши собственные подклассы. Для всего остального остаётся преобразовать значение в строку. Небольшая вспомогательная функция сокращает места вызова:

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}

catch, который обрабатывает только часть ошибок, должен выбрасывать остальные дальше: if (!(e instanceof ValidationError)) throw e;. Проглатывание неизвестных ошибок скрывает настоящие баги.

Выбрасывание ошибок

throw принимает любое выражение, и TypeScript его не ограничивает. Всё равно выбрасывайте объекты Error: у них есть трассировка стека, и от этого зависит каждая проверка instanceof Error в кодовой базе.

Функция, которая всегда выбрасывает ошибку, имеет тип возврата never, и TypeScript использует его для сужения после вызова:

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
}

Начиная с ES2022 Error принимает второй аргумент с cause, который связывает низкоуровневую ошибку с той, которую выбрасываете вы: throw new Error("could not load settings", { cause: e }). Вызывающий код может прочитать err.cause (тип unknown).

Собственные классы ошибок

Подкласс Error позволяет вызывающему коду различать сбои через instanceof и нести дополнительные данные. Задавайте name, потому что унаследованное значение это "Error", и оно видно в логах и в 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

Сначала проверяйте самый конкретный класс, поскольку NotFoundError это ещё и HttpError. Модификатор override здесь необязателен, если не включён noImplicitOverride.

Старые руководства добавляют Object.setPrototypeOf(this, new.target.prototype) в каждый конструктор ошибки. Это было нужно при компиляции классов в функции ES5, где instanceof ломался для подклассов Error. TypeScript 7 больше не поддерживает target: "es5" (он сообщает TS5108: Option 'target=ES5' has been removed), а с ES2015 и новее нативный class ... extends Error работает, как показано выше.

Приём Result

TypeScript не отслеживает, какие ошибки может выбросить функция, поэтому ничто не напоминает вызывающему коду их обработать. Для ожидаемых сбоев (неверный ввод, отсутствующая запись) возврат значения, которое говорит «успех или неудача», вводит ошибку в систему типов:

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 до проверки r.ok это ошибка компиляции, и в этом весь смысл. Используйте исключения для неожиданного (баги, оборванное соединение), а значения Result для исходов, о которых должен принять решение вызывающий код.

Ошибки в асинхронном коде

Отклонённый промис становится выброшенной ошибкой в месте await, поэтому try/catch вокруг await работает так же, и переменная снова имеет тип unknown. Единственное отличие это .catch() у промиса: параметр его колбэка типизирован как any, а не unknown, так что аннотируйте его сами (.catch((e: unknown) => ...)). Примеры см. в разделе async/await.

Частые ошибки

• Читать e.message без сужения. При strict это не компилируется; без strict ломается, когда выброшено не Error.
• Ловить всё и продолжать. Обрабатывайте ожидаемые ошибки, а остальные выбрасывайте дальше.
• Забыть name у собственных ошибок. Тогда в логах у всех будет Error.
• Выбрасывать строки. У throw "failed" нет трассировки стека, и он не проходит проверки instanceof Error.