Enum TypeScript: Enum Numerik, String, dan const

Enum TypeScript adalah kumpulan konstanta bernama. enum Direction { Up, Down, Left, Right } membuat sebuah tipe, Direction, sekaligus objek runtime yang member-nya kamu akses sebagai Direction.Up. Member diberi nomor mulai dari 0 kecuali kamu memberinya nilai, dan enum string memberi setiap member sebuah string yang mudah dibaca.

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 adalah salah satu dari sedikit fitur TypeScript yang bukan sekadar tipe: enum menjadi objek JavaScript sungguhan saat kodenya dikompilasi.

Enum Numerik

Tanpa nilai awal, member mendapat 0, 1, 2, dan seterusnya. Beri member pertama sebuah angka, dan sisanya berlanjut dari angka itu. Kamu juga bisa mengatur setiap nilai secara eksplisit, yang merupakan pilihan aman kalau angkanya disimpan di database atau dikirim lewat jaringan.

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

Mengandalkan penomoran otomatis tidak masalah untuk nilai yang tidak pernah keluar dari program. Kalau urutan member mungkin berubah dan angkanya disimpan di mana pun, menyisipkan member di tengah akan diam-diam menomori ulang semua member setelahnya.

Hasil Kompilasi Sebuah Enum

Tipe dihapus, tetapi enum tidak. Berikut JavaScript yang dihasilkan TypeScript untuk enum numerik dan enum string:

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 mengembalikan 0, jadi Direction[0] = "Up" diatur dalam pernyataan yang sama. Karena itu, enum numerik memetakan dua arah: dari nama ke angka dan dari angka kembali ke nama. Itulah reverse mapping. Enum string hanya memetakan nama ke nilai.

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

Objek Direction yang tercetak punya delapan key: empat nama dan empat angka. Hal ini jadi penting begitu kamu mengiterasinya.

Enum String

Setiap member enum string butuh nilai string yang eksplisit. Nilai-nilai itu muncul apa adanya di log, JSON, dan database, yang membuat enum string lebih mudah di-debug daripada angka.

Enum string bersifat nominal dalam satu hal yang sering mengejutkan: string biasa tidak bisa diberikan kepadanya, bahkan ketika teksnya sama dengan nilai sebuah member.

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

(Saran di pesan itu hanyalah tebakan compiler dan salah di sini; perbaikannya adalah Status.Active.) Ke arah sebaliknya, nilai Status bisa dipakai di mana pun string diharapkan. Kalau nilai datang sebagai string, dari JSON atau form, konversikan dengan pemeriksaan seperti di bagian tentang memeriksa nilai di bawah.

Memakai Enum sebagai Tipe

Nama enum adalah tipe yang nilainya adalah member-member enum itu. Dikombinasikan dengan switch, TypeScript memeriksa bahwa setiap member ditangani ketika fungsi harus mengembalikan nilai:

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

Kalau member baru ditambahkan ke Shape tanpa case baru, sides tidak lagi bisa dikompilasi dengan TS2366, Function lacks ending return statement and return type does not include 'undefined'. Halaman switch memperlihatkan pemeriksaan menyeluruh berbasis never yang lebih ketat.

Baris-baris terakhir memperlihatkan kelemahan nyata enum numerik. Literal angka yang tidak cocok dengan member mana pun, const level: Level = 99, adalah error kompilasi (TS2322), tetapi nilai apa pun yang bertipe number diterima, jadi 57 bisa lolos. Enum string tidak punya celah ini.

Mengiterasi Enum

Enum adalah objek saat runtime, jadi Object.keys, Object.values, dan Object.entries bisa dipakai. Untuk enum string, ketiganya mengembalikan member persis apa adanya. Untuk enum numerik, ketiganya juga mengembalikan entri reverse mapping, yang perlu kamu saring:

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 ]

Untuk memberi tipe variabel sebagai "salah satu nama member enum", pakai keyof typeof Direction, yaitu union "Up" | "Down" | "Left" | "Right". Lalu Direction[name] mencari nilainya dengan keamanan tipe penuh.

Enum string tidak punya reverse mapping, jadi untuk mendapatkan nama member dari nilainya, cari di entrinya: Object.entries(Status).find(([, v]) => v === "ACTIVE")?.[0] menghasilkan "Active", atau undefined kalau tidak ada member dengan nilai itu.

Memeriksa Apakah Sebuah Nilai Ada di Enum

Data dari luar program berupa string atau number biasa. Type guard memeriksanya terhadap nilai-nilai enum dan mempersempitnya menjadi tipe 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

Hindari raw as Status pada input yang tidak tepercaya: assertion itu lolos kompilasi, tetapi tidak ada yang diperiksa saat runtime, jadi "DELETED" akan beredar di program dengan tipe Status yang seolah valid.

const Enum

const enum meminta compiler menghapus enum dan menuliskan nilai setiap member di tempat ia dipakai. Tidak ada objek saat runtime, jadi tidak ada yang bisa diiterasi atau di-reverse mapping.

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 menghemat beberapa byte dan satu pencarian property, tetapi bergantung pada compiler yang melihat deklarasi enum saat mengompilasi setiap file yang memakainya. Alat yang mentranspilasi satu file sekaligus, seperti Babel dan swc, tidak bisa melihat const enum yang dideklarasikan di file lain; type stripping milik Node menolak const enum seperti enum lainnya; dan dengan isolatedModules atau verbatimModuleSyntax, TypeScript melaporkan error TS2748 saat kamu memakai const enum dari file deklarasi. Sebagian besar kode aplikasi tidak butuh const enum.

Enum vs Union Type vs Objek as const

Ada tiga cara umum untuk mendefinisikan kumpulan nilai yang tetap:

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

Banyak tim sekarang memakai union berisi string literal secara default, lalu beralih ke objek as const kalau mereka butuh nilainya saat runtime (untuk diiterasi atau membuat dropdown). Alasannya: union adalah tipe murni dan hilang dari output; union menerima string biasa yang dikirim JSON dan API; dan enum adalah satu-satunya bagian TypeScript sehari-hari yang bukan "JavaScript ditambah tipe yang bisa dihapus".

Poin terakhir itu kini terasa dalam praktik. Node menjalankan file .ts secara langsung dengan membuang tipenya, dan enum bukan sesuatu yang bisa dibuang:

node status.ts

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

Flag --experimental-transform-types milik Node membuat enum bisa berjalan, dan opsi compiler erasableSyntaxOnly melaporkan setiap enum sebagai error TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., sehingga sebuah proyek bisa melarangnya sejak awal. Lihat menjalankan TypeScript untuk cara kerja type stripping. Semua ini tidak membuat enum salah: kode yang dikompilasi dengan tsc atau bundler menjalankannya dengan baik, dan codebase yang sudah memakai enum tidak banyak diuntungkan dengan mengonversinya.