What's this All About?
GraphQL is a wonderful new approach to application data and API layers that's gaining momentum. If you have not heard of it, start here (opens in a new tab) and check out GraphQL Tools docs about Custom scalars (opens in a new tab) as well.
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 (opens in a new tab), 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.
Validation Using Scalars
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.
Serialization and Parsing
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
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
Date instances directly like it is one of primitive types such as string, number and boolean.
This library was originally published as
It was created and maintained by the company
We, The Guild, took over the maintenance of that library later on (opens in a new tab).
We also like to say thank you to @adriano-di-giovanni (opens in a new tab) for being extremely generous and giving us the
graphql-scalars name on npm which was previously owned by his own library (opens in a new tab).
And thanks to excitement-engineer (opens in a new tab) for graphql-iso-date (opens in a new tab), stems (opens in a new tab) for graphql-bigint (opens in a new tab), taion (opens in a new tab) for graphql-type-json (opens in a new tab), langpavel (opens in a new tab) for GraphQLTimestamp.js (opens in a new tab), vespertilian (opens in a new tab) for Duration scalar, maxwellsmart84 (opens in a new tab) for