Enum trong TypeScript: enum số, enum chuỗi và const enum

Enum trong TypeScript là một tập hằng số có tên. enum Direction { Up, Down, Left, Right } tạo ra cùng lúc một kiểu, Direction, và một đối tượng lúc chạy (runtime) mà bạn truy cập các thành viên qua Direction.Up. Các thành viên được đánh số từ 0 nếu bạn không gán giá trị, còn enum chuỗi gán cho mỗi thành viên một chuỗi dễ đọc.

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

Enum là một trong số ít tính năng của TypeScript không chỉ là kiểu: khi code được biên dịch, enum trở thành một đối tượng JavaScript thật.

Enum số

Khi không có giá trị khởi tạo, các thành viên nhận 0, 1, 2 và cứ thế tiếp tục. Gán một số cho thành viên đầu tiên thì các thành viên sau sẽ đếm tiếp từ đó. Bạn cũng có thể đặt giá trị rõ ràng cho từng thành viên, đây là lựa chọn an toàn khi các con số được lưu vào cơ sở dữ liệu hoặc gửi qua mạng.

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

Dựa vào việc tự đánh số là ổn với những giá trị không bao giờ rời khỏi chương trình. Nếu thứ tự thành viên có thể thay đổi và các con số được lưu ở đâu đó, thì chèn một thành viên vào giữa sẽ âm thầm đánh số lại mọi thành viên phía sau.

Enum được biên dịch thành gì

Kiểu bị xóa đi, nhưng enum thì không. Đây là đoạn JavaScript mà TypeScript sinh ra cho một enum số và một enum chuỗi:

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 trả về 0, nên Direction[0] = "Up" được gán ngay trong cùng câu lệnh. Vì vậy enum số ánh xạ theo cả hai chiều: từ tên sang số và từ số ngược về tên. Đó chính là ánh xạ ngược (reverse mapping). Enum chuỗi chỉ ánh xạ từ tên sang giá trị.

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' }

Đối tượng Direction được in ra có tám khóa: bốn tên và bốn con số. Điều đó trở nên quan trọng ngay khi bạn duyệt qua nó.

Enum chuỗi

Mỗi thành viên của enum chuỗi cần một giá trị chuỗi được gán rõ ràng. Các giá trị xuất hiện nguyên vẹn trong log, JSON và cơ sở dữ liệu, nên enum chuỗi dễ gỡ lỗi hơn enum số.

Enum chuỗi có một điểm mang tính danh nghĩa (nominal) khiến nhiều người bất ngờ: không thể gán một chuỗi thường cho nó, kể cả khi nội dung trùng với giá trị của một thành viên.

// 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'?

(Gợi ý trong thông báo chỉ là phỏng đoán của trình biên dịch và ở đây thì sai; cách sửa đúng là Status.Active.) Theo chiều ngược lại, một giá trị Status có thể dùng ở bất cứ đâu cần string. Khi giá trị đến dưới dạng chuỗi, từ JSON hay một biểu mẫu, hãy chuyển đổi chúng bằng một phép kiểm tra như trong phần kiểm tra giá trị bên dưới.

Dùng enum làm kiểu

Tên enum là một kiểu có các giá trị là những thành viên của nó. Kết hợp với switch, TypeScript kiểm tra rằng mọi thành viên đều được xử lý khi hàm phải trả về một giá trị:

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

Nếu thêm một thành viên mới vào Shape mà không có case mới, sides sẽ không biên dịch được nữa với lỗi TS2366, Function lacks ending return statement and return type does not include 'undefined'. Trang switch giới thiệu cách kiểm tra đầy đủ chặt chẽ hơn dựa trên never.

Mấy dòng cuối cho thấy một điểm yếu thật sự của enum số. Một số literal không khớp thành viên nào, const level: Level = 99, là lỗi biên dịch (TS2322), nhưng mọi giá trị có kiểu number đều được chấp nhận, nên 57 vẫn lọt qua. Enum chuỗi không có lỗ hổng này.

Duyệt qua một enum

Lúc chạy, enum là một đối tượng, nên Object.keys, Object.values và Object.entries đều dùng được. Với enum chuỗi, chúng trả về đúng các thành viên. Với enum số, chúng trả về cả các mục ánh xạ ngược, và bạn cần lọc chúng ra:

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 ]

Để khai báo một biến có kiểu "một trong các tên thành viên của enum", dùng keyof typeof Direction, tức là union "Up" | "Down" | "Left" | "Right". Khi đó Direction[name] tra cứu giá trị với đầy đủ an toàn kiểu.

Enum chuỗi không có ánh xạ ngược, nên muốn lấy tên của một thành viên từ giá trị, bạn tìm trong các mục: Object.entries(Status).find(([, v]) => v === "ACTIVE")?.[0] cho ra "Active", hoặc undefined khi không thành viên nào có giá trị đó.

Kiểm tra một giá trị có nằm trong enum không

Dữ liệu từ bên ngoài chương trình là một string hoặc number thường. Một type guard kiểm tra nó với các giá trị của enum và thu hẹp nó về kiểu 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

Tránh dùng raw as Status với đầu vào không đáng tin: phép ép kiểu vẫn biên dịch được, nhưng lúc chạy không có gì được kiểm tra, nên "DELETED" sẽ đi khắp chương trình với kiểu Status như thể hợp lệ.

const enum

const enum yêu cầu trình biên dịch xóa enum và viết giá trị của từng thành viên vào chỗ nó được dùng. Lúc chạy không có đối tượng nào, nên không thể duyệt hay ánh xạ ngược.

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 tiết kiệm vài byte và một lần tra cứu thuộc tính, nhưng nó phụ thuộc vào việc trình biên dịch thấy được khai báo của enum khi biên dịch mọi tệp dùng đến nó. Các công cụ chuyển mã từng tệp một, như Babel và swc, không thấy được một const enum khai báo ở tệp khác; type stripping của Node từ chối const enum giống như mọi enum khác; và khi bật isolatedModules hoặc verbatimModuleSyntax, TypeScript báo lỗi TS2748 nếu bạn dùng một const enum từ tệp khai báo. Phần lớn code ứng dụng không cần đến const enum.

Enum, union type hay đối tượng as const

Có ba cách phổ biến để định nghĩa một tập giá trị cố định:

// 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' ]

Nhiều nhóm giờ mặc định dùng union các chuỗi literal, và chuyển sang đối tượng as const khi cần giá trị lúc chạy (để duyệt hoặc dựng một danh sách thả xuống). Lý do: union là kiểu thuần túy và biến mất khỏi đầu ra; chúng nhận chuỗi thường mà JSON và API gửi về; còn enum là phần duy nhất của TypeScript thường ngày không phải "JavaScript cộng với các kiểu có thể xóa".

Điểm cuối cùng đó giờ đã có ý nghĩa thực tế. Node chạy trực tiếp tệp .ts bằng cách bỏ đi các kiểu, và enum không phải thứ nó bỏ đi được:

node status.ts

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

Cờ --experimental-transform-types của Node giúp enum chạy được, còn tùy chọn trình biên dịch erasableSyntaxOnly báo mọi enum là lỗi TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., nên một dự án có thể cấm enum ngay từ đầu. Xem chạy TypeScript để biết type stripping hoạt động thế nào. Không điều gì ở đây khiến enum trở nên sai: code biên dịch bằng tsc hoặc một bundler vẫn chạy enum tốt, và một codebase đã dùng enum chẳng được lợi bao nhiêu khi chuyển đổi.