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

הצד של זמן הריצה (איך ה-stack נפרם, אילו טיפוסי שגיאה מובנים קיימים) מוסבר ב-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: יש להם stack trace, וכל בדיקת 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 לתוצאות שהקורא חייב להחליט לגביהן.

שגיאות בקוד אסינכרוני

promise שנדחה הופך לשגיאה שנזרקת ב-await, ולכן try/catch סביב await עובד באותה צורה, והמשתנה שוב unknown. ההבדל היחיד הוא .catch() על promise: לפרמטר של ה-callback שלו יש את הטיפוס any, לא unknown, אז תנו לו הערת טיפוס בעצמכם (.catch((e: unknown) => ...)). ראו async/await לדוגמאות.

טעויות נפוצות

• קריאה של e.message בלי צמצום. תחת strict זה לא עובר קומפילציה; בלי strict זה נשבר כשנזרק משהו שאינו Error.
• לתפוס הכול ולהמשיך. טפלו בשגיאות שאתם מצפים להן וזרקו מחדש את השאר.
• לשכוח את name בשגיאות מותאמות. אז בלוגים כתוב Error על כולן.
• זריקת מחרוזות. ל-throw "failed" אין stack trace, והוא נכשל בבדיקות instanceof Error.