{
    "slug": "typescript_enums",
    "term": "TypeScript Enums vs Const Enums vs Union Types",
    "category": "typescript",
    "difficulty": "intermediate",
    "short": "Three ways to define a set of named constants in TypeScript — regular enums emit JavaScript, const enums are inlined at compile time, and union types are the idiomatic zero-cost alternative.",
    "long": "Regular enum: generates JavaScript object, supports reverse mapping (Direction[0] === 'Up'). Const enum: fully inlined at compile time — zero JavaScript generated, faster but no runtime access. String union type: type Direction = 'Up' | 'Down' — no JavaScript emitted, readable, tree-shakeable, and more compatible with JSON APIs. The TypeScript community trend: prefer string union types over enums for most cases; use const enums only when performance is critical and runtime access is not needed; avoid regular numeric enums (they allow invalid values).",
    "aliases": [
        "enum TypeScript",
        "const enum",
        "string union",
        "union type enum"
    ],
    "tags": [
        "typescript",
        "types"
    ],
    "misconception": "Enums are always better than union types because they are explicit — string union types are fully type-safe, produce no JavaScript, work perfectly with JSON, and are the idiomatic TypeScript approach.",
    "why_it_matters": "A numeric enum (enum Status { Active = 0 }) allows Status[99] at runtime with no error — a string union type Status = 'active' | 'inactive' makes invalid values a compile-time error and produces cleaner JSON.",
    "common_mistakes": [
        "Numeric enums in APIs — JSON serialises as numbers, not readable names.",
        "Regular enums where const enums or union types would be better — unnecessary JavaScript overhead.",
        "Mixing enum and non-enum values — direction: Direction | null requires careful handling.",
        "Using enum as a namespace — use a regular object const as a namespace instead."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "typescript_interfaces_types",
        "typescript_utility_types",
        "typescript_generics"
    ],
    "prerequisites": [
        "typescript_interfaces_types",
        "enums",
        "typescript_config"
    ],
    "refs": [
        "https://www.typescriptlang.org/docs/handbook/enums.html"
    ],
    "bad_code": "// Numeric enum — allows invalid values, generates JS:\nenum Direction { Up, Down, Left, Right }\nconst d: Direction = 99; // No error! 99 is not a valid direction\nJSON.stringify(Direction.Up); // '0' — not readable\n\n// Regular enum generates runtime JS object:\n// var Direction;\n// Direction[Direction.Up = 0] = 'Up'; ...",
    "good_code": "// String union — zero JS, type-safe, readable JSON:\ntype Direction = 'Up' | 'Down' | 'Left' | 'Right';\nconst d: Direction = 'Invalid'; // Compile error!\nJSON.stringify('Up'); // 'Up' — readable\n\n// Const enum — inlined, no JS:\nconst enum Color { Red = 'red', Blue = 'blue' }\nconst c = Color.Red; // Compiled to: const c = 'red'\n\n// Object const as namespace when runtime needed:\nexport const Direction = { Up: 'up', Down: 'down' } as const;\nexport type Direction = typeof Direction[keyof typeof Direction];",
    "quick_fix": "Prefer const enums or union types over regular enums — regular enums compile to JavaScript objects with runtime overhead; const enums are erased and union types need no runtime representation",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/typescript_enums",
        "html_url": "https://codeclaritylab.com/glossary/typescript_enums",
        "json_url": "https://codeclaritylab.com/glossary/typescript_enums.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[TypeScript Enums vs Const Enums vs Union Types](https://codeclaritylab.com/glossary/typescript_enums) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/typescript_enums"
            }
        }
    }
}