Adding Custom Scalars: Handling Dates in GraphQL

Previously in this course, we discussed Organizing Schema Files to maintain a clean codebase. While the built-in primitives covered in our Introduction to GraphQL Scalars are sufficient for most tasks, real-world data often requires more nuance.

Today, we move beyond standard types by implementing custom scalars. This allows us to define complex validation and formatting rules for specific fields, such as ensuring a Date string is always a valid ISO-8601 timestamp.

Why Custom Scalars?

GraphQL ships with five built-in scalars: String, Int, Float, Boolean, and ID. Sometimes, however, you need to represent a type that doesn't map perfectly to these primitives.

A Date is the classic example. In JSON, dates are almost always strings. However, if your API returns a "date," you likely want to enforce that it is a valid format rather than a random string of text. Custom scalars allow you to intercept data at the "boundary" of your GraphQL server, validating or transforming it before it ever hits your resolvers.

Defining and Implementing a Custom Scalar

To add a custom scalar, we follow a three-step process:

1. Declare it in your SDL: Tell GraphQL a new scalar type exists.
2. Define the Resolver: Create a GraphQLScalarType object with specific logic.
3. Register it: Add the scalar to your server configuration.

The Code Implementation

We'll use the graphql package to create a Date scalar. This scalar will ensure that any input marked as Date is a valid JavaScript Date object or string representation.

JAVASCRIPT
// scalars/DateScalar.js
const { GraphQLScalarType, Kind } = require(CE9178">'graphql');

const dateScalar = new GraphQLScalarType({
  name: CE9178">'Date',
  description: CE9178">'A custom scalar for ISO date strings',
  
  // Serialize: Data from your API to the Client
  serialize(value) {
    return value.toISOString(); // Convert Date object to ISO string
  },
  
  // ParseValue: Input variable from the Client
  parseValue(value) {
    return new Date(value); // Convert string input to Date object
  },
  
  // ParseLiteral: Hardcoded values in the query
  parseLiteral(ast) {
    if (ast.kind === Kind.STRING) {
      return new Date(ast.value);
    }
    return null;
  }
});

module.exports = dateScalar;

Understanding the Logic

• serialize: This runs when your server sends data back to the client. If your database stores a date as a JavaScript Date object, this function ensures it gets sent over the network as a clean ISO-8601 string.
• parseValue: This runs when the client sends a variable (e.g., in a mutation). It converts the incoming string into a format your business logic can easily use.
• parseLiteral: This handles "hardcoded" values directly in your GraphQL query string. It ensures that if a developer writes createdAt: "2023-10-27", the server can parse that raw AST node into a Date.

Hands-on Exercise

1. Add scalar Date to your typeDefs.
2. Update one of your existing object types (like a Post or User) to use the Date type instead of String for a field like createdAt.
3. Import your dateScalar into your resolvers map and add it alongside your other resolvers:

   JAVASCRIPT
   const resolvers = {
     Date: dateScalar,
     Query: { ... }
   };
   

Common Pitfalls

• Returning null on failure: In parseLiteral, if the input isn't a string, returning null tells GraphQL the input is invalid, triggering an automatic error. Don't skip these checks.
• Over-engineering: Don't use custom scalars for every validation rule. As we learned in Validating Inputs, standard schema validation is often enough for simple tasks. Reserve custom scalars for data types that require structural transformation.
• Performance: Keep your serialization logic lean. These functions run on every request for every field using that scalar; avoid expensive computations inside them.

FAQ

Q: Can I use custom scalars to validate email addresses? A: Yes! You could create an Email scalar that uses a Regex inside parseValue to ensure the input follows email formatting.

Q: Does every scalar need serialize, parseValue, and parseLiteral? A: Yes, these are the three pillars of a custom scalar that ensure your API remains consistent regardless of how the client provides the data.

Recap

Custom scalars provide a powerful way to extend your schema's type system. By implementing serialize, parseValue, and parseLiteral, you ensure that specific data types like Date are handled consistently across your entire application. This keeps your resolvers focused on business logic rather than format conversion.

Up next: We will secure our API by implementing Middleware and Authentication to protect sensitive resolvers.