graphql-scalars

What is graphql-scalars?

The graphql-scalars npm package provides a collection of custom GraphQL scalar types for common use cases not covered by the default GraphQL specification. These scalars help in validating and parsing data types such as DateTime, Email, URL, and more, making it easier to handle various data formats in a GraphQL API.

What are graphql-scalars's main functionalities?

DateTime Scalar

The DateTime scalar type is used to handle ISO 8601 date and time strings. This is useful for ensuring that date and time values are properly formatted and validated.

const { DateTimeResolver } = require('graphql-scalars');

const typeDefs = gql`
  scalar DateTime

  type Event {
    id: ID!
    name: String!
    date: DateTime!
  }
`;

const resolvers = {
  DateTime: DateTimeResolver,
};

Email Scalar

The Email scalar type is used to validate email addresses. This ensures that any email address provided in the GraphQL API is in a valid format.

const { EmailAddressResolver } = require('graphql-scalars');

const typeDefs = gql`
  scalar EmailAddress

  type User {
    id: ID!
    email: EmailAddress!
  }
`;

const resolvers = {
  EmailAddress: EmailAddressResolver,
};

URL Scalar

The URL scalar type is used to validate URLs. This ensures that any URL provided in the GraphQL API is in a valid format.

const { URLResolver } = require('graphql-scalars');

const typeDefs = gql`
  scalar URL

  type Website {
    id: ID!
    url: URL!
  }
`;

const resolvers = {
  URL: URLResolver,
};

JSON Scalar

The JSON scalar type is used to handle arbitrary JSON objects. This is useful for fields that need to store complex data structures.

const { JSONResolver } = require('graphql-scalars');

const typeDefs = gql`
  scalar JSON

  type Config {
    id: ID!
    settings: JSON!
  }
`;

const resolvers = {
  JSON: JSONResolver,
};

Other packages similar to graphql-scalars

graphql-type-json

The graphql-type-json package provides a JSON scalar type for GraphQL. It allows you to use JSON objects as scalar values in your GraphQL schema. Compared to graphql-scalars, it focuses solely on JSON handling and does not provide other custom scalar types.

graphql-iso-date

The graphql-iso-date package provides ISO 8601 compliant date/time scalar types for GraphQL. It includes Date, Time, and DateTime scalars. Compared to graphql-scalars, it is more specialized in handling date and time formats but does not offer other scalar types like Email or URL.

graphql-custom-types

The graphql-custom-types package offers a set of custom scalar types for GraphQL, including DateTime, Email, and URL. It is similar to graphql-scalars in terms of the types it provides, but it may have different implementations and additional features.

README

graphql-scalars

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

Installation

npm install --save graphql-scalars

or

yarn add 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 EmailAddress

scalar NegativeFloat

scalar NegativeInt

scalar NonNegativeFloat

scalar NonNegativeInt

scalar NonPositiveFloat

scalar NonPositiveInt

scalar PhoneNumber

scalar PositiveFloat

scalar PositiveInt

scalar PostalCode

scalar RegularExpression

scalar UnsignedFloat

scalar UnsignedInt

scalar URL

In your resolver map, first import them:

import {
  DateTime,
  NonPositiveInt,
  PositiveInt,
  NonNegativeInt,
  NegativeInt,
  NonPositiveFloat,
  PositiveFloat,
  NonNegativeFloat,
  NegativeFloat,
  EmailAddress,
  URL,
  PhoneNumber,
  PostalCode,
} from '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 '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.

Usage with Apollo Server

import { ApolloServer } from 'apollo-server';
import { makeExecutableSchema } from 'graphql-tools';
// import all scalars and resolvers
import OKGGraphQLScalars, {
  OKGScalarDefinitions,
} from 'graphql-scalars';
// Alternatively, import individual scalars and resolvers
// import { DateTime, DateTimeScalar, ... } from "graphql-scalars"

const server = new ApolloServer({
  schema: makeExecutableSchema({
    typeDefs: [
      // use spread syntax to add scalar definitions to your schema
      ...OKGScalarDefinitions,
      // DateTimeScalar,
      // ...
      // ... other type definitions ...
    ],
    resolvers: {
      // use spread syntax to add scalar resolvers to your resolver map
      ...OKGGraphQLScalars,
      // DateTime,
      // ...
      // ... remainder of resolver map ...
    },
  }),
});

server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});

Using the RegularExpression 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 RegularExpression('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 resolver 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.

RegularExpression options

There is an optional third options argument to the RegularExpression constructor that can be used like this:

const options = {
  errorMessage: (regex, value) => {
    if (process.env.NODE_ENV === 'production')
      return `Value is invalid format: ${value} `;
    else
      return `Value does not match the regular expression ${regex}: ${value}`;
  },
};

const MyRegexType = new RegularExpression('MyRegexType', /^ABC$/, options);

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().

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

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 type
• regex - The regex to be used to check against any values for fields with this new type

const MyRegexType = new RegularExpression('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.

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