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

Custom scalars for GraphQL.

Currently available scalars:

• GraphQLDate
• GraphQLEmailAddress
• GraphQLURL

Installation

npm install graphql-scalars --save

GraphQLDate

This custom scalar for GraphQL parses any integer, float, string or date value to javascript dates.

GraphQLDate uses new Date() to parse values so, please refer to the documentation for more details.

GraphQLDate serializes dates to ISO 8601 strings.

Usage

import {
  graphql,
  GraphQLObjectType,
  GraphQLSchema
} from 'graphql'

import { GraphQLDate } from 'graphql-scalars'

const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'RootQuery',
    fields: {
      createdAt: {
        type: GraphQLDate,
        resolve () {
          // Resolver can return an integer, string or date value.
          // The following return values all resolve to the same date.
          // `return 262915200000`
          // `return '1978-05-02'`
          // `return '1978-05-02T00:00:00.000Z'`
          return new Date('1978-05-02')
        }
      }
    }
  }),
  mutation: new GraphQLObjectType({
    name: 'RootMutation',
    fields: {
      setCreatedAt: {
        type: GraphQLDate,
        args: {
          createdAt: {
            type: GraphQLDate
          }
        },
        resolve (source, { createdAt }) {
          // `createdAt` is a javascript date
          return createdAt
        }
      }
    }
  })
})

const query = `
  {
    createdAt
  }
`

graphql(schema, query)
  .then(result => {
    const isoString = result.data.createdAt
    console.log(isoString) // 1978-05-02T00:00:00.000Z
  })

// literals for GraphQLDate can be any integer or string value
// `setCreatedAt(createdAt:262915200000)`
// `setCreatedAt(createdAt:"1978-05-02")`
// `setCreatedAt(createdAt:"1978-05-02T00:00:00.000Z")`
const mutation = `
  mutation {
    setCreatedAt(createdAt:"1978-05-02")
  }
`

graphql(schema, query)
  .then(result => {
    const isoString = result.data.createdAt
    console.log(isoString) // 1978-05-02T00:00:00.000Z
  })

GraphQLEmailAddress

GraphQLEmailAddress uses the regular expression as per HTML5 specification to validate input email addresses.

GraphQLURL

GraphQLURL uses the regular expression by Diego Perini.

License

graphql-scalars is MIT-licensed.