Try catch em TypeScript: tipos de erro e erros personalizados

O TypeScript usa o try, catch, finally e throw do JavaScript. A parte específica do TypeScript é a variável do catch: com strict ligado, ela tem o tipo unknown, então você verifica o que foi lançado antes de usá-la.

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

O lado de tempo de execução (como a pilha é desfeita, quais tipos de erro embutidos existem) é coberto em try/catch em JavaScript.

Por que a variável do catch é unknown

O JavaScript pode lançar qualquer coisa: um Error, uma string, um número, undefined, um objeto de uma biblioteca. O TypeScript não tem como saber qual, então com strict (a flag useUnknownInCatchVariables) a variável é unknown e você precisa estreitá-la antes de usar:

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

Sem strict, e é any e o mesmo código compila, mas dá errado em tempo de execução quando uma string é lançada: e.message é undefined, e qualquer coisa mais profunda, como e.message.length, lança um TypeError. Também não dá para resolver com uma anotação: catch (e: Error) dá o erro TS1196 (Catch clause variable type annotation must be 'any' or 'unknown' if specified).

Estreitando o erro

instanceof Error cobre tudo o que é construído sobre Error, incluindo TypeError, SyntaxError, RangeError e as suas próprias subclasses. Para qualquer outra coisa, converta o valor para string como alternativa. Um pequeno helper deixa os pontos de chamada curtos:

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}

Um catch que trata só alguns erros deve relançar o resto: if (!(e instanceof ValidationError)) throw e;. Engolir erros desconhecidos esconde bugs reais.

Lançando erros

throw aceita qualquer expressão, e o TypeScript não a restringe. Lance objetos Error mesmo assim: eles carregam um stack trace, e toda verificação instanceof Error do código depende disso.

Uma função que sempre lança um erro tem o tipo de retorno never, que o TypeScript usa para estreitar depois da chamada:

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
}

Desde o ES2022, Error recebe um segundo argumento com um cause, que encadeia um erro de baixo nível ao que você lança: throw new Error("could not load settings", { cause: e }). Quem chama pode ler err.cause (tipado como unknown).

Classes de erro personalizadas

Uma subclasse de Error permite que quem chama diferencie falhas com instanceof e carregue dados extras. Defina name, porque o herdado é "Error" e ele aparece nos logs e em 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

Verifique primeiro a classe mais específica, já que um NotFoundError também é um HttpError. O modificador override é opcional aqui, a menos que noImplicitOverride esteja ligado.

Guias mais antigos adicionam Object.setPrototypeOf(this, new.target.prototype) a todo construtor de erro. Isso era necessário ao compilar classes para funções ES5, em que instanceof quebrava para subclasses de Error. O TypeScript 7 não suporta mais target: "es5" (ele reporta TS5108: Option 'target=ES5' has been removed), e com ES2015 ou posterior o class ... extends Error nativo funciona, como acima.

O padrão Result

O TypeScript não rastreia quais erros uma função pode lançar, então nada lembra quem chama de tratá-los. Para falhas esperadas (entrada inválida, um registro inexistente), retornar um valor que diz "sucesso ou falha" coloca o erro dentro do sistema de tipos:

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

Ler r.value antes de verificar r.ok é erro de compilação, e essa é a ideia. Use exceções para o inesperado (bugs, uma conexão caída) e valores Result para desfechos sobre os quais quem chama precisa decidir.

Erros em código assíncrono

Uma promise rejeitada vira um erro lançado no await, então try/catch em volta de await funciona do mesmo jeito, e a variável é de novo unknown. A única diferença é o .catch() de uma promise: o parâmetro do callback dele é tipado como any, não unknown, então anote-o você mesmo (.catch((e: unknown) => ...)). Veja async/await para exemplos.

Erros comuns

• Ler e.message sem estreitar. Com strict não compila; sem strict, quebra quando algo que não é Error é lançado.
• Capturar tudo e seguir em frente. Trate os erros que você espera e relance o resto.
• Esquecer name nos erros personalizados. Aí os logs dizem Error para todos eles.
• Lançar strings. throw "failed" não tem stack trace e falha nas verificações instanceof Error.