@okgrow/graphql-scalars

@okgrow/graphql-scalars

A library of custom GraphQL scalar types for creating precise type-safe GraphQL schemas.

Installation

npm install --save @okgrow/graphql-scalars

Usage

To use these scalars you'll need to add them in two places, your schema and your resolvers map.

In your schema:

scalar DateTime

scalar PositiveInt
scalar NonNegativeInt
scalar PositiveFloat
scalar NonNegativeFloat

scalar EmailAddress
scalar URL

In your resolver map, first import them:

import {
  DateTime,
  PositiveInt,
  PositiveFloat,
  NonNegativeFloat,
  EmailAddress,
  URL,
} from '@okgrow/graphql-scalars';

Then make sure they're in the root resolver map like this:

const myResolverMap = {
  DateTime,

  PositiveInt,
  NonNegativeInt,
  PositiveFloat,
  NonNegativeFloat,

  EmailAddress,
  URL,

  Query: {
    // more stuff here
  },

  Mutation: {
    // more stuff here
  },
}

Alternatively, use the default import and ES6's spread operator syntax:

import OKGGraphQLScalars from '@okgrow/graphql-scalars';

Then make sure they're in the root resolver map like this:

const myResolverMap = {
  ...OKGGraphQLScalars,

  Query: {
    // more stuff here
  },

  Mutation: {
    // more stuff here
  },
}

That's it. Now you can use these scalar types in your schema definition like this:

type Person {
  birthDate: DateTime
  ageInYears: PositiveInt

  heightInInches: PositiveFloat

  minimumHourlyRate: NonNegativeFloat

  currentlyActiveProjects: NonNegativeInt

  email: EmailAddress
  homePage: URL
}

These scalars can be used just like the base, built-in ones.

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.

The Types

DateTime

Use real JavaScript Dates for GraphQL fields. Currently you can use a String or an Int (e.g., a timestamp in milliseconds) to represent a date/time. This scalar makes it easy to be explicit about the type and have a real JavaScript Date returned that the client can use without doing the inevitable parsing or conversion themselves.

NonNegativeInt

Integers that will have a value of 0 or more. Uses parseInt().

PositiveInt

Integers that will have a value greater than 0. Uses parseInt().

NonNegativeFloat

Floats that will have a value of 0 or more. Uses parseFloat().

PositiveFloat

Floats that will have a value greater than 0. Uses parseFloat().

EmailAddress

A field whose value conforms to the standard internet email address format as specified in RFC822.

URL

A field whose value conforms to the standard URL format as specified in RFC3986.

Future

We'd like to keep growing this package, within reason, to include the scalar types that are widely required when defining GraphQL schemas. We welcome both suggestions and pull requests. A couple of ideas we're considering are:

• NegativeInt
• NegativeFloat

These are easy to add, we just haven't run into cases for them yet.

• PhoneNumber
• PostalCode

These both have challenges in terms of making them globally useful so they need a bit of thought.

For PhoneNumber we can probably just use the E.164 specification which is simply [phone]. The very powerful libphonenumber library is available to take that format, parse and display it in whatever display format you want. It can also be used to parse user input and get the E.164 format to pass into a schema.

Postal codes are a bit more involved. But, again, it's probably just a really long regex.

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 Apollo 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.

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.

License

Released under the MIT license.

Contributing

Issues and Pull Requests are always welcome. Please read our contribution guidelines.