@okgrow/graphql-scalars
A library of custom GraphQL scalar types for creating precise type-safe GraphQL schemas.
Installation
npm install --save @okgrow/graphql-scalars
or
yarn add @okgrow/graphql-scalars
Usage
To use these scalars you'll need to add them in two places, your schema and your resolvers map.
NOTE: The new RegularExpression
scalar will be used a little differently and is explained below.
In your schema:
scalar DateTime
scalar NonPositiveInt
scalar PositiveInt
scalar NonNegativeInt
scalar NegativeInt
scalar NonPositiveFloat
scalar PositiveFloat
scalar NonNegativeFloat
scalar NegativeFloat
scalar EmailAddress
scalar URL
scalar PhoneNumber
scalar PostalCode
In your resolver map, first import them:
import {
DateTime,
NonPositiveInt,
PositiveInt,
NonNegativeInt,
NegativeInt,
NonPositiveFloat,
PositiveFloat,
NonNegativeFloat,
NegativeFloat,
EmailAddress,
URL,
PhoneNumber,
PostalCode,
} from '@okgrow/graphql-scalars';
Then make sure they're in the root resolver map like this:
const myResolverMap = {
DateTime,
NonPositiveInt,
PositiveInt,
NonNegativeInt,
NegativeInt,
NonPositiveFloat,
PositiveFloat,
NonNegativeFloat,
NegativeFloat,
EmailAddress,
URL,
PhoneNumber,
PostalCode,
Query: {
// more stuff here
},
Mutation: {
// more stuff here
},
};
NOTE: NonNegativeFloat
and NonNegativeInt
are also available under the aliases UnsignedFloat
and UnsignedInt
, respectively.
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
phoneNumber: PhoneNumber
homePostalCode: PostalCode
}
These scalars can be used just like the base, built-in ones.
Using the RegulareExpression scalar
First an explanation: To create a new scalar type to the GraphQL schema language, you must create an
instance of a new GraphQLScalarType
object that implements three general functions/methods:
serialize
, parseValue
and parseLiteral
which are used at different stages of processing your
GraphQL types during queries and mutations. So creating a new scalar looks like this:
const MyScalar = new GraphQLScalarType({
'MyScalar',
description: 'A description of my scalar',
serialize(value) {
// ...
return value;
},
parseValue(value) {
// ...
return value;
},
parseLiteral(ast) {
// ...
return ast.value;
}
});
Given this, if we want to create a new type that is essentially the same except for one little
customizable aspect (e.g., a regular expression type that has all the same code except the regex is
different) then we need to dynamically generate a new GraphQLScalarType
object given some
parameters. That's the approach we take here.
Therefore the RegularExpression
scalar type is really a GraphQLScalarType
object generator
that takes two arguments:
- a name
- the regex you want it to use
So to create a new scalar for a given regex, you will do this:
const MyRegexType = new RegexType('MyRegexType', /^ABC$/);
Now MyRegexType
is your new GraphQL scalar type that will enforce a value of, in this case, "ABC".
Add your new scalar type to your esolver map:
export default {
MyRegexType,
};
And to your schema:
scalar MyRegexType
That's it. Now you can use MyRegexType
as a type in the rest of your schema.
Why?
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
Person
type in your schema and that type has as field likeageInYears
, 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.
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()
.
NonPositiveInt
Integers that will have a value of 0 or less. Uses parseInt()
.
PositiveInt
Integers that will have a value greater than 0. Uses parseInt()
.
NegativeInt
Integers that will have a value less than 0. Uses parseInt()
.
NonNegativeFloat
Floats that will have a value of 0 or more. Uses parseFloat()
.
NonPositiveFloat
Floats that will have a value of 0 or less. Uses parseFloat()
.
PositiveFloat
Floats that will have a value greater than 0. Uses parseFloat()
.
NegativeFloat
Floats that will have a value less 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.
PhoneNumber
A field whose value conforms to the standard E.164 format as specified in
E.164 specification. Basically this is +17895551234
.
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.
PostalCode
We're going to start with a limited set as suggested here and here.
Which gives us the following countries:
- US - United States
- UK - United Kingdom
- DE - Germany
- CA - Canada
- FR - France
- IT - Italy
- AU - Australia
- NL - Netherlands
- ES - Spain
- DK - Denmark
- SE - Sweden
- BE - Belgium
- IN - India
This is really a practical decision of weight (of the package) vs. completeness.
In the future we might expand this list and use the more comprehensive list found here.
RegularExpression
A GraphQLScalarType
object generator that takes two arguments:
name
- The name of your custom typeregex
- The regex to be used to check against any values for fields with this new type
const MyRegexType = new RegexType('MyRegexType', /^ABC$/);
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.