How to create a custom scalar in GraphQL

note
This note serves as my personal copypasta. Go to the "References" links at the end for more in-depth explanation.

Maybe/Someday: Summarize serialize, parseValue, and parseLiteral in my own words.

By default, GraphQL provides these scalar types: Int, Float, String, Boolean, and ID.

We can define our own custom scalar type by creating a GraphQLScalarType instance.

const { GraphQLScalarType, Kind } = require("graphql");
 
const myScalar = new GraphQLScalarType({
  // name, // required
  // description,
  // serialize, // required
  // parseValue,
  // parseLiteral,
});

API reference: https://graphql.org/graphql-js/type/#graphqlscalartype

Then we add it to the resolver map that we pass to the GraphQL server code (eg. ApolloServer).

const { ApolloServer, gql } = require("apollo-server");
const { GraphQLScalarType, Kind } = require("graphql");
 
const myScalar = new GraphQLScalarType({
  // ...
});
 
const typeDefs = gql`
  scalar MyScalar
 
  type Post {
    id: ID!
    foo: MyScalar!
  }
 
  type Query {
    posts: [post!]
  }
`;
 
const resolvers = {
  MyScalar: myScalar
  // ...other resolver definitions...
};
 
const server = new ApolloServer({ typeDefs, resolvers, csrfPrevention: true });

"Odd number" scalar example from apollographql.com and graphql-tools.com:

const { GraphQLScalarType, Kind } = require("graphql");
 
function oddValue(value) {
  return value % 2 === 1 ? value : null
}
 
const oddScalar = new GraphQLScalarType({
  name: "Odd",
  parseValue: oddValue,
  serialize: oddValue,
  parseLiteral(ast) {
    if (ast.kind === Kind.INT) {
      return oddValue(parseInt(ast.value, 10));
    }
    return null;
  }
});
 
// ... etc

Type definitions and resolver usage:

const { ApolloServer, gql } = require("apollo-server");
const { GraphQLScalarType, Kind } = require("graphql");
 
function oddValue(value) { ... } // see above
 
const oddScalar = new GraphQLScalarType({ ... }); // see above
 
const typeDefs = gql`
  scalar Odd
 
  type Query {
    # Echoes the provided odd integer
    echoOdd(odd: Odd!): Odd!
  }
`;
 
const resolvers = {
  Odd: oddScalar,
  Query: {
    echoOdd(_, { odd }) {
      return odd;
    }
  }
};
 
const server = new ApolloServer({ typeDefs, resolvers, csrfPrevention: true });

You can also import custom scalars from external library. graphql-scalars provides dozens of common scalar types such as BigInt, Date, country code, and more.

References:

In: GraphQL MOC