switch case في TypeScript: التضييق والفحص الشامل

جملة switch في TypeScript هي switch في JavaScript مع فحص الأنواع. تقارن قيمة مع كل case بـ ===، وتنفّذ الفرع المطابق، وتتوقف عند break أو return. وتضيّق TypeScript القيمة المفحوصة داخل كل حالة، ويمكنها التحقق من معالجة كل قيمة ممكنة.

type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";

function describe(day: Weekday): string {
    switch (day) {
        case "sat":
        case "sun":
            return "weekend";
        case "fri":
            return "almost weekend";
        default:
            return "workday";
    }
}

console.log(describe("sun")); // weekend
console.log(describe("fri")); // almost weekend
console.log(describe("tue")); // workday

التسميات المكدسة (case "sat": case "sun":) تشترك في فرع واحد. وينهي return الدالة، فلا حاجة إلى break بعده.

الصياغة

switch (expression) {
    case value1:
        // runs when expression === value1
        break;
    case value2:
    case value3:
        // runs for value2 or value3
        break;
    default:
        // runs when nothing else matched
}

• تستخدم المطابقة المساواة الصارمة ===: الحالة case 1 لا تطابق النص "1".
• دون break أو return أو throw يستمر التنفيذ إلى الحالة التالية (fallthrough).
• default اختياري ويمكن وضعه في أي مكان، وإن كان المعتاد وضعه في النهاية.
• قيمة case تستطيع TypeScript إثبات أنها لا تطابق أبدًا هي الخطأ TS2678. لمعامل نوعه "a" | "b" تبلّغ case "c": الرسالة Type '"c"' is not comparable to type '"a" | "b"'.، وهذا يلتقط الأخطاء الإملائية في تسميات الحالات.

التضييق داخل كل حالة

في كل case تعرف TypeScript أي قيمة طابقت وتضيّق النوع. وهذا أكثر فائدة مع discriminated union: استخدم خاصية الوسم المشتركة في switch، فترى كل حالة المتغير المطابق بخصائصه الخاصة.

type Shape =
    | { kind: "circle"; radius: number }
    | { kind: "rect"; width: number; height: number }
    | { kind: "square"; side: number };

function area(shape: Shape): number {
    switch (shape.kind) {
        case "circle":
            return Math.PI * shape.radius ** 2; // shape: circle variant
        case "rect":
            return shape.width * shape.height;  // shape: rect variant
        case "square":
            return shape.side ** 2;             // shape: square variant
    }
}

console.log(area({ kind: "circle", radius: 1 }).toFixed(2)); // 3.14
console.log(area({ kind: "rect", width: 2, height: 3 }));    // 6
console.log(area({ kind: "square", side: 4 }));              // 16

لا يُترجم shape.radius إلا في حالة "circle". وخارجها قد يكون shape مستطيلًا لا يملك radius. لا يوجد default، ومع ذلك تجتاز الدالة فحص الأنواع على أنها تعيد number، لأن TypeScript ترى أن الحالات الثلاث تغطي كل قيم kind. وتجد أنماطًا أخرى مبنية على ذلك في صفحة discriminated unions.

switch شامل مع never

تتوقف الدالة السابقة عن الترجمة إذا أُضيف شكل رابع دون حالة له (TS2366، قيمة مُعادة مفقودة). لكن هذا يعمل فقط عندما تعيد الدالة قيمة. ولضمان يعمل أيضًا في كود void ويعطي رسالة أوضح، أضف default يسند القيمة إلى never:

// This does not compile: the "triangle" case is missing.
type Shape =
    | { kind: "circle"; radius: number }
    | { kind: "square"; side: number }
    | { kind: "triangle"; base: number; height: number };

function area(shape: Shape): number {
    switch (shape.kind) {
        case "circle":
            return Math.PI * shape.radius ** 2;
        case "square":
            return shape.side ** 2;
        default: {
            const unreachable: never = shape;
            throw new Error(`Unknown shape: ${JSON.stringify(unreachable)}`);
        }
    }
}

console.log(area({ kind: "square", side: 3 }));

index.ts(14,19): error TS2322: Type '{ kind: "triangle"; base: number; height: number; }' is not assignable to type 'never'.

بعد الحالات المعالَجة، النوع الوحيد المتبقي لـ shape هو متغير المثلث، ولا يمكن إسناده إلى never. والخطأ يسمّي بالضبط ما هو مفقود. أضف case "triangle": return (shape.base * shape.height) / 2; فيرى default النوع never، ويُترجم الكود ويطبع 9. وما زال throw يحمي من البيانات الخاطئة وقت التشغيل، مثل kind قادم من JSON لم تتوقعه الأنواع.

كثير من المشاريع تغلّف الفحص في دالة مساعدة:

function assertNever(value: never): never {
    throw new Error(`Unhandled value: ${JSON.stringify(value)}`);
}

type Status = "idle" | "loading" | "done";

function label(status: Status): string {
    switch (status) {
        case "idle": return "Waiting";
        case "loading": return "Loading...";
        case "done": return "Finished";
        default: return assertNever(status);
    }
}

console.log(label("loading")); // Loading...

والتقنية نفسها تعمل مع enums: استخدم قيمة الـ enum في switch ومرّرها إلى assertNever في default.

switch (true) للنطاقات والشروط

يقارن switch القيم، فالنطاقات تحتاج إلى حيلة: استخدم true في switch واكتب شرطًا في كل case. ومنذ TypeScript 5.3 تضيّق هذه الشروط الأنواع كما تفعل جمل if.

function grade(score: number): string {
    switch (true) {
        case score >= 90: return "A";
        case score >= 80: return "B";
        case score >= 70: return "C";
        default: return "F";
    }
}

function format(value: string | number | boolean): string {
    switch (true) {
        case typeof value === "string":
            return value.toUpperCase();   // value: string
        case typeof value === "number":
            return value.toFixed(2);      // value: number
        default:
            return value ? "yes" : "no";  // value: boolean
    }
}

console.log(grade(85), grade(42));                     // B F
console.log(format("hi"), format(3.14159), format(true)); // HI 3.14 yes

تُختبر الحالات بالترتيب، فضع الأكثر تحديدًا أولًا. أما هل يُقرأ هذا أفضل من if / else if فمسألة ذوق؛ السلوك واحد.

الانتقال إلى الحالة التالية وbreak

الحالة التي فيها كود دون break أو return أو throw تنتقل إلى الحالة التالية. وهذا خطأ برمجي في أغلب الأحيان. خيار المترجم noFallthroughCasesInSwitch (ليس جزءًا من strict) يحوّله إلى الخطأ TS7029، Fallthrough case in switch.، مع السماح بالتسميات الفارغة المكدسة.

function permissions(role: "admin" | "editor" | "viewer"): string[] {
    const result: string[] = [];
    switch (role) {
        case "admin":
            result.push("delete");
        // intentional fallthrough: admins can also edit
        case "editor":
            result.push("edit");
        // intentional fallthrough: editors can also view
        case "viewer":
            result.push("view");
    }
    return result;
}

console.log(permissions("admin"));  // [ 'delete', 'edit', 'view' ]
console.log(permissions("viewer")); // [ 'view' ]

الانتقال المقصود بهذا الشكل يعمل، لكن مع تفعيل noFallthroughCasesInSwitch يجب إعادة كتابته، مثلًا بفحوص if منفصلة. وهذا عادةً أوضح على أي حال.

المتغيرات داخل الحالات

جسم switch كله كتلة واحدة، فالـ const المعرّف في حالة يكون مرئيًا في الحالات الأخرى (وإعادة تعريفه خطأ). ضع الحالة بين أقواس معقوصة لتعطيها نطاقها الخاص:

function price(item: "tea" | "cake", qty: number): number {
    switch (item) {
        case "tea": {
            const unit = 2.5;
            return unit * qty;
        }
        case "cake": {
            const unit = 4; // fine: a different block
            return unit * qty;
        }
    }
}

console.log(price("tea", 2), price("cake", 3)); // 5 12

دون الأقواس يكون const unit الثاني خطأ الترجمة TS2451، Cannot redeclare block-scoped variable 'unit'.

switch أم البحث في كائن

عندما تحوّل كل حالة قيمة إلى قيمة أخرى فقط، يكون الكائن المعرّف بنوع Record أقصر، وتتحقق TypeScript من وجود كل مفتاح:

type Level = "debug" | "info" | "warn" | "error";

const icons: Record<Level, string> = {
    debug: "[D]",
    info: "[I]",
    warn: "[W]",
    error: "[E]",
};

console.log(icons.warn, icons["error"]); // [W] [E]

حذف مفتاح خطأ ترجمة، وهذا يعطي الشمولية نفسها التي يعطيها فحص never. واحتفظ بـ switch للحالات التي تنفّذ منطقًا مختلفًا، أو تضيّق متغيرات union، أو تعود مبكرًا.