Enums are one of the few features TypeScript has which is not a type-level extension of JavaScript.
\nEnums allow a developer to define a set of named constants.\nUsing enums can make it easier to document intent, or create a set of distinct cases.\nTypeScript provides both numeric and string-based enums.
\nWe’ll first start off with numeric enums, which are probably more familiar if you’re coming from other languages.\nAn enum can be defined using the enum keyword.
\ntsenum Direction {\n Up = 1,\n Down,\n Left,\n Right\n}
Above, we have a numeric enum where Up is initialized with 1.\nAll of the following members are auto-incremented from that point on.\nIn other words, Direction.Up has the value 1, Down has 2, Left has 3, and Right has 4.
If we wanted, we could leave off the initializers entirely:
\n\ntsenum Direction {\n Up,\n Down,\n Left,\n Right\n}
Here, Up would have the value 0, Down would have 1, etc.\nThis auto-incrementing behavior is useful for cases where we might not care about the member values themselves, but do care that each value is distinct from other values in the same enum.
Using an enum is simple: just access any member as a property off of the enum itself, and declare types using the name of the enum:
\n\ntsenum Response {\n No = 0,\n Yes = 1\n}\n\nfunction respond(recipient: string, message: Response): void {\n // ...\n}\n\nrespond(\"Princess Caroline\", Response.Yes);
Numeric enums can be mixed in computed and constant members (see below).\nThe short story is, enums without initializers either need to be first, or have to come after numeric enums initialized with numeric constants or other constant enum members.\nIn other words, the following isn’t allowed:
\n\ntsenum E {\n A = getSomeValue(),\n B // Error! Enum member must have initializer.\n}
String enums are a similar concept, but have some subtle runtime differences as documented below.\nIn a string enum, each member has to be constant-initialized with a string literal, or with another string enum member.
\n\ntsenum Direction {\n Up = \"UP\",\n Down = \"DOWN\",\n Left = \"LEFT\",\n Right = \"RIGHT\"\n}
While string enums don’t have auto-incrementing behavior, string enums have the benefit that they “serialize” well.\nIn other words, if you were debugging and had to read the runtime value of a numeric enum, the value is often opaque - it doesn’t convey any useful meaning on its own (though reverse mapping can often help), string enums allow you to give a meaningful and readable value when your code runs, independent of the name of the enum member itself.
\nTechnically enums can be mixed with string and numeric members, but it’s not clear why you would ever want to do so:
\n\ntsenum BooleanLikeHeterogeneousEnum {\n No = 0,\n Yes = \"YES\"\n}
Unless you’re really trying to take advantage of JavaScript’s runtime behavior in a clever way, it’s advised that you don’t do this.
\nEach enum member has a value associated with it which can be either constant or computed.\nAn enum member is considered constant if:
\n0:\nts// E.X is constant:\nenum E {\n X\n}
\nts// All enum members in 'E1' and 'E2' are constant.\n\nenum E1 {\n X,\n Y,\n Z\n}\n\nenum E2 {\n A = 1,\n B,\n C\n}
The enum member is initialized with a constant enum expression.\nA constant enum expression is a subset of TypeScript expressions that can be fully evaluated at compile time.\nAn expression is a constant enum expression if it is:
\n+, -, ~ unary operators applied to constant enum expression+, -, *, /, %, <<, >>, >>>, &, |, ^ binary operators with constant enum expressions as operandsIt is a compile time error for constant enum expressions to be evaluated to NaN or Infinity.
In all other cases enum member is considered computed.
\n\ntsenum FileAccess {\n // constant members\n None,\n Read = 1 << 1,\n Write = 1 << 2,\n ReadWrite = Read | Write,\n // computed member\n G = \"123\".length\n}
There is a special subset of constant enum members that aren’t calculated: literal enum members.\nA literal enum member is a constant enum member with no initialized value, or with values that are initialized to
\n\"foo\", \"bar, \"baz\")1, 100)-1, -100)When all members in an enum have literal enum values, some special semantics come to play.
\nThe first is that enum members also become types as well!\nFor example, we can say that certain members can only have the value of an enum member:
\n\ntsenum ShapeKind {\n Circle,\n Square\n}\n\ninterface Circle {\n kind: ShapeKind.Circle;\n radius: number;\n}\n\ninterface Square {\n kind: ShapeKind.Square;\n sideLength: number;\n}\n\nlet c: Circle = {\n kind: ShapeKind.Square, // Error! Type 'ShapeKind.Square' is not assignable to type 'ShapeKind.Circle'.\n radius: 100\n};
The other change is that enum types themselves effectively become a union of each enum member.\nWhile we haven’t discussed union types yet, all that you need to know is that with union enums, the type system is able to leverage the fact that it knows the exact set of values that exist in the enum itself.\nBecause of that, TypeScript can catch silly bugs where we might be comparing values incorrectly.\nFor example:
\n\ntsenum E {\n Foo,\n Bar\n}\n\nfunction f(x: E) {\n if (x !== E.Foo || x !== E.Bar) {\n // ~~~~~~~~~~~\n // Error! This condition will always return 'true' since the types 'E.Foo' and 'E.Bar' have no overlap.\n }\n}
In that example, we first checked whether x was not E.Foo.\nIf that check succeeds, then our || will short-circuit, and the body of the ‘if’ will run.\nHowever, if the check didn’t succeed, then x can only be E.Foo, so it doesn’t make sense to see whether it’s equal to E.Bar.
Enums are real objects that exist at runtime.\nFor example, the following enum
\n\ntsenum E {\n X,\n Y,\n Z\n}
can actually be passed around to functions
\n\ntsfunction f(obj: { X: number }) {\n return obj.X;\n}\n\n// Works, since 'E' has a property named 'X' which is a number.\nf(E);
Even though Enums are real objects that exist at runtime, the keyof keyword works differently than you might expect for typical objects. Instead, use keyof typeof to get a Type that represents all Enum keys as strings.
\ntsenum LogLevel {\n ERROR,\n WARN,\n INFO,\n DEBUG\n}\n\n/**\n * This is equivalent to:\n * type LogLevelStrings = 'ERROR' | 'WARN' | 'INFO' | 'DEBUG';\n */\ntype LogLevelStrings = keyof typeof LogLevel;\n\nfunction printImportant(key: LogLevelStrings, message: string) {\n const num = LogLevel[key];\n if (num <= LogLevel.WARN) {\n console.log(\"Log level key is: \", key);\n console.log(\"Log level value is: \", num);\n console.log(\"Log level message is: \", message);\n }\n}\nprintImportant(\"ERROR\", \"This is a message\");
In addition to creating an object with property names for members, numeric enums members also get a reverse mapping from enum values to enum names.\nFor example, in this example:
\n\ntsenum Enum {\n A\n}\nlet a = Enum.A;\nlet nameOfA = Enum[a]; // \"A\"
TypeScript might compile this down to something like the following JavaScript:
\n\njsvar Enum;\n(function(Enum) {\n Enum[(Enum[\"A\"] = 0)] = \"A\";\n})(Enum || (Enum = {}));\nvar a = Enum.A;\nvar nameOfA = Enum[a]; // \"A\"
In this generated code, an enum is compiled into an object that stores both forward (name -> value) and reverse (value -> name) mappings.\nReferences to other enum members are always emitted as property accesses and never inlined.
Keep in mind that string enum members do not get a reverse mapping generated at all.
\nconst enumsIn most cases, enums are a perfectly valid solution.\nHowever sometimes requirements are tighter.\nTo avoid paying the cost of extra generated code and additional indirection when accessing enum values, it’s possible to use const enums.\nConst enums are defined using the const modifier on our enums:
\ntsconst enum Enum {\n A = 1,\n B = A * 2\n}
Const enums can only use constant enum expressions and unlike regular enums they are completely removed during compilation.\nConst enum members are inlined at use sites.\nThis is possible since const enums cannot have computed members.
\n\ntsconst enum Directions {\n Up,\n Down,\n Left,\n Right\n}\n\nlet directions = [\n Directions.Up,\n Directions.Down,\n Directions.Left,\n Directions.Right\n];
in generated code will become
\n\njsvar directions = [0 /* Up */, 1 /* Down */, 2 /* Left */, 3 /* Right */];
Ambient enums are used to describe the shape of already existing enum types.
\n\ntsdeclare enum Enum {\n A = 1,\n B,\n C = 2\n}
One important difference between ambient and non-ambient enums is that, in regular enums, members that don’t have an initializer will be considered constant if its preceding enum member is considered constant.\nIn contrast, an ambient (and non-const) enum member that does not have initializer is always considered computed.
","headings":[{"value":"Numeric enums","depth":2},{"value":"String enums","depth":2},{"value":"Heterogeneous enums","depth":2},{"value":"Computed and constant members","depth":2},{"value":"Union enums and enum member types","depth":2},{"value":"Enums at runtime","depth":2},{"value":"Enums at compile time","depth":2},{"value":"Reverse mappings","depth":3},{"value":"const enums","depth":3},{"value":"Ambient enums","depth":2}],"frontmatter":{"permalink":"/docs/handbook/enums.html","title":"Enums"}}},"pageContext":{"slug":"/docs/handbook/enums.html","isOldHandbook":true}}}