Custom scalars and enums
The GraphQL specification includes the following default scalar types: Int
, Float
, String
, Boolean
and ID
. While this covers most of the use cases, often you need to support custom atomic data types (e.g. Date), or you want a version of an existing type that does some validation. To enable this, GraphQL allows you to define custom scalar types. Enumerations are similar to custom scalars, but their values can only be one of a pre-defined list of strings.
#
Custom scalarsTo define a custom scalar you simply add it to the schema string with the following notation:
Afterwards, you have to define the behavior of your MyCustomScalar
custom scalar by passing an instance of the GraphQLScalarType
class in the resolver map. This instance can be defined in a dependency package or in your own code.
For more information about GraphQL's type system, please refer to the official documentation or to the Learning GraphQL tutorial.
Note that most of popular GraphQL clients does not currently have a way to automatically interpret custom scalars, so there's no way to automatically reverse the serialization on the client.
#
Using a packageHere, we'll take the graphql-scalars package as an example to demonstrate what can be done. This npm package defines a JSON GraphQL scalar type.
Add the graphql-scalars
package to your project's dependencies :
In your JavaScript code, require the type defined by in the npm package and use it :
Remark : GraphQLJSON
is a GraphQLScalarType
instance.
For a set of popular scalar types that are ready to reuse, try out the GraphQL Scalars npm library.
GraphQLScalarType
instance#
Custom If needed, you can define your own GraphQLScalarType instance. This can be done the following way :
#
Custom scalar examplesLet's look at a couple of examples to demonstrate how a custom scalar type can be defined.
#
Date as a scalarThe goal is to define a Date
data type for returning Date
values from the database. Let's say we're using a MongoDB driver that uses the native JavaScript Date
data type. The Date
data type can be easily serialized as a number using the getTime()
method. Therefore, we would like our GraphQL server to send and receive Date
s as numbers when serializing to JSON. This number will be resolved to a Date
on the server representing the date value. On the client, the user can simply create a new date from the received numeric value.
The following is the implementation of the Date
data type. First, the schema:
Next, the resolver:
#
ValidationsIn this example, we follow the official GraphQL documentation for the scalar datatype. Let's say that you have a database field that should only contain odd numbers. First, the schema:
Next, the resolver:
#
EnumsAn Enum is similar to a scalar type, but it can only be one of several values defined in the schema. Enums are most useful in a situation where you need the user to pick from a prescribed list of options, and they will auto-complete in tools like GraphiQL.
In the schema language, an enum looks like this:
You can use it in your schema anywhere you could use a scalar:
Then, you query it like this:
If you want to pass the enum value as a variable, use a string in your JSON, like so:
Putting it all together:
#
Internal valuesOften, you might have a different value for the enum in your code than in the public API. So maybe in the API we call it RED
, but inside our resolvers we want to use #f00
instead. That's why you can use the resolvers
argument to makeExecutableSchema
to add custom values to your enum that only show up internally:
These don't change the public API at all, but they do allow you to use that value instead of the schema value in your resolvers, like so:
Most of the time, you don't need to use this feature of enums unless you're interoperating with some other library which already expects its values in a different form.