## Introduction

We will continue with the same repository as in the previous article on <a href="/blog/graphql-scalars-and-their-input-and-result-coercion">GraphQL scalars</a>. You can clone the GitHub repository using this command
``` bash
git clone git@github.com:atherosai/graphql-gateway-apollo-express.git
```

install dependencies with

``` bash
npm i
```

and start the server in development with 

``` bash
npm run dev
```

You should be now able to <a href="http://localhost:8000/graphql" title="GraphQL playground">access GraphQL Playground</a>

In this part, we will go through the fields that use **Enum** fields in our previously defined schema. If you are new to GraphQL, it might also be helpful to check out our previous articles on <a href="/blog/graphql-scalars-and-their-input-and-result-coercion" title="Built-in scalars">built-in scalars</a> as well as the one on <a title="Input object type" href="/blog/input-object-type-as-an-argument-for-graphql-mutations-and-queries">input object</a> type. We use them as prerequisites for this article in terms of understanding GraphQL, and we will also use parts of the code that we built in previous articles. In the following image we illustrate the hierarchical tree graph of the response for our queries and mutations


## Enum Types

**Enums** are basically a special type we can use to enumerate all possible values in the field. By using Enums we are adding another kind of validation to existing GraphQL schema. The specified values of the Enum type are the only possible options that are accepted. Now let’s go right into the implementation.
Let’s consider that in our **Task** type we also define Enum for the task **state**. We design this enum type with the consideration that a given task can have one of three states:
* **ASSIGNED**;
* **UNASSIGNED**;
* **IN_PROGRESS**;

In the GraphQL query language we can write it in the following form
``` graphql { "github": "https://github.com/atherosai/graphql-gateway-apollo-express/blob/master/server/schema/sdl-schema.graphql", "title": "Task state enum defined with SDL" }
enum TaskStateEnum {
    ASSIGNED
    UNASSIGNED
    IN_PROGRESS
}
```
It is common good practice to label enum values as capitalized values. In GraphQL language, these values are automatically mapped to the name of the value. However, when we rewrite the **TaskStateEnum** with <a href="https://github.com/graphql/graphql-js">graphql-js</a>, we can also write the enum type in the following form:
``` javascript { "github": "https://github.com/atherosai/graphql-gateway-apollo-express/blob/master/server/schema/tasks/TaskStateEnumType.ts", "title": "TaskStateEnum built with graphql-js" }
import {
    GraphQLEnumType,
} from 'graphql';

const TaskStateEnumType = new GraphQLEnumType({
    name: 'TaskStateEnum',
    values: {
        ASSIGNED: {
            value: 0,
        },
        UNASSIGNED: {
            value: 1,
        },
        IN_PROGRESS: {
            value: 2,
        },
    },
});

export default TaskStateEnumType
```
The enum class allows us to map enum values to internal values represented by integers (or different strings etc.). By defining enumerated values to an integer leads you to design your schema in the most efficient way in terms of performance. In our case, we did not use any real database and did not send it to some more complex backend infrastructure. However, in production you will often use some monolithic or microservice architecture. It is much more efficient to send these enum values using integers, as the size is much smaller and can be transferred over the network more quickly. Also, it is more efficient to store integer values in the database.

## Including our Enum in the database

Now we can implement our defined state in our **Task** definition:
``` javascript { "github": "https://github.com/atherosai/graphql-gateway-apollo-express/blob/master/server/schema/tasks/TaskType.ts", "title": "Task type defined with graphql-js library" }
import {
    GraphQLString,
    GraphQLID,
    GraphQLObjectType,
    GraphQLNonNull,
    GraphQLInt,
    GraphQLFloat,
    GraphQLBoolean,
} from 'graphql';

import DateTime from '../custom-scalars/DateTime';
import TaskStateEnumType from './TaskStateEnumType';

const TaskType = new GraphQLObjectType({
    name: 'Task',
    fields: () => ({
        id: {
            type: new GraphQLNonNull(GraphQLID),
        },
        name: {
            type: new GraphQLNonNull(GraphQLString),
        },
        completed: {
            type: new GraphQLNonNull(GraphQLBoolean),
            defaultValue: false
        },
        state: {
            type: new GraphQLNonNull(TaskStateEnumType),
        },
        progress: {
            type: new GraphQLNonNull(GraphQLFloat),
        },
        taskPriority: {
            type: new GraphQLNonNull(GraphQLInt),
        },
        dueDate: {
            type: DateTime,
        },
        createdAt: {
            type: new GraphQLNonNull(DateTime),
        },
        updatedAt: {
            type: DateTime,
        },
    }),
});
  
export default TaskType
```

We will also use our **TaskStateEnumType** for validating input when creating task. The type called **CreateTaskInput** is defined as follows:

``` javascript { "github": "https://github.com/atherosai/graphql-gateway-apollo-express/blob/master/server/schema/tasks/CreateTaskInputType.ts", "title": "CreateTaskInput type definition" }
import {
    GraphQLString,
    GraphQLInputObjectType,
    GraphQLNonNull,
    GraphQLBoolean,
    GraphQLInt,
    GraphQLFloat,
} from 'graphql';
import TaskStateEnum from './TaskStateEnumType';
import DateTime from '../custom-scalars/DateTime';

const CreateTaskInputType = new GraphQLInputObjectType({
    name: 'CreateTaskInput',
    fields: () => ({
        name: {
            type: new GraphQLNonNull(GraphQLString),
        },
        completed: {
            type: GraphQLBoolean,
            defaultValue: false,
        },
        state: {
            type: TaskStateEnum,
            defaultValue: TaskStateEnum.getValue("ASSIGNED"),
        },
        taskPriority: {
            type: GraphQLInt,
            defaultValue: 1,
        },
        progress: {
            type: GraphQLFloat,
            defaultValue: 0,
        },
        dueDate: {
            type: DateTime,
        },
    }),
});

export default CreateTaskInputType;
```

You can also see, that we defined **defaultValue** for **state** field with in-build function called **getValue**, which is available for all Enum objects. It is a good practice to define all enumerated fields at one place and then just reuse them through the whole codebase.

All possible values for the state field are now available through introspection and can be viewed in <a href="http://localhost:8000/graphql">GraphQL Playground</a> in the **Docs tab**. The Schema can be also written in SDL:

``` graphql { "github": "https://github.com/atherosai/graphql-gateway-apollo-express/blob/master/server/schema/sdl-schema.graphql", "title": "GraphQL schema overview in SDL" }
input CreateTaskInput {
  name: String!
  completed: Boolean = false
  state: TaskStateEnum
  taskPriority: Int = 1
  progress: Float = 0
  dueDate: DateTime
}

"""CreateTaskPayload type definition"""
type CreateTaskPayload {
  task: Task!
}

"""An ISO-8601 encoded UTC date string."""
scalar DateTime

type Mutation {
  createTask(input: CreateTaskInput!): CreateTaskPayload
}

type Query {
  tasks: [Task]!
}

type Task {
  id: ID!
  name: String!
  completed: Boolean!
  state: TaskStateEnum!
  progress: Float!
  taskPriority: Int!
  dueDate: DateTime
  createdAt: DateTime!
  updatedAt: DateTime
}

enum TaskStateEnum {
  ASSIGNED
  UNASSIGNED
  IN_PROGRESS
}
```

Now let’s move on to result and input coercion for enums. If you do not know what that means, it might be useful to go through the article on <a href="/blog/graphql-scalars-and-their-input-and-result-coercion">scalars and its input and result coercion</a>, where we explain these terms.

## Result coercion for enums

If we receive a different value from the database, that is not defined in the enum type, an error is raised. For example, let’s change the value of the model **Task state** in the “in-memory” db (<a href="https://github.com/atherosai/graphql-gateway-apollo-express/blob/master/server/db/tasks-db.ts">task-db.ts</a>) to **badstate**. 

``` javascript
let tasks = [
    {
      id: '7e68efd1',
      name: 'Test task',
      completed: 0.0,
      createdAt: '2017-10-06T14:54:54+00:00',
      updatedAt: '2017-10-06T14:54:54+00:00',
      taskPriority: 1,
      progress: 55.5,
      state: "badstate",
    },
  ];

export default tasks;
```


And then execute the following query for retrieving tasks from the server:
``` graphql { "github": "https://github.com/atherosai/graphql-gateway-apollo-express/blob/master/graphql-documents/GET_TASKS.graphql", "title": "Get tasks query" }
query getTasks {
    tasks {
        id
        name
        completed
        state
        progress
        taskPriority
    }
}
```
The GraphQL server will raise the following error:
``` json
Expected a value of type ”TaskStateEnumType” but received: badstate
```
The important thing to recognize is also the fact that if we change the state from integer value 1 (UNASSIGNED) to the string value **UNASSIGNED** the GraphQL will also raises the same type of error:
``` json
Expected a value of type ”TaskStateEnumType” but received: UNASSIGNED
```

GraphQL server takes care about internal value mapping when dealing with result coercion, therefore will raise the error when no internal enum values matches the received data. If the data are matched to enumerated values, these data values are then mapped according to enum specification, e.g. 2 will be mapped to **IN_PROGRESS**. However, when we use float 1.0 as a value for the state field of the task in the “in-memory” DB. The value is then transformed to the integer 1 and GraphQL does not raise an error as the data are available in the **TaskStateEnum** specification.

## Input coercion for enums

When we deal with input coercion for enums, we have to take into account additional validation for enumerated values. The GraphQL server will check if the values for the enum field matches defined values in the schema. Therefore if we execute the following mutation for adding task with state argument **badstate**
``` graphql
mutation createTask {
  createTask(input: {name: "task with bad state", state: badstate}) {
    id
  }
}
```

the GraphQL server would raise the following error.

``` json
Argument "input" has invalid value {name: "task with bad state", state: badState}.
In field "state": Expected type "TaskStateEnumType", found badState.
```

The common error when using Enums is the execution of this **createTask** mutation

``` graphql
mutation createTask {
    createTask(input: {
      name: "Next task",
      state: "ASSIGNED"
    }) {
      task {
        id
        name
        completed
        state
        progress
        taskPriority
      }
    }
}
```
It is not always expected that we will get the following error
``` json
Argument "input" has invalid value {name: "Next task", state: "ASSIGNED"}.
In field "state": Expected type "TaskStateEnumType", found "ASSIGNED".
```

The correct way to pass enum inline arguments in GraphQL Playground is just to specify enumerated values without the
quotation
``` graphql { "github": "https://github.com/atherosai/graphql-gateway-apollo-express/blob/master/graphql-documents/CREATE_TASK.graphql", "title": "Create Task mutation" }
mutation createTask {
    createTask(input: {
      name: "Next task",
      state: ASSIGNED
    }) {
    task {
      id
      name
      completed
      state
      progress
      taskPriority
    }
  }
}
```
This is different, of course, when we specify mutations using variables, as the variable has to be written according to JSON syntax specification. When using variables the GraphQL document will look as follows:

``` graphql { "github": "https://github.com/atherosai/graphql-gateway-apollo-express/blob/master/graphql-documents/CREATE_TASK_VARIABLES.graphql", "title": "Create Task mutation with variables" }
mutation createTask($input: CreateTaskInput!) {
    createTask(input: $input) {
     task {
       id
       name
     }
   }
}
```

with this variables:

``` json
{
    "input": {
      "name": "Next task",
      "state": "ASSIGNED"
    }
}
```

## Conclusion
In GraphQL, Enum type can be used as input and output type. Enums are the great way to add additional validation constraints. We can list the values with <a href="/blog/graphql-introspection-and-introspection-queries" title="GraphQL introspection and introspection queries">introspection query</a>:

``` graphql { "github":"https://github.com/atherosai/graphql-gateway-apollo-express/blob/master/graphql-documents/ENUM_VALUES_INTROSPECTION.graphql", "title": "GraphQL introspection query enum" }
query introspectTaskStateEnumType {
    __type(name: "TaskStateEnum") {
      enumValues {
        name
      }
    }
}
```

and reuse the Enumerated types across our whole code base. 



> Did you like this post? The repository with the examples and project set-up can be cloned from <a href="https://github.com/a7v8x/express-graphql-demo/tree/feature/3-graphql-scalars">this branch</a>.
> Feel free to send any questions about the topic to <a href="mailto:david@atheros.ai">david@atheros.ai</a>.


What is GraphQL enum? When to use GraphQL enum and best practices for using it. Enums in GraphQL and its application.