Try catch en TypeScript: tipos de error y errores personalizados

TypeScript usa try, catch, finally y throw de JavaScript. La parte específica de TypeScript es la variable de catch: con strict activado, tiene tipo unknown, así que compruebas qué se lanzó antes de usarla.

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

La parte de ejecución (cómo se deshace la pila, qué tipos de error integrados existen) se explica en try/catch en JavaScript.

Por qué la variable de catch es unknown

JavaScript puede lanzar cualquier cosa: un Error, un string, un número, undefined, un objeto de una librería. TypeScript no puede saber cuál, así que con strict (la opción useUnknownInCatchVariables) la variable es unknown y debes estrecharla antes de usarla:

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

Sin strict, e es any y el mismo código compila, pero falla en tiempo de ejecución cuando se lanza un string: e.message es undefined, y cualquier cosa más profunda, como e.message.length, lanza un TypeError. Tampoco puedes arreglarlo con una anotación: catch (e: Error) es el error TS1196 (Catch clause variable type annotation must be 'any' or 'unknown' if specified).

Estrechar el error

instanceof Error cubre todo lo que se basa en Error, incluidos TypeError, SyntaxError, RangeError y tus propias subclases. Para cualquier otra cosa, recurre a convertir el valor en un string. Una pequeña función auxiliar mantiene cortas las llamadas:

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}

Un catch que solo maneja algunos errores debe volver a lanzar el resto: if (!(e instanceof ValidationError)) throw e;. Tragarse errores desconocidos oculta bugs reales.

Lanzar errores

throw acepta cualquier expresión, y TypeScript no lo restringe. Aun así, lanza objetos Error: llevan una traza de la pila, y todas las comprobaciones instanceof Error del código dependen de ello.

Una función que siempre lanza un error tiene el tipo de retorno never, que TypeScript usa para estrechar después de la llamada:

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 ES2022, Error admite un segundo argumento con un cause, que encadena un error de bajo nivel al que lanzas: throw new Error("could not load settings", { cause: e }). Quien llama puede leer err.cause (de tipo unknown).

Clases de error propias

Una subclase de Error permite a quien llama distinguir los fallos con instanceof y llevar datos extra. Asigna name, porque el heredado es "Error" y aparece en los logs y en 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

Comprueba primero la clase más específica, ya que un NotFoundError también es un HttpError. El modificador override es opcional aquí salvo que noImplicitOverride esté activado.

Las guías antiguas añaden Object.setPrototypeOf(this, new.target.prototype) en cada constructor de error. Eso hacía falta al compilar las clases a funciones de ES5, donde instanceof fallaba con las subclases de Error. TypeScript 7 ya no admite target: "es5" (informa TS5108: Option 'target=ES5' has been removed), y con ES2015 o posterior el class ... extends Error nativo funciona, como arriba.

El patrón Result

TypeScript no registra qué errores puede lanzar una función, así que nada le recuerda a quien llama que debe manejarlos. Para los fallos esperados (una entrada inválida, un registro que no existe), devolver un valor que diga «éxito o fallo» mete el error en el 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

Leer r.value antes de comprobar r.ok es un error de compilación, y esa es la idea. Usa excepciones para lo inesperado (bugs, una conexión caída) y valores Result para los resultados sobre los que quien llama debe decidir.

Errores en código asíncrono

Una promesa rechazada se convierte en un error lanzado en el await, así que un try/catch alrededor de await funciona igual, y la variable vuelve a ser unknown. La única diferencia es .catch() sobre una promesa: el parámetro de su callback tiene tipo any, no unknown, así que anótalo tú (.catch((e: unknown) => ...)). Consulta async/await para ver ejemplos.

Errores habituales

• Leer e.message sin estrechar. Con strict no compila; sin strict falla cuando se lanza algo que no es un Error.
• Capturarlo todo y seguir. Maneja los errores que esperas y vuelve a lanzar el resto.
• Olvidar name en los errores propios. Entonces los logs dicen Error para todos.
• Lanzar strings. throw "failed" no tiene traza de la pila y no pasa las comprobaciones instanceof Error.