Try catch en TypeScript : types d'erreur et erreurs personnalisées

TypeScript utilise les try, catch, finally et throw de JavaScript. Ce qui est propre à TypeScript, c'est la variable du catch : avec strict activé, elle a le type unknown, donc vous vérifiez ce qui a été levé avant de l'utiliser.

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

Le côté exécution (comment la pile se déroule, quels types d'erreur intégrés existent) est présenté dans try/catch en JavaScript.

Pourquoi la variable du catch est unknown

JavaScript peut lever n'importe quoi : une Error, une chaîne, un nombre, undefined, un objet venant d'une bibliothèque. TypeScript ne peut pas savoir lequel, donc sous strict (l'option useUnknownInCatchVariables) la variable est unknown et vous devez restreindre son type avant de l'utiliser :

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

Sans strict, e est any et le même code compile, puis se passe mal à l'exécution quand une chaîne est levée : e.message vaut undefined, et tout accès plus profond, comme e.message.length, lève une TypeError. Une annotation ne vous tire pas d'affaire non plus : catch (e: Error) provoque l'erreur TS1196 (Catch clause variable type annotation must be 'any' or 'unknown' if specified).

Restreindre le type de l'erreur

instanceof Error couvre tout ce qui est construit sur Error, y compris TypeError, SyntaxError, RangeError et vos propres sous-classes. Pour le reste, convertissez la valeur en chaîne. Une petite fonction utilitaire garde les appels courts :

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 qui ne gère qu'une partie des erreurs doit relancer les autres : if (!(e instanceof ValidationError)) throw e;. Avaler les erreurs inconnues cache de vrais bugs.

Lever des erreurs

throw accepte n'importe quelle expression, et TypeScript ne le restreint pas. Levez tout de même des objets Error : ils portent une trace de pile, et chaque test instanceof Error du code en dépend.

Une fonction qui lève toujours une exception a le type de retour never, que TypeScript utilise pour restreindre les types après l'appel :

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
}

Depuis ES2022, Error accepte un second argument avec une cause, qui relie une erreur de bas niveau à celle que vous levez : throw new Error("could not load settings", { cause: e }). L'appelant peut lire err.cause (typé unknown).

Classes d'erreur personnalisées

Une sous-classe d'Error permet aux appelants de distinguer les échecs avec instanceof et de transporter des données supplémentaires. Définissez name, car celui hérité vaut "Error" et il apparaît dans les logs et dans 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

Testez d'abord la classe la plus spécifique, puisqu'une NotFoundError est aussi une HttpError. Le modificateur override est facultatif ici, sauf si noImplicitOverride est activé.

Les anciens guides ajoutent Object.setPrototypeOf(this, new.target.prototype) dans chaque constructeur d'erreur. C'était nécessaire quand les classes étaient compilées en fonctions ES5, où instanceof ne fonctionnait plus pour les sous-classes d'Error. TypeScript 7 ne prend plus en charge target: "es5" (il signale TS5108: Option 'target=ES5' has been removed), et avec ES2015 ou plus le class ... extends Error natif fonctionne, comme ci-dessus.

Le pattern Result

TypeScript ne suit pas les erreurs qu'une fonction peut lever, donc rien ne rappelle aux appelants de les gérer. Pour les échecs prévus (une saisie invalide, un enregistrement absent), renvoyer une valeur qui dit « succès ou échec » fait entrer l'erreur dans le système de types :

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

Lire r.value avant de tester r.ok est une erreur de compilation, et c'est tout l'intérêt. Utilisez les exceptions pour l'imprévu (bugs, connexion coupée) et les valeurs Result pour les issues sur lesquelles l'appelant doit décider.

Les erreurs dans le code asynchrone

Une promesse rejetée devient une erreur levée au niveau du await, donc un try/catch autour de await fonctionne de la même façon, et la variable est là aussi unknown. La seule différence concerne .catch() sur une promesse : le paramètre de son callback est typé any, pas unknown, donc annotez-le vous-même (.catch((e: unknown) => ...)). Voir async/await pour des exemples.

Erreurs courantes

• Lire e.message sans restreindre le type. Sous strict, cela ne compile pas ; sans strict, cela casse quand ce qui est levé n'est pas une Error.
• Tout capturer et continuer. Gérez les erreurs que vous attendez et relancez les autres.
• Oublier name sur les erreurs personnalisées. Les logs affichent alors Error pour toutes.
• Lever des chaînes. throw "failed" n'a pas de trace de pile et échoue aux tests instanceof Error.