|
| 1 | +--- |
| 2 | +title: Enums |
| 3 | +id: version-1.1.0-enums |
| 4 | +original_id: enums |
| 5 | +--- |
| 6 | + |
| 7 | +Nowadays almost all typed languages have support for enumerated types, including TypeScript. Enums limit the range of a variable's values to a set of predefined constants, which makes it easier to document intent. |
| 8 | + |
| 9 | +GraphQL also has enum type support, so TypeGraphQL allows us to use TypeScript enums in our GraphQL schema. |
| 10 | + |
| 11 | +## Creating enum |
| 12 | + |
| 13 | +Let's create a TypeScript enum. It can be a numeric or string enum - the internal values of enums are taken from the enum definition values and the public names taken from the enum keys: |
| 14 | + |
| 15 | +```typescript |
| 16 | +// implicit value 0, 1, 2, 3 |
| 17 | +enum Direction { |
| 18 | + UP, |
| 19 | + DOWN, |
| 20 | + LEFT, |
| 21 | + RIGHT, |
| 22 | +} |
| 23 | + |
| 24 | +// or explicit values |
| 25 | +enum Direction { |
| 26 | + UP = "up", |
| 27 | + DOWN = "down", |
| 28 | + LEFT = "left", |
| 29 | + RIGHT = "right", |
| 30 | +} |
| 31 | +``` |
| 32 | + |
| 33 | +To tell TypeGraphQL about our enum, we would ideally mark the enums with the `@EnumType()` decorator. However, TypeScript decorators only work with classes, so we need to make TypeGraphQL aware of the enums manually by calling the `registerEnumType` function and providing the enum name for GraphQL: |
| 34 | + |
| 35 | +```typescript |
| 36 | +import { registerEnumType } from "type-graphql"; |
| 37 | + |
| 38 | +registerEnumType(Direction, { |
| 39 | + name: "Direction", // this one is mandatory |
| 40 | + description: "The basic directions", // this one is optional |
| 41 | +}); |
| 42 | +``` |
| 43 | + |
| 44 | +In case we need to provide additional GraphQL-related config for values, like description or deprecation reason, we can use `valuesConfig` property and put the data inside it, e.g.: |
| 45 | + |
| 46 | +```typescript |
| 47 | +enum Direction { |
| 48 | + UP = "UP", |
| 49 | + DOWN = "DOWN", |
| 50 | + LEFT = "LEFT", |
| 51 | + RIGHT = "RIGHT", |
| 52 | + SIDEWAYS = "SIDEWAYS", |
| 53 | +} |
| 54 | + |
| 55 | +registerEnumType(Direction, { |
| 56 | + name: "Direction", |
| 57 | + description: "The basic directions", |
| 58 | + valuesConfig: { |
| 59 | + SIDEWAYS: { |
| 60 | + deprecationReason: "Replaced with Left or Right", |
| 61 | + }, |
| 62 | + RIGHT: { |
| 63 | + description: "The other left", |
| 64 | + }, |
| 65 | + }, |
| 66 | +}); |
| 67 | +``` |
| 68 | + |
| 69 | +This way, the additional info will be emitted in the GraphQL schema: |
| 70 | + |
| 71 | +```graphql |
| 72 | +enum Direction { |
| 73 | + UP |
| 74 | + DOWN |
| 75 | + LEFT |
| 76 | + """ |
| 77 | + The other left |
| 78 | + """ |
| 79 | + RIGHT |
| 80 | + SIDEWAYS @deprecated(reason: "Replaced with Left or Right") |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +## Using enum |
| 85 | + |
| 86 | +The last step is very important: TypeScript has limited reflection ability, so this is a case where we have to explicitly provide the enum type for object type fields, input type fields, args, and the return type of queries and mutations: |
| 87 | + |
| 88 | +```typescript |
| 89 | +@InputType() |
| 90 | +class JourneyInput { |
| 91 | + @Field(type => Direction) // it's very important |
| 92 | + direction: Direction; |
| 93 | +} |
| 94 | +``` |
| 95 | + |
| 96 | +Without this annotation, the generated GQL type would be `String` or `Float` (depending on the enum type), rather than the `ENUM` we are aiming for. |
| 97 | + |
| 98 | +With all that in place, we can use our enum directly in our code 😉 |
| 99 | + |
| 100 | +```typescript |
| 101 | +@Resolver() |
| 102 | +class SpriteResolver { |
| 103 | + private sprite = getMarioSprite(); |
| 104 | + |
| 105 | + @Mutation() |
| 106 | + move(@Arg("direction", type => Direction) direction: Direction): boolean { |
| 107 | + switch (direction) { |
| 108 | + case Direction.Up: |
| 109 | + this.sprite.position.y++; |
| 110 | + break; |
| 111 | + case Direction.Down: |
| 112 | + this.sprite.position.y--; |
| 113 | + break; |
| 114 | + case Direction.Left: |
| 115 | + this.sprite.position.x--; |
| 116 | + break; |
| 117 | + case Direction.Right: |
| 118 | + this.sprite.position.x++; |
| 119 | + break; |
| 120 | + default: |
| 121 | + // it will never be hitten ;) |
| 122 | + return false; |
| 123 | + } |
| 124 | + |
| 125 | + return true; |
| 126 | + } |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +## Interoperability |
| 131 | + |
| 132 | +Enums in TypeGraphQL are designed with server side in mind - the runtime will map the string value from input into a corresponding enum value, like `"UP"` into `0`. While this is very handy e.g. for mapping database values into GraphQL API enum names, it makes it unusable on the query side because `Direction.UP` will put `0` in the query which is an invalid value (should be `UP`). |
| 133 | + |
| 134 | +So if we would like to share the types definition and use the enum on the client side app or use the enums directly on the server app e.g. in tests, we have to use the direct mapping of the enum member names with values, e.g.: |
| 135 | + |
| 136 | +```typescript |
| 137 | +enum Direction { |
| 138 | + UP = "UP", |
| 139 | + DOWN = "DOWN", |
| 140 | + LEFT = "LEFT", |
| 141 | + RIGHT = "RIGHT", |
| 142 | +} |
| 143 | +``` |
0 commit comments