Skip to main content

Introduction

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 and check out GraphQL Tools docs Custom scalars also.

However, for all of GraphQL's greatness. It is missing a couple 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 Int, Float, String, Boolean and 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.

NOTE: 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.

Why?#

The primary purposes these scalars, really of all types are to:

  1. 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 Person type 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.
  2. 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 String due to restrictions of JSON, and each time you receive and pass the data, you have to parse the string and create a JavaScript 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 would work with native JavaScript Date instances directly like it is one of primitive types such as string, number and boolean.

Thanks#

This library was originally published as @okgrow/graphql-scalars. It was created and maintained by the company ok-grow. We, The Guild, took over the maintenance of that library later on.

We also like to say thank you to @adriano-di-giovanni for being extremely generous and giving us the graphql-scalars name on npm which was previously owned by his own library.

And thanks to excitement-engineer for graphql-iso-date, stems for graphql-bigint, taion for graphql-type-json, langpavel for GraphQLTimestamp.js, vespertilian for Duration scalar, maxwellsmart84 for NonEmptyString scalar