However, for all of GraphQL’s greatness, it is missing a couple of things that we have (and you might) find very useful in defining your schemas. Namely GraphQL has a limited set of scalar types, and we have found there are some additional scalar types that are useful in being more precise in our schemas. Thankfully, those sharp GraphQL folks provided a simple way to add new custom scalar types if needed. That’s what this package does.
GraphQL Scalars is a library of custom GraphQL scalar types for creating precise type-safe GraphQL schemas.
The GraphQL Specification has the
ID Scalar types by
default. Those scalar types help you identify the data and validate it before transferring it
between client and server. But you might need more specific scalars for your GraphQL application, to
help you better describe and validate your app’s data.
We don’t fault the GraphQL folks for these omissions. They have kept the core small and clean. Arguably not every project needs these additional scalar types. But we have, and now you can use them too if needed.
The primary purposes these scalars, really of all types are to:
- Communicate to users of your schema exactly what they can expect or to at least reduce
ambiguity in cases where that’s possible. For example if you have a
Persontype in your schema and that type has as field like
ageInYears, the value of that can only be null or a positive integer (or float, depending on how you want your schema to work). It should never be zero or negative.
- Run-time type checking. GraphQL helps to tighten up the contract between client and server. It does this with strong typing of the interface (or schema). This helps us have greater confidence about what we’re receiving from the server and what the server is receiving from the client.
This package adds to the base options available in GraphQL to support types that are reasonably common in defining schemas or interfaces to data.
For example, you have a
String field, but you need to validate upcoming or ongoing string data
using regular expressions. So you should have this validation on each end; one in the client, the
other one in the server and maybe there is another on a source. Instead of duplicating the same
logic in different parts of the project, you can use
EmailAddress scalar type that does the
validation inside GraphQL for you.
The other benefit of using GraphQL scalar types is parsing and serializing while transferring data.
For example, you have
DateTime data, but it is transferred as
String due to restrictions of
JSON, and each time you receive and pass the data, you have to parse the string and create a
Date instance while also serializing it to string before passing it to the client.
Instead of having that logic in your implementation, you can just use
DateTime scalar, and you
Date instances directly like it is one of primitive types such
as string, number and boolean.
This library was originally published as
@okgrow/graphql-scalars. It was created and maintained by
ok-grow. We, The Guild, took over the maintenance of that library
And thanks to excitement-engineer for
stems for graphql-bigint,
vespertilian for Duration scalar,