Try catch in TypeScript: tipi di errore ed errori personalizzati

TypeScript usa try, catch, finally e throw di JavaScript. La parte specifica di TypeScript è la variabile del catch: con strict attivo ha tipo unknown, quindi controlli cosa è stato lanciato prima di usarlo.

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

Il lato runtime (come si srotola lo stack, quali tipi di errore predefiniti esistono) è trattato in try/catch in JavaScript.

Perché la variabile del catch è unknown

JavaScript può lanciare qualsiasi cosa: un Error, una stringa, un numero, undefined, un oggetto di una libreria. TypeScript non può sapere quale, quindi con strict (il flag useUnknownInCatchVariables) la variabile è unknown e devi restringerla prima di 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'.

Senza strict, e è any e lo stesso codice compila, poi va storto a runtime quando viene lanciata una stringa: e.message è undefined, e qualsiasi cosa più profonda, come e.message.length, lancia un TypeError. Non puoi nemmeno cavartela con un'annotazione: catch (e: Error) è l'errore TS1196 (Catch clause variable type annotation must be 'any' or 'unknown' if specified).

Restringere l'errore

instanceof Error copre tutto ciò che è costruito su Error, compresi TypeError, SyntaxError, RangeError e le tue sottoclassi. Per tutto il resto, ripiega sulla conversione del valore in stringa. Un piccolo helper tiene brevi i punti di chiamata:

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 che gestisce solo alcuni errori deve rilanciare gli altri: if (!(e instanceof ValidationError)) throw e;. Ingoiare gli errori sconosciuti nasconde bug reali.

Lanciare errori

throw accetta qualsiasi espressione, e TypeScript non lo limita. Lancia comunque oggetti Error: portano con sé uno stack trace, e ogni controllo instanceof Error del codebase dipende da questo.

Una funzione che lancia sempre un errore ha tipo di ritorno never, che TypeScript usa per restringere dopo la chiamata:

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
}

Da ES2022, Error accetta un secondo argomento con una cause, che collega un errore di basso livello a quello che lanci: throw new Error("could not load settings", { cause: e }). Chi chiama può leggere err.cause (tipizzato unknown).

Classi di errore personalizzate

Una sottoclasse di Error permette a chi chiama di distinguere i fallimenti con instanceof e di portare dati extra. Imposta name, perché quello ereditato è "Error" e compare nei log e 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

Controlla per prima la classe più specifica, perché un NotFoundError è anche un HttpError. Il modificatore override qui è facoltativo, a meno che noImplicitOverride sia attivo.

Le guide più vecchie aggiungono Object.setPrototypeOf(this, new.target.prototype) a ogni costruttore di errore. Serviva quando le classi venivano compilate in funzioni ES5, dove instanceof si rompeva per le sottoclassi di Error. TypeScript 7 non supporta più target: "es5" (segnala TS5108: Option 'target=ES5' has been removed), e con ES2015 o successivi il nativo class ... extends Error funziona, come sopra.

Il pattern Result

TypeScript non tiene traccia degli errori che una funzione può lanciare, quindi nulla ricorda a chi chiama di gestirli. Per i fallimenti previsti (input non valido, un record mancante), restituire un valore che dice "successo o fallimento" porta l'errore dentro il sistema di tipi:

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

Leggere r.value prima di controllare r.ok è un errore di compilazione, ed è proprio questo lo scopo. Usa le eccezioni per l'imprevisto (bug, una connessione caduta) e i valori Result per gli esiti su cui chi chiama deve decidere.

Errori nel codice asincrono

Una promise rifiutata diventa un errore lanciato nel punto dell'await, quindi try/catch attorno ad await funziona allo stesso modo, e la variabile è di nuovo unknown. L'unica differenza è .catch() su una promise: il parametro della sua callback è tipizzato any, non unknown, quindi annotalo tu (.catch((e: unknown) => ...)). Vedi async/await per degli esempi.

Errori comuni

• Leggere e.message senza restringere. Con strict non compila; senza strict si rompe quando viene lanciato qualcosa che non è un Error.
• Catturare tutto e andare avanti. Gestisci gli errori che ti aspetti e rilancia gli altri.
• Dimenticare name negli errori personalizzati. I log diranno allora Error per tutti.
• Lanciare stringhe. throw "failed" non ha stack trace e non supera i controlli instanceof Error.