Enum في TypeScript: الأنواع الرقمية والنصية وconst enum

الـ enum في TypeScript مجموعة مسماة من الثوابت. ينشئ enum Direction { Up, Down, Left, Right } نوعًا هو Direction، وكائنًا وقت التشغيل تصل إلى أعضائه بـ Direction.Up. تُرقَّم الأعضاء بدءًا من 0 ما لم تعطها قيمًا، وتعطي enums النصية كل عضو نصًا مقروءًا.

enum Direction {
    Up,    // 0
    Down,  // 1
    Left,  // 2
    Right, // 3
}

enum Status {
    Active = "ACTIVE",
    Inactive = "INACTIVE",
}

function move(dir: Direction): string {
    return `moving ${Direction[dir]} (${dir})`;
}

console.log(move(Direction.Left)); // moving Left (2)
console.log(Status.Active);        // ACTIVE

let current: Status = Status.Inactive;
console.log(current === Status.Inactive); // true

الـ enums من الميزات القليلة في TypeScript التي ليست مجرد أنواع: يصبح الـ enum كائن JavaScript حقيقيًا عند ترجمة الكود.

Enums الرقمية

دون قيم ابتدائية تحصل الأعضاء على 0 و1 و2 وهكذا. أعطِ العضو الأول رقمًا فتكمل البقية منه. ويمكنك أيضًا ضبط كل قيمة صراحة، وهذا الخيار الآمن عندما تُخزَّن الأرقام في قاعدة بيانات أو تُرسل عبر الشبكة.

enum Priority {
    Low = 1,
    Medium, // 2
    High,   // 3
}

enum HttpStatus {
    Ok = 200,
    NotFound = 404,
    ServerError = 500,
}

// Bit flags: combine members with |, test with &
enum Permission {
    None = 0,
    Read = 1 << 0,  // 1
    Write = 1 << 1, // 2
    Delete = 1 << 2, // 4
    All = Read | Write | Delete, // 7
}

console.log(Priority.High, HttpStatus.NotFound); // 3 404

const mine = Permission.Read | Permission.Write;
console.log(mine, (mine & Permission.Write) !== 0, (mine & Permission.Delete) !== 0); // 3 true false

الاعتماد على الترقيم التلقائي مناسب للقيم التي لا تغادر البرنامج أبدًا. أما إذا قد يتغير ترتيب الأعضاء والأرقام محفوظة في أي مكان، فإن إدراج عضو في المنتصف يعيد ترقيم كل ما بعده بصمت.

ما الذي يُترجم إليه الـ enum

تُمحى الأنواع، لكن الـ enum لا يُمحى. هذا هو كود JavaScript الذي تنتجه TypeScript لـ enum رقمي وآخر نصي:

enum Direction { Up, Down, Left, Right }
enum Status { Active = "ACTIVE", Inactive = "INACTIVE" }

var Direction;
(function (Direction) {
    Direction[Direction["Up"] = 0] = "Up";
    Direction[Direction["Down"] = 1] = "Down";
    Direction[Direction["Left"] = 2] = "Left";
    Direction[Direction["Right"] = 3] = "Right";
})(Direction || (Direction = {}));
var Status;
(function (Status) {
    Status["Active"] = "ACTIVE";
    Status["Inactive"] = "INACTIVE";
})(Status || (Status = {}));

يعيد Direction["Up"] = 0 القيمة 0، لذلك يُضبط Direction[0] = "Up" في الجملة نفسها. وهكذا يربط enum الرقمي في الاتجاهين: من الاسم إلى الرقم ومن الرقم إلى الاسم. هذا هو التعيين العكسي (reverse mapping). أما enums النصية فتربط الأسماء بالقيم فقط.

enum Direction { Up, Down, Left, Right }
enum Status { Active = "ACTIVE", Inactive = "INACTIVE" }

console.log(Direction);
console.log(Direction[2]);    // Left: number to name
console.log(Direction.Left);  // 2: name to number
console.log(Status);          // { Active: 'ACTIVE', Inactive: 'INACTIVE' }

للكائن Direction المطبوع ثمانية مفاتيح: الأسماء الأربعة والأرقام الأربعة. وهذا يهم بمجرد أن تكرر عليه.

Enums النصية

كل عضو في enum نصي يحتاج إلى قيمة نصية صريحة. تظهر القيم كما هي في السجلات وJSON وقواعد البيانات، ما يجعل enums النصية أسهل في التصحيح من الأرقام.

للـ enum النصي طبيعة اسمية (nominal) بطريقة تفاجئ الناس: لا يمكن إسناد نص عادي إليه، حتى عندما يطابق النص قيمة أحد الأعضاء.

// This does not compile: "ACTIVE" is a string, not a Status.
enum Status {
    Active = "ACTIVE",
    Inactive = "INACTIVE",
}

let current: Status = "ACTIVE";
console.log(current);

index.ts(7,5): error TS2820: Type '"ACTIVE"' is not assignable to type 'Status'. Did you mean 'Status.Inactive'?

(الاقتراح في الرسالة تخمين من المترجم وهو خاطئ هنا؛ الحل هو Status.Active.) وفي الاتجاه الآخر، يمكن استخدام قيمة Status حيثما يُتوقع string. وعندما تصل القيم كنصوص، من JSON أو نموذج، حوّلها بفحص مثل الموجود في قسم فحص القيم أدناه.

استخدام enum كنوع

اسم الـ enum نوع قيمه هي أعضاؤه. ومع switch تتحقق TypeScript من معالجة كل عضو عندما يجب أن تعيد الدالة قيمة:

enum Shape { Circle = "circle", Square = "square", Triangle = "triangle" }

function sides(shape: Shape): number {
    switch (shape) {
        case Shape.Circle: return 0;
        case Shape.Square: return 4;
        case Shape.Triangle: return 3;
    }
}

console.log(sides(Shape.Square)); // 4

// Numeric enums accept any number, not only member values:
enum Level { Low, High }
const fromDb: number = 57;
const level: Level = fromDb; // compiles
console.log(level);           // 57

إذا أُضيف عضو جديد إلى Shape دون case جديد، يتوقف sides عن الترجمة بالخطأ TS2366، Function lacks ending return statement and return type does not include 'undefined'. وتعرض صفحة switch الفحص الشامل الأكثر صرامة المبني على never.

تُظهر الأسطر الأخيرة ضعفًا حقيقيًا في enums الرقمية. الرقم الحرفي الذي لا يطابق أي عضو، const level: Level = 99، خطأ ترجمة (TS2322)، لكن أي قيمة نوعها number تُقبل، فيمر 57. أما enums النصية فليس فيها هذه الثغرة.

التكرار على enum

الـ enum كائن وقت التشغيل، لذلك تعمل Object.keys وObject.values وObject.entries. في enum النصي تعيد الأعضاء بالضبط. وفي enum الرقمي تعيد أيضًا مدخلات التعيين العكسي، التي تستبعدها:

enum Status { Active = "ACTIVE", Inactive = "INACTIVE", Banned = "BANNED" }
enum Direction { Up, Down, Left, Right }

console.log(Object.keys(Status));   // [ 'Active', 'Inactive', 'Banned' ]
console.log(Object.values(Status)); // [ 'ACTIVE', 'INACTIVE', 'BANNED' ]

for (const [name, value] of Object.entries(Status)) {
    console.log(`${name} = ${value}`);
}

// Numeric enum: keys include "0", "1", ... from the reverse mapping
const names = Object.keys(Direction).filter((k) => isNaN(Number(k)));
const values = Object.values(Direction).filter((v) => typeof v === "number");
console.log(names);  // [ 'Up', 'Down', 'Left', 'Right' ]
console.log(values); // [ 0, 1, 2, 3 ]

لتحديد نوع متغير على أنه «أحد أسماء أعضاء الـ enum»، استخدم keyof typeof Direction، وهو union "Up" | "Down" | "Left" | "Right". عندها يبحث Direction[name] عن القيمة بأمان أنواع كامل.

لا يملك enum النصي تعيينًا عكسيًا، لذلك للحصول على اسم عضو من قيمته، ابحث في المدخلات: Object.entries(Status).find(([, v]) => v === "ACTIVE")?.[0] يساوي "Active"، أو undefined عندما لا يملك أي عضو تلك القيمة.

التحقق من أن قيمة موجودة في enum

البيانات القادمة من خارج البرنامج string أو number عادي. يفحصها type guard مقابل قيم الـ enum ويضيّقها إلى نوع الـ enum:

enum Status { Active = "ACTIVE", Inactive = "INACTIVE" }

function isStatus(value: string): value is Status {
    return (Object.values(Status) as string[]).includes(value);
}

function parseStatus(raw: string): Status {
    if (!isStatus(raw)) throw new Error(`unknown status: ${raw}`);
    return raw; // narrowed to Status
}

console.log(parseStatus("ACTIVE") === Status.Active); // true
try {
    parseStatus("DELETED");
} catch (e) {
    if (e instanceof Error) console.log(e.message); // unknown status: DELETED
}

// Enum member name from a string key:
const key: string = "Inactive";
console.log(Status[key as keyof typeof Status]); // INACTIVE

تجنب raw as Status مع المدخلات غير الموثوقة: يُترجم التأكيد، لكن لا شيء يُفحص وقت التشغيل، فينتقل "DELETED" عبر البرنامج بنوع Status صحيح.

const enum

يطلب const enum من المترجم حذف الـ enum وكتابة قيمة كل عضو حيث يُستخدم. لا يوجد كائن وقت التشغيل، فلا يمكن التكرار على شيء ولا التعيين العكسي.

const enum Size {
    Small = 1,
    Medium = 2,
    Large = 3,
}

const chosen = Size.Large;
console.log(chosen); // 3

// Emitted JavaScript for the line above:
//   const chosen = 3 /* Size.Large */;
// There is no Size object; Object.keys(Size) is a compile error (TS2475).

يوفر const enum بضعة بايتات وعملية بحث عن خاصية، لكنه يعتمد على أن يرى المترجم تصريح الـ enum عند ترجمة كل ملف يستخدمه. الأدوات التي تحوّل ملفًا واحدًا في كل مرة، مثل Babel وswc، لا تستطيع رؤية const enum معلن في ملف آخر؛ ويرفض حذف الأنواع في Node الـ const enums مثل أي enum آخر؛ ومع isolatedModules أو verbatimModuleSyntax تبلّغ TypeScript عن الخطأ TS2748 عندما تستخدم const enum من ملف تعريف. معظم كود التطبيقات لا يحتاج إلى const enums.

enum مقابل union type مقابل كائن as const

هناك ثلاث طرق شائعة لتعريف مجموعة ثابتة من القيم:

// 1. Enum
enum ColorEnum { Red = "red", Green = "green" }

// 2. Union of string literals: types only, nothing at runtime
type ColorUnion = "red" | "green";

// 3. as const object: runtime values plus a derived union type
const Color = { Red: "red", Green: "green" } as const;
type Color = (typeof Color)[keyof typeof Color]; // "red" | "green"

function paintEnum(c: ColorEnum) { return `enum ${c}`; }
function paintUnion(c: ColorUnion) { return `union ${c}`; }
function paintConst(c: Color) { return `const ${c}`; }

console.log(paintEnum(ColorEnum.Red)); // needs the enum member
console.log(paintUnion("red"));        // plain strings work
console.log(paintConst(Color.Red), paintConst("green")); // both work
console.log(Object.values(Color));     // [ 'red', 'green' ]

تعتمد فرق كثيرة اليوم افتراضيًا على union من النصوص الحرفية، وتنتقل إلى كائن as const عندما تحتاج إلى القيم وقت التشغيل (للتكرار عليها أو لبناء قائمة منسدلة). والأسباب: أنواع union أنواع خالصة تختفي من الناتج؛ وتقبل النصوص العادية التي تسلّمها JSON وواجهات API؛ والـ enums هي الجزء الوحيد من TypeScript اليومية الذي ليس «JavaScript مع أنواع قابلة للمحو».

وقد أصبحت النقطة الأخيرة عملية. يشغّل Node ملفات .ts مباشرة بحذف الأنواع، والـ enum ليس شيئًا يستطيع حذفه:

node status.ts

SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode

الخيار --experimental-transform-types في Node يجعل الـ enums تعمل، وخيار المترجم erasableSyntaxOnly يبلّغ عن كل enum بالخطأ TS1294، This syntax is not allowed when 'erasableSyntaxOnly' is enabled.، فيستطيع المشروع منعها من البداية. انظر تشغيل TypeScript لمعرفة كيف يعمل حذف الأنواع. لا شيء من هذا يجعل الـ enums خاطئة: الكود المترجم بـ tsc أو بأداة تجميع يشغّلها دون مشكلة، وقاعدة الكود التي تستخدم enums أصلًا لا تكسب كثيرًا من تحويلها.