Çalıştırılabilir TypeScript Dokümanları: Enum'lar

Q: TypeScript'te bir enum üzerinde nasıl dolaşılır?

Bir string enum için Object.values(MyEnum) değerleri, Object.keys(MyEnum) adları verir. Sayısal bir enum reverse mapping girdileri de içerir ("0": "Up"), bu yüzden onları filtreleyin: Object.keys(Direction).filter((k) => isNaN(Number(k))) yalnızca adları verir. Bir const enum üzerinde dolaşılamaz, çünkü çalışma zamanında var değildir.

Q: TypeScript'te enum mu, union tip mi kullanmalıyım?

Pek çok ekip bir string literal union'ını (type Status = "active" | "inactive"), değerlere çalışma zamanında da ihtiyaç duyduklarında bir as const nesnesini tercih ediyor. Union'lar tamamen silinir, Node'un yerleşik type stripping özelliği ve erasableSyntaxOnly seçeneğiyle çalışır ve "active" gibi düz string'leri kabul eder. Enum'lar da gayet iyidir, özellikle onları zaten kullanan kod tabanlarında.

Bir TypeScript enum'ı, adlandırılmış bir sabitler kümesidir. enum Direction { Up, Down, Left, Right } hem Direction adında bir tip hem de üyelerine Direction.Up şeklinde eriştiğiniz bir çalışma zamanı nesnesi oluşturur. Üyelere değer vermezseniz 0'dan başlayarak numaralandırılır; string enum'lar ise her üyeye okunabilir bir string verir.

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'lar, yalnızca tip olmayan az sayıdaki TypeScript özelliğinden biridir: kod derlendiğinde bir enum gerçek bir JavaScript nesnesine dönüşür.

Sayısal Enum'lar

Başlangıç değeri verilmezse üyeler 0, 1, 2 gibi değerler alır. İlk üyeye bir sayı verin, geri kalanlar ondan devam eder. Her değeri açıkça da belirleyebilirsiniz; sayılar bir veritabanında saklanıyor ya da ağ üzerinden gönderiliyorsa güvenli seçim budur.

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

Otomatik numaralandırmaya güvenmek programdan hiç çıkmayan değerler için sorun değildir. Üyelerin sırası değişebilecekse ve sayılar herhangi bir yerde saklanıyorsa, ortaya bir üye eklemek ondan sonraki her şeyi sessizce yeniden numaralandırır.

Bir Enum Neye Derlenir

Tipler silinir, ama bir enum silinmez. TypeScript'in sayısal ve string bir enum için ürettiği JavaScript şudur:

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 ifadesi 0 döndürür, bu yüzden Direction[0] = "Up" aynı ifadede ayarlanır. Böylece sayısal bir enum iki yönlü eşleme yapar: addan sayıya ve sayıdan tekrar ada. Buna reverse mapping denir. String enum'lar yalnızca adları değerlere eşler.

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

Yazdırılan Direction nesnesinin sekiz anahtarı vardır: dört ad ve dört sayı. Bu, üzerinde dolaşmaya başladığınız anda önem kazanır.

String Enum'lar

Bir string enum'ın her üyesi açık bir string değeri ister. Değerler loglarda, JSON'da ve veritabanlarında olduğu gibi görünür; bu da string enum'larda hata ayıklamayı sayılara göre kolaylaştırır.

Bir string enum, insanları şaşırtan bir açıdan nominaldir: metin bir üyenin değeriyle eşleşse bile düz bir string ona atanamaz.

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

(Mesajdaki öneri derleyicinin bir tahminidir ve burada yanlıştır; çözüm Status.Active yazmaktır.) Diğer yönde, bir Status değeri string beklenen her yerde kullanılabilir. Değerler JSON'dan veya bir formdan string olarak geldiğinde, onları aşağıdaki değer kontrolü bölümündekine benzer bir kontrolle dönüştürün.

Bir Enum'ı Tip Olarak Kullanmak

Enum adı, değerleri üyeleri olan bir tiptir. switch ile birleştiğinde, fonksiyonun bir değer döndürmesi gerektiğinde TypeScript her üyenin ele alındığını kontrol eder:

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 tipine yeni bir case olmadan yeni bir üye eklenirse sides fonksiyonu TS2366 ile derlenmez olur: Function lacks ending return statement and return type does not include 'undefined'. Daha katı, never tabanlı kapsamlı kontrolü switch sayfası gösteriyor.

Son satırlar sayısal enum'ların gerçek bir zayıflığını gösteriyor. Hiçbir üyeyle eşleşmeyen bir sayı literal'i, const level: Level = 99, bir derleme hatasıdır (TS2322), ama number tipindeki her değer kabul edilir; bu yüzden 57 geçip gider. String enum'larda bu açık yoktur.

Bir Enum Üzerinde Dolaşmak

Bir enum çalışma zamanında bir nesnedir, bu yüzden Object.keys, Object.values ve Object.entries çalışır. Bir string enum için tam olarak üyeleri döndürürler. Sayısal bir enum için reverse mapping girdilerini de döndürürler, onları filtrelersiniz:

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 ]

Bir değişkene "enum'ın üye adlarından biri" tipini vermek için "Up" | "Down" | "Left" | "Right" union'ına karşılık gelen keyof typeof Direction kullanın. Ardından Direction[name] değeri tam tip güvenliğiyle bulur.

Bir string enum'da reverse mapping yoktur; bu yüzden bir üyenin adını değerinden bulmak için girdilerde arayın: Object.entries(Status).find(([, v]) => v === "ACTIVE")?.[0] sonucu "Active" olur, hiçbir üye o değere sahip değilse undefined.

Bir Değerin Enum'da Olup Olmadığını Kontrol Etmek

Program dışından gelen veriler düz bir string veya number değeridir. Bir type guard onu enum'ın değerlerine karşı kontrol eder ve enum tipine daraltır:

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

Güvenilmeyen girdide raw as Status kullanmaktan kaçının: assertion derlenir ama çalışma zamanında hiçbir şey kontrol edilmez; böylece "DELETED" programın içinde geçerli bir Status olarak tiplenmiş halde dolaşır.

const Enum'lar

const enum, derleyiciden enum'ı silmesini ve her üyenin değerini kullanıldığı yere yazmasını ister. Çalışma zamanında bir nesne yoktur, bu yüzden hiçbir şey üzerinde dolaşılamaz ve reverse mapping yapılamaz.

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 birkaç bayt ve bir özellik aramasından tasarruf sağlar, ama derleyicinin onu kullanan her dosyayı derlerken enum'ın bildirimini görmesine bağlıdır. Babel ve swc gibi dosyaları tek tek dönüştüren araçlar başka bir dosyada bildirilmiş bir const enum'ı göremez; Node'un type stripping özelliği const enum'ları diğer her enum gibi reddeder; isolatedModules veya verbatimModuleSyntax açıkken de bir bildirim dosyasındaki const enum'ı kullandığınızda TypeScript TS2748 hatası bildirir. Çoğu uygulama kodunun const enum'lara ihtiyacı yoktur.

Enum, Union Tip ve as const Nesnesi

Sabit bir değer kümesini tanımlamanın yaygın üç yolu vardır:

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

	`enum`	Literal union'ı	`as const` nesnesi
Çalışma zamanında var	evet, bir nesne	hayır	evet, düz bir nesne
Değerler üzerinde dolaşma	`Object.values` (sayısal: filtreleyin)	hayır, dolaşılacak bir şey yok	`Object.values`
Düz bir `"red"` kabul eder	hayır (string enum'lar)	evet	evet
`X.Red` ile adla erişim	evet	hayır	evet
Reverse mapping	yalnızca sayısal enum'lar	hayır	hayır
Node type stripping ile çalışır	hayır	evet	evet
`erasableSyntaxOnly` izin verir	hayır	evet	evet
Öğrenilecek ek sözdizimi	enum kuralları, const enum'lar	yok	`typeof` kalıbı

Pek çok ekip artık varsayılan olarak bir string literal union'ı kullanıyor, değerlere çalışma zamanında ihtiyaç duyduğunda da (üzerlerinde dolaşmak ya da bir açılır liste oluşturmak için) as const nesnesine geçiyor. Nedenleri: union'lar saf tiplerdir ve çıktıdan kaybolur; JSON ve API'lerin getirdiği düz string'leri kabul ederler; enum'lar da günlük TypeScript'in "JavaScript artı silinebilir tipler" olmayan tek parçasıdır.

Bu son nokta artık pratik bir önem taşıyor. Node, .ts dosyalarını tipleri silerek doğrudan çalıştırır ve bir enum silebileceği bir şey değildir:

node status.ts

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

Node'un --experimental-transform-types bayrağı enum'ların çalışmasını sağlar; erasableSyntaxOnly derleyici seçeneği ise her enum'ı TS1294 hatası olarak bildirir, This syntax is not allowed when 'erasableSyntaxOnly' is enabled.; böylece bir proje onları baştan yasaklayabilir. Type stripping'in nasıl çalıştığı için TypeScript çalıştırma sayfasına bakın. Bunların hiçbiri enum'ları yanlış yapmaz: tsc veya bir bundler ile derlenen kod onları sorunsuz çalıştırır ve enum'ları zaten kullanan bir kod tabanı onları dönüştürmekten pek bir şey kazanmaz.

Sıkça Sorulan Sorular

TypeScript'te enum nedir?

Hem bir tip hem de bir çalışma zamanı nesnesi olan adlandırılmış bir sabitler kümesidir: enum Direction { Up, Down }, Direction.Up yazmanıza ve Direction tipini bir parametre tipi olarak kullanmanıza izin verir. TypeScript özelliklerinin çoğunun aksine bir enum silinmez: çalışma zamanında var olan bir JavaScript nesnesine derlenir.

TypeScript'te bir enum üzerinde nasıl dolaşılır?

Bir string enum için Object.values(MyEnum) değerleri, Object.keys(MyEnum) adları verir. Sayısal bir enum reverse mapping girdileri de içerir ("0": "Up"), bu yüzden onları filtreleyin: Object.keys(Direction).filter((k) => isNaN(Number(k))) yalnızca adları verir. Bir const enum üzerinde dolaşılamaz, çünkü çalışma zamanında var değildir.

TypeScript'te bir string'i enum değerine nasıl çeviririm?

String'i bir type guard içinde enum'ın değerlerine karşı kontrol edin: function isStatus(s: string): s is Status { return (Object.values(Status) as string[]).includes(s); }. Kontrolden sonra s değişkeninin tipi Status olur. Düz bir s as Status derlenir ama çalışma zamanında hiçbir kontrol yapmaz.

TypeScript'te enum mu, union tip mi kullanmalıyım?

Pek çok ekip bir string literal union'ını (type Status = "active" | "inactive"), değerlere çalışma zamanında da ihtiyaç duyduklarında bir as const nesnesini tercih ediyor. Union'lar tamamen silinir, Node'un yerleşik type stripping özelliği ve erasableSyntaxOnly seçeneğiyle çalışır ve "active" gibi düz string'leri kabul eder. Enum'lar da gayet iyidir, özellikle onları zaten kullanan kod tabanlarında.

enum ile const enum arasındaki fark nedir?

Normal bir enum, çalışma zamanında üzerinde dolaşıp arama yapabileceğiniz bir nesneye derlenir. Bir const enum derleme sırasında silinir ve her kullanımı değeriyle değiştirilir (Size.Large ifadesi 2 olur); böylece çalışma zamanında hiçbir maliyeti olmaz ama üzerinde dolaşılamaz ve dosyaları tek tek derleyen araçlar onu kısıtlar.

İlgili kavramlar