GraphQL

How to Resolve Nested Queries in Apollo Server

Published May 17, 2023

Updated May 30, 2023

6 min read

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

When working with relational data, there will be times when you will need to access information within nested queries. But how would this work within the context of Apollo Server?

In this article, we will take a look at a few code examples that explore different solutions on how to resolve nested queries in Apollo Server. I have included all code examples in CodeSandbox if you are interested in trying them out on your own.

Prerequisites

This article assumes that you have a basic knowledge of GraphQL terminology.

How to resolve nested queries: An approach using resolvers and the filter method
A refactored approach using Data Loaders and Data Sources
Resolving nested queries when microservices are involved
Conclusion

How to resolve nested queries: An approach using resolvers and the filter method

In this first example, we are going to be working with two data structures called musicBrands and musicAccessories. musicBrands is a collection of entities consisting of id and name. musicAccessories is a collection of entities consisting of the product name, price, id and an associated brandId. You can think of the brandId as a foreign key that connects the two database tables.

We also need to set up the schemas for the brands and accessories.

const typeDefs = gql`
  scalar USCurrency

  type MusicBrand {
    id: ID!
    brandName: String
  }

  type MusicAccessories {
    id: ID!
    product: String
    price: USCurrency
    brandId: Int
    brand: MusicBrand
  }

  type Query {
    accessories: [MusicAccessories]
  }
`;

The next step is to set up a resolver for our Query to return all of the music accessories.

const resolvers = {
  Query: {
    accessories: () => musicAccessories,
  },
};

When we run the following query and start the server, we will see this JSON output:

query Query {
  accessories {
    product
    brand {
      brandName
    }
  }
}

{
  "data": {
    "accessories": [
      {
        "product": "NS Micro Violin Tuner Standard",
        "brands": null
      },
      {
        "product": "Standard Gong Stand",
        "brands": null
      },
      {
        "product": "Black Cymbal Mallets",
        "brands": null
      },
      {
        "product": "Classic Series XLR Microphone Cable",
        "brands": null
      },
      {
        "product": "Folding 5-Guitar Stand Standard",
        "brands": null
      },
      {
        "product": "Black Deluxe Drum Rug",
        "brands": null
      }
    ]
  }
}

As you can see, we are getting back the value of null for the brands field. This is because we haven't set up that relationship yet in the resolvers.

Inside our resolver, we are going to create another query for the MusicAccessories and have the value for the brands key be a filtered array of results for each brand.

const resolvers = {
  Query: {
    accessories: () => musicAccessories,
  },
  MusicAccessories: {
    // parent represents each music accessory
   brand: (parent) => {
      const isBrandInAccessory = (brand) => brand.id === parent.brandId;
      return musicBrands.find(isBrandInAccessory);
    },
  },
};

When we run the query, this will be the final result:

query Query {
  accessories {
    product
    brand {
      brandName
    }
  }
}

{
  "data": {
    "accessories": [
      {
        "product": "NS Micro Violin Tuner Standard",
        "brands": [
          {
            "brandName": "D'Addario"
          }
        ]
      },
      {
        "product": "Standard Gong Stand",
        "brands": [
          {
            "brandName": "Zildjian"
          }
        ]
      },
      {
        "product": "Black Cymbal Mallets",
        "brands": [
          {
            "brandName": "Zildjian"
          }
        ]
      },
      {
        "product": "Classic Series XLR Microphone Cable",
        "brands": [
          {
            "brandName": "D'Addario"
          }
        ]
      },
      {
        "product": "Folding 5-Guitar Stand Standard",
        "brands": [
          {
            "brandName": "Fender"
          }
        ]
      },
      {
        "product": "Black Deluxe Drum Rug",
        "brands": [
          {
            "brandName": "Zildjian"
          }
        ]
      }
    ]
  }
}

This single query makes it easy to access the data we need on the client side as compared to the REST API approach. If this were a REST API, then we would be dealing with multiple API calls and a Promise.all which could get a little messy.

You can find the entire code in this CodeSandbox example.

A refactored approach using Data Loaders and Data Sources

Even though our first approach does solve the issue of resolving nested queries, we still have an issue fetching the same data repeatedly. Let’s look at this example query:

query MyAccessories {
  accessories {
    id
    brand {
      id
      brandName
    }
  }
}

If we take a look at the results, we are making additional queries for the brand each time we request the information. This leads to the N+1 problem in our current implementation. We can solve this issue by using Data Loaders and Data Sources.

What are Data Loaders

Data Loaders are used to batch and cache fetch requests. This allows us to fetch the same data and work with cached results, and reduce the number of API calls we have to make.

To learn more about Data Loaders in GraphQL, please read this helpful article.

How to setup a Data Source

In this example, we will be using the following packages:

We first need to create a BrandAccessoryDataSource class which will simulate the fetching of our data.

class BrandAccessoryDataSource extends DataSource {
  ...
}

We will then set up a constructor with a custom Dataloader.

 constructor() {
    super();
    this.loader = new DataLoader((ids) => {
      if (!ids.length) {
        return musicAccessories;
      }

      return musicAccessories.filter((accessory) => ids.includes(accessory.id));
    });
  }

Right below our constructor, we will set up the context and cache.

 initialize({ context, cache } = {}) {
    this.context = context;
    this.cache = cache || new InMemoryLRUCache();
  }

We then want to set up the error handling and cache keys for both the accessories and brands. To learn more about how caching works with GraphQL, please read through this article.


  didEncounterError(error) {
    throw new Error(`There was an error loading data: ${error}`);
  }

  cacheKey(id) {
    return `music-acc-${id}`;
  }

  cacheBrandKey(id) {
    return `brand-acc-${id}`;
  }

Next, we are going to set up an asynchronous function called get which takes in an id. The goal of this function is to first check if there is anything in the cached results and if so return those cached results. Otherwise, we will set that data to the cache and return it. We will set the ttl(Time to Live in cache) value to 15 seconds.

  async get(id) {
    const cacheDoc = await this.cache.get(this.cacheKey(id));
    if (cacheDoc) {
      return JSON.parse(cacheDoc);
    }
    const doc = await this.loader.load(id);
    this.cache.set(this.cacheKey(id), JSON.stringify(doc), { ttl: 15 });
    return doc;
  }

Below the get function, we will create another asynchronous function called getByBrand which takes in a brand. This function will have a similar setup to the get function but will filter out the data by brand.

 async getByBrand(brand) {
    const cacheDoc = await this.cache.get(this.cacheBrandKey(brand.id));
    if (cacheDoc) {
      return JSON.parse(cacheDoc);
    }

   const musicBrandAccessories = musicAccessories.filter(
      (accessory) => accessory.brandId === brand.id
    );

    this.cache.set(
      this.cacheBrandKey(brand.id),
      JSON.stringify(musicBrandAccessories),
      { ttl: 15 }
    );

    return musicBrandAccessories;
  }

Setting up our schemas and resolvers

The last part of this refactored example includes modifying the resolvers. We first need to add an accessory key to our Query schema.

type Query {
  brands: [Brand]
  accessory(id: Int): Accessory
}

Inside the resolver, we will add the accessories key with a value for the function that returns the data source we created earlier.

  // this is the custom scalar type we added to the Accessory schema
  USCurrency,
  Query: {
    brands: () => musicBrands,
    accessory: (_, { id }, context) => context.dataSources.brandAccessories.get(id),
  },

We also need to refactor our Brand resolver to include the data source we set up earlier.

  Brand: {
    accessories: (brand, _, context) =>
      context.dataSources.brandAccessories.getByBrand(brand),
  },

Lastly, we need to modify our ApolloServer object to include the BrandAccessoryDataSource.

const server = new ApolloServer({
  typeDefs,
  resolvers,
  dataSources: () => ({ brandAccessories: new BrandAccessoryDataSource() }),
});

Here is the entire CodeSandbox example.

When the server starts up, click on the Query your server button and run the following query:

query Query {
  brands {
    id
    brandName
    accessories {
      id
      product
      price
    }
  }
}

Resolving nested queries when microservices are involved

Microservices is a type of architecture that will split up your software into smaller independent services. All of these smaller services can interact with a single API data layer. In this case, this data layer would be GraphQL. The client will interact directly with this data layer, and will consume API data from a single entry point.

You would similarly resolve your nested queries as before because, at the end of the day, there are just functions. But now, this single API layer will reduce the number of requests made by the client because only the data layer will be called. This simplifies the data fetching experience on the client side.

Conclusion

In this article, we looked at a few code examples that explored different solutions on how to resolve nested queries in Apollo Server. The first approach involved creating custom resolvers and then using the filter method to filter out music accessories by brand. We then refactored that example to use a custom DataLoader and Data Source to fix the "N+1 problem". Lastly, we briefly touched on how to approach this solution if microservices were involved.

If you want to get started with Apollo Server and build your own nested queries and resolvers using these patterns, check out our serverless-apollo-contentful starter kit!

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Jessica Wilkins
Jessica Wilkins is a classical musician turned Software Engineer. Prior to joining the tech industry, she spent her time running her own sheet music company (JDW Sheet Music) as well as performing and teaching in Los Angeles, CA. She enjoys working with React and TypeScript. She is also a prolific technical writer for freeCodeCamp.
@codergirl1991 @jdwilkin4

Introducing the New Serverless, GraphQL, Apollo Server, and Contentful Starter kit

Introducing the new Serverless, GraphQL, Apollo Server, and Contentful Starter kit The team at This Dot Labs has released a brand new starter kit which includes the Serverless Framework, GraphQL, Apollo Server and Contentful configured and ready to go. This article will walk through how to set up the new kit, the key technologies used, and reasons why you would consider using this kit. Table of Contents - How to get started setting up the kit - Generate the project - Setup Contentful access - Setting up Docker - Starting the local server - How to Create the Technology Model in Contentful - How to seed the database with demo data - How to work with the migration scripts - Technologies included in this starter kit - Why use GraphQL? - Why use Contentful? - Why use Amazon Simple Queue Service (SQS)? - Why use Apollo Server? - Why use the Serverless Framework? - Why use Redis? - Why use the Jest testing framework? - Project structure - How to deploy your application - What can this starter kit be used for? - Conclusion How to get started setting up the kit Generate the project In the command line, you will need to start the starter.dev CLI by running the npx @this-dot/create-starter command. You can then select the Serverless Framework, Apollo Server, and Contentful CMS kit and name your new project. Then you will need to cd into your new project directory and install the dependencies using the tool of your choice (npm, yarn, or pnpm). Next, you will need to Run cp .env.example .env to copy the contents of the .env.example file into the .env file. Setup Contentful access You will first need to create an account on Contentful, if you don't have one already. Once you are logged in, you will need to create a new space. From there, go to Settings -> API keys and click on the Content Management Tokens tab. Next, click on the Generate personal token button and give your token a name. Copy your new Personal Access Token, and add it to the CONTENTFUL_CONTENT_MANAGEMENT_API_TOKEN variable. Then, go to Settings -> General settings to get the CONTENTFUL_SPACE_ID. The last step is to add those CONTENTFUL_CONTENT_MANAGEMENT_API_TOKEN and CONTENTFUL_SPACE_ID values to your .env file. Setting up Docker You will first need to install Docker Desktop if you don't have it installed already. Once installed, you can start up the Docker container with the npm run infrastructure:up command. Starting the local server While the Docker container is running, open up a new tab in the terminal and run npm run dev to start the development server. Open your browser to http://localhost:3000/dev/graphql to open up Apollo server. How to Create the Technology Model in Contentful To get started with the example model, you will first need to create the model in Contentful. 1. Log into your Contentful account 2. Click on the Content Model tab 3. Click on the Design your Content Modal button if this is your first modal 4. Create a new model called Technology 5. Add three new text fields called displayName, description and url 6. Save your new model How to seed the database with demo data This starter kit comes with a seeding script that pre-populates data for the Technology Content type. In the command line, run npm run db:seed which will add three new data entries into Contentful. If you want to see the results from seeding the database, you can execute a small GraphQL query using Apollo server. First, make sure Docker, and the local server(npm run dev) are running, and then navigate to http://localhost:3000/dev/graphql. Add the following query: ` When you run the query, you should see the following output. ` How to work with the migration scripts Migrations are a way to make changes to your content models and entries. This starter kit comes with a couple of migration scripts that you can study and run to make changes to the demo Technology model. These migration scripts are located in the scripts/migration directory. To get started, you will need to first install the contentful-cli. ` You can then login to Contentful using the contentful-cli. ` You will then need to choose the Contentful space where the Technology model is located. ` If you want to modify the existing demo content type, you can run the second migration script from the starter kit. ` If you want to build out more content models using the CLI, you can study the example code in the /scripts/migrations/01-create-technology-contentType.js file. From there, you can create a new migration file, and run the above contentful space migration command. If you want to learn more about migration in Contentful, then please check out the documentation. Technologies included in this starter kit Why use GraphQL? GraphQL is a query language for your API and it makes it easy to query all of the data you need in a single request. This starter kit uses GraphQL to query the data from our Contentful space. Why use Contentful? Contentful is a headless CMS that makes it easy to create and manage structured data. We have integrated Contentful into this starter kit to make it easy for you to create new entries in the database. Why use Amazon Simple Queue Service (SQS)? Amazon Simple Queue Service (SQS) is a queuing service that allows you to decouple your components and process and store messages in a scalable way. In this starter kit, an SQS message is sent by the APIGatewayProxyHandler using the sendMessage function, which is then stored in a queue called DemoJobQueue. The SQS handler sqs-handler polls this queue, and processes any message received. ` Why use Apollo Server? Apollo Server is a production-ready GraphQL server that works with any GraphQL client, and data source. When you run npm run dev and open the browser to http://localhost:3000/dev/graphql, you will be able to start querying your Contentful data in no time. Why use the Serverless Framework? The Serverless Framework is used to help auto-scale your application by using AWS Lambda functions. In the starter kit, you will find a serverless.yml file, which acts as a configuration for the CLI and allows you to deploy your code to your chosen provider. This starter kit also includes the following plugins: - serverless-offline - allows us to deploy our application locally to speed up development cycles. - serverless-plugin-typescript - allows the use of TypeScript with zero-config. - serverless-dotenv-plugin - preloads function environment variables into the Serverless Framework. Why use Redis? Redis is an open-source in-memory data store that stores data in the server memory. This starter kit uses Redis to cache the data to reduce the API response times and rate limiting. When you make a new request, those new requests will be retrieved from the Redis cache. Why use the Jest testing framework? Jest is a popular testing framework that works well for creating unit tests. You can see some example test files under the src/schema/technology directory. You can use the npm run test command to run all of the tests. Project structure Inside the src directory, you will find the following structure: ` This given structure makes it easy to find all of the code and tests related to that specific component. This structure also follows the single responsibility principle which means that each file has a single purpose. How to deploy your application The Serverless Framework needs access to your cloud provider account so that it can create and manage resources on your behalf. You can follow the guide to get started. Steps to get started: 1. Sign up for an AWS account 2. Create an IAM User and Access Key 3. Export your AWS_ACCESS_KEY_ID & AWS_SECRET_ACCESS_KEY credentials. ` 4. Deploy your application on AWS Lambda: ` 5. To deploy a single function, run: ` To stop your Serverless application, run: ` For more information on Serverless deployment, check out this article. What can this starter kit be used for? This starter kit is very versatile, and can be used with a front-end application for a variety of situations. Here are some examples: - personal developer blog - small e-commerce application Conclusion In this article, we looked at how we can get started using the Serverless, GraphQL, Apollo Server, and Contentful Starter kit. We also looked at the different technologies used in the kit, and why they were chosen. Lastly, we looked at how to deploy our application using AWS. I hope you enjoy working with our new starter kit!...

Jun 2, 2023

7 mins

GraphQL

Efficiently Extract Object References in Shopify Storefront GraphQL API

Efficiently Extract Object References in Shopify Storefront GraphQL API Introduction So, this blog post is born out of necessity and a bit of frustration. If you're diving into the world of Shopify's Storefront API, you've probably realized that while it's powerful, extracting data in the object reference from Metadata fields or Metaobjects (in the GraphQL query) can be a bit like searching for a needle in a haystack. This complexity often arises not from the API's lack of capabilities but from the sparse and sometimes unclear documentation on this specific aspect. That's precisely why I decided to create this post. As a developer, I found myself in a situation where the documentation and community resources were either scarce or not detailed enough for the specific challenges I faced. This guide is the result of my journey - from confusion to clarity. The Situation To understand the crux of my challenge, it's essential to recognize that creating metafields and metaobjects is a common practice for those seeking a more customized and controlled experience with Shopify CMS. In my specific case, I wanted to enrich the information available for each product's vendor beyond what Shopify typically allows, which is just a single text box. I aimed to have each vendor display their name and two versions of their logo: a themed logo that aligns with my website's color scheme and an original logo for use on specific pages. The challenge emerged when I fetched a list of all vendors to display on a page. My GraphQL query for the Storefront API looked like this: ` This was when I hit a roadblock. How do I fetch a field with a more complex type than a simple text or number, like an image? To retrieve the correct data, what specific details must I include in the originalLogo and themedLogo fields? In my quest for a solution, I turned to every resource I could think of. I combed through the Storefront API documentation, searched endlessly on Stack Overflow, and browsed various tech forums. Despite all these efforts, I couldn’t find the clear, detailed answers I needed. It felt like I was looking for something that should be there but wasn’t. Solution Before diving into the solution, it's important to note that this is the method I discovered through trial and error. There might be other approaches, but I want to share the process that worked for me without clear documentation. My first step was to understand the nature of the data returned by the Storefront API. I inspected the value of a metaobject, which looked something like this: ` The key here was the gid, or global unique identifier. What stood out was that it always includes the object type, in this case, MediaImage. This was crucial because it indicated which union to use and what properties to query from this object in the Storefront API documentation. So, I modified my query to include a reference to this object type, focusing on the originalLogo field as an example: ` The next step was to consult the Storefront API documentation for MediaImage at Shopify API Documentation. Here, I discovered the image field within MediaImage, an object containing the url field. With this information, I updated my query: ` Finally, when executing this query, the output for a single object was as follows: ` Through this process, I successfully extracted the necessary data from the object references in the metafields, specifically handling more complex data types like images. Conclusion In wrapping up, it's vital to emphasize that while this guide focused on extracting MediaImage data from Shopify's Storefront API, the methodology I've outlined is broadly applicable. The key is understanding the structure of the gid (global unique identifier) and using it to identify the correct object types within your GraphQL queries. Whether you're dealing with images or any other data type defined in Shopify's Storefront API, this approach can be your compass. Dive into the API documentation, identify the object types relevant to your needs, and adapt your queries accordingly. It's a versatile strategy that can be tailored to suit many requirements. Remember, the world of APIs and e-commerce is constantly evolving, and staying adaptable and resourceful is crucial. This journey has been a testament to the power of perseverance and creative problem-solving in the face of technical challenges. May your ventures into Shopify's Storefront API be equally rewarding and insightful....

Mar 29, 2024

4 mins

GraphQLShopify

How to Discover API Signatures and Verify Callers Using the Stripe API

When you are working with sensitive data like customer payment information or login credentials, you will want to ensure that the data you are receiving from the backend is properly authenticated. API signature verification will check for proper authentication and help ensure that it has not been tampered with. In this article, we will learn how API signatures work, and look at an example using the Stripe API within Stripe Apps. Prerequisites: This article will assume that you have a basic working knowledge of the fetch API, JavaScript, Node, and Express. We are also going to be looking at an example using Stripe Apps. I encourage you to create a Stripe account if you are interested in trying out some of the examples on your own. API signatures and hashing algorithms When an API request is made, an unique digital signature is created. These signatures use a hashing algorithm which takes the inputted data and converts it to a fixed length string of enciphered data. Popular forms of hashing algorithms include the Secure Hash Algorithm (SHA), and the (Rivest-Shamir-Adleman)(RSA) algorithm. Here is a basic example of using the HMAC-SHA1 hash algorithm with Node.js. ` Third party APIs like PayPal or Stripe have their own verification methods and libraries that use these popular hashing algorithms underneath the hood. Let's take a look at an example where we will create a fetch call with an API signature using Stripe's fetchStripeSignature and verify the request on the backend using the verifyHeader method. How to use Stripe's fetchStripeSignature in the frontend Before we make a fetch call, we will need to first get a Stripe signature. Within Stripe's Extensions SDK, we will need to import the fetchStripeSignature function. This function will create a signature that we will use to send to the backend for verification. ` We are now going to start setting up our fetch request with the POST method. ` Within the headers object, we are going to invoke the fetchStripeSignature function and add it as a value to the 'Stripe-Signature' key. We are also going to set the content type to JSON. ` For the body, we are going to add the user and account IDs because Stripe signatures, by default, are signed with those IDs. We are also going to use the JSON.stringify method to ensure that we are working with a JSON string. ` In order to get the user and account IDs, Stripe Apps has a userContext object which comes from the ExtensionContextValue. To learn more, please visit the Stripe Extensions API reference page. How to verify the request on the backend using the verifyHeader method Now that we have made our fetch call on the frontend, we now need to verify that data on the backend. We first need to import the Stripe API, and add our Stripe API key and secret. These API keys are used to help authenticate the request and can be found on your Stripe Developer Dashboard. It is a best practice to place your API keys in an .env file like this: ` Then you can access those keys use process.env. ` Then we are going to setup a small Express sever. ` Within our post, we need to setup the request to get the Stripe signature header. ` Next, we need to request the user and account ids. ` We are now going to setup a try catch block and first try to verify the signature for its authenticity. If it is not a valid signature, then we will setup an error message and add a 400 status code in the catch block. For the verification, we are going to use Stripe's verifyHeader method and pass in the account IDs, Stripe signature, and the Stripe API secret key. ` At the bottom of our post function, we are going to return the JSON response. ` Conclusion In this article, we learned about API signatures and how it uses popular hashing algorithms underneath the hood. We then looked at an example using the Stripe API within the Stripe Apps platform. We first setup a frontend fetch call using the POST method and created a Stripe signature using the fetchStripeSignature function. Then, we verified that signature on the backend using the verifyHeader method. I hope you enjoyed this article and best of luck on your programming journey....

Dec 2, 2022

3 mins

JavaScript

Introduction to Zod for Data Validation

As web developers, we're often working with data from external sources like APIs we don't control or user inputs submitted to our backends. We can't always rely on this data to take the form we expect, and we can encounter unexpected errors when it deviates from expectations. But with the Zod library, we can define what our data ought to look like and parse the incoming data against those defined schemas. This lets us work with that data confidently, or to quickly throw an error when it isn't correct. Why use Zod? TypeScript is great for letting us define the shape of our data in our code. It helps us write more correct code the first time around by warning us if we are doing something we shouldn't. But TypeScript can't do everything for us. For example, we can define a variable as a string or a number, but we can't say "a string that starts with user_id_ and is 20 characters long" or "an integer between 1 and 5". There are limits to how much TypeScript can narrow down our data for us. Also, TypeScript is a tool for us developers. When we compile our code, our types are not available to the vanilla JavaScript. JavaScript can't validate that the data we actually use in our code matches what we thought we'd get when we wrote our TypeScript types unless you're willing to manually write code to perform those checks. This is where we can reach for a tool like Zod. With Zod, we can write data schemas. These schemas, in the simplest scenarios, look very much like TypeScript types. But we can do more with Zod than we can with TypeScript alone. Zod schemas let us create additional rules for data parsing and validation. A 20-character string that starts with user_id_? It's z.string().startsWith('user_id_').length(20). An integer between 1 and 5 inclusive? It's z.number().int().gte(1).lte(5). Zod's primitives give us many extra functions to be more specific about *exactly* what data we expect. Unlike TypeScript, Zod schemas aren't removed on compilation to JavaScript—we still have access to them! If our app receives some data, we can verify that it matches the expected shape by passing it to your Zod schema's parse function. You'll either get back your data in exactly the shape you defined in your schema, or Zod will give you an error to tell you what was wrong. Zod schemas aren't a replacement for TypeScript; rather, they are an excellent complement. Once we've defined our Zod schema, it's simple to derive a TypeScript type from it and to use that type as we normally would. But when we really need to be sure our data conforms to the schema, we can always parse the data with our schema for that extra confidence. Defining Data Schemas Zod schemas are the variables that define our expectations for the shape of our data, validate those expectations, and transform the data if necessary to match our desired shape. It's easy to start with simple schemas, and to add complexity as required. Zod provides different functions that represent data structures and related validation options, which can be combined to create larger schemas. In many cases, you'll probably be building a schema for a data object with properties of some primitive type. For example, here's a schema that would validate a JavaScript object representing an order for a pizza: ` Zod provides a number of primitives for defining schemas that line up with JavaScript primitives: string, number, bigint, boolean, date, symbol, undefined, and null. It also includes primitives void, any, unknown, and never for additional typing information. In addition to basic primitives, Zod can define object, array, and other native data structure schemas, as well as schemas for data structures not natively part of JavaScript like tuple and enum. The documentation contains considerable detail on the available data structures and how to use them. Parsing and Validating Data with Schemas With Zod schemas, you're not only telling your program what data should look like; you're also creating the tools to easily verify that the incoming data matches the schema definitions. This is where Zod really shines, as it greatly simplifies the process of validating data like user inputs or third party API responses. Let's say you're writing a website form to register new users. At a minimum, you'll need to make sure the new user's email address is a valid email address. For a password, we'll ask for something at least 8 characters long and including one letter, one number, and one special character. (Yes, this is not really the best way to write strong passwords; but for the sake of showing off how Zod works, we're going with it.) We'll also ask the user to confirm their password by typing it twice. First, let's create a Zod schema to model these inputs: ` So far, this schema is pretty basic. It's only making sure that whatever the user types as an email is an email, and it's checking that the password is at least 8 characters long. But it is *not* checking if password and confirmPassword match, nor checking for the complexity requirements. Let's enhance our schema to fix that! ` By adding refine with a custom validation function, we have been able to verify that the passwords match. If they don't, parsing will give us an error to let us know that the data was invalid. We can also chain refine functions to add checks for our password complexity rules: ` Here we've chained multiple refine functions. You could alternatively use superRefine, which gives you even more fine grained control. Now that we've built out our schema and added refinements for extra validation, we can parse some user inputs. Let's see two test cases: one that's bound to fail, and one that will succeed. ` There are two main ways we can use our schema to validate our data: parse and safeParse. The main difference is that parse will throw an error if validation fails, while safeParse will return an object with a success property of either true or false, and either a data property with your parsed data or an error property with the details of a ZodError explaining why the parsing failed. In the case of our example data, userInput2 will parse just fine and return the data for you to use. But userInput1 will create a ZodError listing all of the ways it has failed validation. ` ` We can use these error messages to communicate to the user how they need to fix their form inputs if validation fails. Each error in the list describes the validation failure and gives us a human readable message to go with it. You'll notice that the validation errors for checking for a valid email and for checking password length have a lot of details, but we've got three items at the end of the error list that don't really tell us anything useful: just a custom error of Invalid input. The first is from our refine checking if the passwords match, and the second two are from our refine functions checking for password complexity (numbers and special characters). Let's modify our refine functions so that these errors are useful! We'll add our own error parameters to customize the message we get back and the path to the data that failed validation. ` Now, our error messages from failures in refine are informative! You can figure out which form fields aren't validating from the path, and then display the messages next to form fields to let the user know how to remedy the error. ` By giving our refine checks a custom path and message, we can make better use of the returned errors. In this case, we can highlight specific problem form fields for the user and give them the message about what is wrong. Integrating with TypeScript Integrating Zod with TypeScript is very easy. Using z.infer<typeof YourSchema> will allow you to avoid writing extra TypeScript types that merely reflect the intent of your Zod schemas. You can create a type from any Zod schema like so: ` Using a TypeScript type derived from a Zod schema does *not* give you any extra level of data validation at the type level beyond what TypeScript is capable of. If you create a type from z.string.min(3).max(20), the TypeScript type will still just be string. And when compiled to JavaScript, even that will be gone! That's why you still need to use parse/safeParse on incoming data to validate it before proceeding as if it really does match your requirements. A common pattern with inferring types from Zod schemas is to use the same name for both. Because the schema is a variable, there's no name conflict if the type uses the same name. However, I find that this can lead to confusing situations when trying to import one or the other—my personal preference is to name the Zod schema with Schema at the end to make it clear which is which. Conclusion Zod is an excellent tool for easily and confidently asserting that the data you're working with is exactly the sort of data you were expecting. It gives us the ability to assert at runtime that we've got what we wanted, and allows us to then craft strategies to handle what happens if that data is wrong. Combined with the ability to infer TypeScript types from Zod schemas, it lets us write and run more reliable code with greater confidence....

Nov 15, 2024

7 mins

JavaScriptZod

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

How to Resolve Nested Queries in Apollo Server

Table of Contents

How to resolve nested queries: An approach using resolvers and the filter method

A refactored approach using Data Loaders and Data Sources

What are Data Loaders

How to setup a Data Source

Setting up our schemas and resolvers

Resolving nested queries when microservices are involved

Conclusion

Jessica Wilkins

You might also like

Introducing the New Serverless, GraphQL, Apollo Server, and Contentful Starter kit

Efficiently Extract Object References in Shopify Storefront GraphQL API

How to Discover API Signatures and Verify Callers Using the Stripe API

Introduction to Zod for Data Validation

Let's innovate together!

You might also like

Introducing the New Serverless, GraphQL, Apollo Server, and Contentful Starter kit

Efficiently Extract Object References in Shopify Storefront GraphQL API

How to Discover API Signatures and Verify Callers Using the Stripe API

Introduction to Zod for Data Validation