Numeric-Enums

Right, so you’ve decided to venture into the wild west of TypeScript declaration files (.d.ts), where the rules get a little… bendy. Good for you. This is where you make peace with JavaScript code you didn’t write and teach TypeScript how to understand it. And when that JavaScript code has enums, you can’t just waltz in with a normal enum declaration. You need an ambient enum. The declare keyword is your passport here. It tells TypeScript, “Hey, trust me on this. This thing exists at runtime, I’m just describing its shape for you.” You use it in .d.ts files to describe code that lives elsewhere.

Now, let’s talk about the elephant in the room: the growing sentiment that you might not need enums at all. I know, I know, I just spent a chapter singing their praises. But hear me out. TypeScript offers a powerfully elegant alternative that often feels more… well, TypeScript-y. It’s the humble union of literal types. Think of it this way: an enum is a runtime construct that generates a JavaScript object. A union of string or number literals is a purely type-level construct. It vanishes when your code is compiled to JavaScript, leaving behind only the raw, simple primitives you actually use. This isn’t just a philosophical difference; it has real, practical implications.

Now, let’s get into the real magic: when an enum member becomes more than just a value in an enum—it becomes its own unique type, a literal type. This is where TypeScript flexes its type system muscles and turns your boring old enums into a powerful tool for writing self-documenting, type-safe code. Think of it this way: a variable of type MyEnum can hold any value from that enum. But a variable of the type of a specific member, like MyEnum.Value, can only hold that one, exact value. It’s a type so narrow and specific, it’s essentially a constant built into the type system itself.

Alright, let’s talk about const enums. You’re going to love the concept and hate the implementation. It’s one of those classic TypeScript features that’s brilliant in theory but comes with a giant asterisk the size of Jupiter. Here’s the elevator pitch: a const enum is completely erased from your compiled JavaScript. Unlike a regular enum, which generates a lookup object in the final code, a const enum has its members inlined directly wherever you use them. It’s the ultimate form of type-safe abstraction with zero runtime cost. Sounds perfect, right? Well, hold my drink.

Now we arrive at the dark, cobwebbed corner of the enum world: the heterogeneous enum. TypeScript, in its infinite and occasionally misguided wisdom, allows you to mix string and numeric members within the same enum. It’s a feature that feels like it was added because they could, not because they should. Let me be direct: you should almost never do this. It’s a code smell of the highest order, a confusing pattern that will make the next developer (who might be you in six months) curse your name.

Right, so you’ve met numeric enums. They’re fine. They get the job done. But you and I both know that debugging something because LogLevel[2] returns "WARN" feels a bit like communicating through a translator who occasionally makes things up. Enter string enums. They are, in my utterly unbiased opinion, what enums always wanted to be when they grew up. A string enum is exactly what it sounds like: an enum where each member is explicitly initialized with a string value. No more implicit reverse mappings to magical numbers. It’s explicit, it’s clear, and it serializes to something human-readable without you having to lift a finger.

Let’s talk about the first enums you’ll meet, the ones that look suspiciously like numbers. Because, well, they are numbers. A numeric enum is essentially a fancy way to give friendly names to a set of numeric values. TypeScript’s approach here is pragmatic, a bit clever, and comes with one of its weirder party tricks: reverse mapping. The Basics and Auto-Incrementing Madness You define a numeric enum using the enum keyword. Here’s the classic example: