Try Catch في TypeScript: أنواع الأخطاء والأخطاء المخصصة

يستخدم TypeScript كلمات JavaScript نفسها: try وcatch وfinally وthrow. الجزء الخاص بـ 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");
}

جانب وقت التشغيل (كيف يُفك المكدس، وما أنواع الأخطاء المدمجة الموجودة) مشروح في 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: فهي تحمل تتبع المكدس، وكل فحص 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: معامل دالتها نوعه any لا unknown، لذلك حدد نوعه بنفسك (.catch((e: unknown) => ...)). راجع async/await لأمثلة.

أخطاء شائعة

• قراءة e.message دون تضييق. مع strict لا يُترجم الكود؛ ودونه يتعطل عند رمي قيم ليست Error.
• التقاط كل شيء والاستمرار. عالج الأخطاء التي تتوقعها وأعد رمي البقية.
• نسيان name في الأخطاء المخصصة. عندها تقول السجلات Error لكل الأخطاء.
• رمي النصوص. throw "failed" ليس فيه تتبع للمكدس ويفشل في فحوص instanceof Error.