Graphql Scalars

A library of custom GraphQL scalar types for creating precise type-safe GraphQL schemas, with validation powered by Joi.

🔧 Installation

npm install --save graphql @saeris/graphql-scalars
# or
yarn add graphql @saeris/graphql-scalars

📦 Usage

To use these scalars you'll need to add them in two places, your schema and your resolvers map. Here is an example of how to use them with Apollo Server:

import { ApolloServer } from "apollo-server"
import { makeExecutableSchema } from "graphql-tools"
import CustomScalars, { RegularExpressionFactory } from "@saeris/graphql-scalars"
// Alternatively, import individual scalars and resolvers:
// import { DateTimeScalar, DateTime } from "@saeris/graphql-scalars"

const { scalar: MyRegexScalar, resolver: MyRegex } = RegularExpressionFactory(`MyRegex`, /^abc$/)

const server = new ApolloServer({
  schema: makeExecutableSchema({
    typeDefs: [
      ...Object.keys(CustomScalars),
      // DateTimeScalar,
      MyRegexScalar
    ],
    resolvers: {
      ...Object.values(CustomScalars),
      // DateTime,
      MyRegex
    }
  })
})

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

Now you can use them in your schema just like you would any other Type/Scalar:

type Person {
  birthDate: DateTime
  ageInYears: PositiveInt

  heightInInches: PositiveFloat

  minimumHourlyRate: NonNegativeFloat

  currentlyActiveProjects: NonNegativeInt

  email: EmailAddress
  homePage: URL

  phoneNumber: PhoneNumber
  homePostalCode: PostalCode
}

📐 Scalars

DateTime

import { DateTimeScalar, DateTime } from "@saeris/graphql-scalars"

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.

UnsignedInt

import { UnsignedIntScalar, UnsignedInt } from "@saeris/graphql-scalars"

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

NonPositiveInt

import { NonPositiveIntScalar, NonPositiveInt } from "@saeris/graphql-scalars"

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

PositiveInt

import { PositiveIntScalar, PositiveInt } from "@saeris/graphql-scalars"

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

NegativeInt

import { NegativeIntScalar, NegativeInt } from "@saeris/graphql-scalars"

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

UnsignedFloat

import { UnsignedFloatScalar, UnsignedFloat } from "@saeris/graphql-scalars"

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

NonPositiveFloat

import { NonPositiveFloatScalar, NonPositiveFloat } from "@saeris/graphql-scalars"

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

PositiveFloat

import { PositiveFloatScalar, PositiveFloat } from "@saeris/graphql-scalars"

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

NegativeFloat

import { NegativeFloatScalar, NegativeFloat } from "@saeris/graphql-scalars"

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

EmailAddress

import { EmailAddressScalar, EmailAddress } from "@saeris/graphql-scalars"

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

URL

import { URLScalar, URL } from "@saeris/graphql-scalars"

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

PhoneNumber

import { PhoneNumberScalar, PhoneNumber } from "@saeris/graphql-scalars"

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

import { PostalCodeScalar, PostalCode } from "@saeris/graphql-scalars"

A field whose value conforms to the standard Portal Code format of any of the following countries:

• US - United States
• GB - United Kingdom
• DE - Germany
• CA - Canada
• FR - France
• IT - Italy
• AU - Australia
• NL - Netherlands
• ES - Spain
• DK - Denmark
• SE - Sweden
• BE - Belgium
• IN - India

Uses joi-postalcode for validation, which uses postal-codes-js under the hood.

🏭 Factories

RegularExpressionFactory

import { RegularExpressionFactory } from "@saeris/graphql-scalars"

A GraphQLScalarType factory 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 { scalar: MyRegexScalar, resolver: MyRegexResolver } = new RegularExpressionFactory('MyRegex', /^ABC$/);

📣 Acknowledgements

This library was forked from @okgrow/graphql-scalars and uses Joi for validation.

🥂 License

Released under the MIT license.