Enum ב-TypeScript: מספריים, מחרוזות ו-const enums

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 של מחרוזות:

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

// 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 על קלט לא אמין: ה-assertion עובר קומפילציה, אבל שום דבר לא נבדק בזמן ריצה, ולכן "DELETED" היה עובר בתוכנית עם הטיפוס של Status תקין.

const Enums

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 שהוצהר בקובץ אחר; ה-type stripping של 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 כשהם צריכים את הערכים בזמן ריצה (כדי לעבור עליהם או לבנות רשימה נפתחת). הסיבות: unions הם טיפוסים טהורים ונעלמים מהפלט; הם מקבלים את המחרוזות הרגילות ש-JSON ו-APIs מספקים; ו-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 כדי להבין איך type stripping עובד. שום דבר מזה לא הופך enums לשגויים: קוד שמקומפל עם tsc או עם bundler מריץ אותם בלי בעיה, ובסיס קוד שכבר משתמש ב-enums מרוויח מעט מהמרה.