GraphQL

Ship Less JavaScript with GraphQL Resolvers

Jan 17, 2023

5 min read

In the past year or two, I’ve noticed a lot of folks online putting an emphasis on the size and amount of code we are shipping as JavaScript bundles in our web applications. And this makes sense. A lean JavaScript bundle is advantageous for many reasons like accessibility, mobile device/network experience, SEO, and overall speed of your web pages and applications.

There are many ways that we can reduce the size of the JavaScript bundles that we ship without sacrificing using the tools and frameworks that we’re familiar with to build high-quality websites and applications. In this article, I want to highlight some ways that we can use GraphQL and tools like Apollo Server to reduce the amount of JavaScript that gets shipped in our bundles.

This article assumes that you have some experience and familiarity with GraphQL. If you need an introduction to these concepts, check out this fantastic post from our blog: Migrating from REST to GraphQL. Otherwise, let's dig right into some different strategies and examples we can use to speed up our websites! For the sake of our examples going forward, we are going to pretend that we are working on an IMDB-like website for movies.

Defining schemas to get the most out of your API

One of the key benefits of GraphQL is the ability to define a schema that specifies the shape of the data that is available through the API. Defining a well-crafted GraphQL schema provides the ability to ship only the data that is actually needed by the client. In a REST API, it is common to fetch entire entities from a database, even if only a small portion of that data is actually needed by the client. With GraphQL, you have granular control over the data that is returned, allowing you to ship only the data that is required.

Here’s a simple example schema to describe our movie API. It includes a query to fetch a list of films, and another to fetch a list of actors. as well as the shape of those entities, that we can request some or all of the fields from, using our GraphQL API.

type Query {
  films(limit: Int): [Film]
  people(limit: Int): [Person]
}

type Film {
  title: String
  releaseDate: String
  actors: [Person]
}

type Person {
  name: String
  films: [Film]
}

Sub-query resolvers

One particularly powerful feature of GraphQL is the ability to define sub-query resolvers. This allows you to specify relationships between different types of data in your schema, allowing the client to request related data in a single query. This can greatly reduce the number of API calls needed to fetch all of the data required by the client, ultimately leading to the shipment of less JavaScript.

Based on our schema above, we can easily write a query to request a list of actors that played in a particular film.

query {
  films(limit: 5) {
    title
    actors {
      name
    }
  }
}

Our Apollo Server sub-query resolver might look something like this:

const resolvers = {
  Film: {
    actors: (film, _, { dataSources }) => dataSources.peopleAPI.getActorsByFilm(film.id),
  },
}

A quality GraphQL schema will provide more granular control to its clients, and will help prevent over-fetching of data. This is an easy way to reduce bytes sent across the wire, which will lead to improved performance in our applications.

Moving client logic ito resolvers

Resolvers are just functions that we write to fetch and aggregate the data that we defined in our schema. A simple concept that provides a powerful layer between our data sources and the contract we have defined with our GraphQL API. They are called by the GraphQL engine and are passed the arguments defined in our queries and a reference to the calling object.

Let's update our films query to accept some additional arguments:

type Query {
  films(limit: Int, title: String, year: Int, offset: Int): [Film]
}

Using the arguments defined on our films query, our client now has more control to only fetch the data they need. The limit and offset arguments that allow them to paginate the results so a single page will need to fetch and render a smaller amount of items at a time.

Here’s what our resolver might look like using these new arguments to fetch a subset of the data that is available:

const resolvers = {
  Query: {
    films: async (_, { limit, title, year, offset }, { dataSources }) => {
        return dataSources.filmAPI.getFilms({ limit, title, year, offset });
    },
  },
}

Magic Fields

Another way to use resolvers is to create "magic fields" that are single-purpose data transformations. For example, we could create a field on the Person type called latestFilm that returns the actor’s most recent film, rather than returning a list of all of the user's posts and having the client filter through them. This can save on both the amount of data shipped, and the amount of processing required by the client.

type Person {
  name: String
  films: [Film]
	latestFilm: Film
}

Transformational Resolvers

Transformational resolvers allow you to perform transformations on the data before it is returned to the client, reducing the need for complex data manipulation logic on the client side.

For example, in your film type, you can use an enum to allow the client to request the release date in different formats, such as SHORT or LONG.

enum DateFormat {
  SHORT
  LONG
}

Then, you can use this format in your film query as a variable and pass it to the releaseDate field:

query Film($id: ID!, $format: DateFormat) {
  film(id: $id) {
    id
    releaseData(format: $format)
  }
}

On the server side, you can define a resolver for the releaseData field that takes the format variable as an argument, and performs the appropriate transformation before returning the data to the client.

const resolvers = {
  Film: {
    releaseData: (film, { format }, { dataSources }) => {
        if (format === DateFormat.SHORT) {
            // Perform short format transformation
            return shortFormatDate(film.releaseDate);
        } else if (format === DateFormat.LONG) {
            // Perform long format transformation
            return longFormatDate(film.releaseDate);
        }
    },
  },
}

This way, the client can request the release date in the format they need, and the server can handle the transformation before returning the data. This reduces the amount of code needed on the client side to manipulate the data and improves the performance of the application.

It's worth noting that in some cases, it may make sense to keep some of the data manipulation logic on the client side. The goal is to find the right balance between server and client-side code, and to make sure that the code you ship to the client only contains the logic that is necessary for the user experience.

Wrapping REST APIs to leverage GraphQL features

In some cases, you may not have the ability to create a new GraphQL API from scratch. Fortunately, it is possible to wrap existing REST APIs with GraphQL using tools such as Apollo Server. This allows you to take advantage of the benefits of GraphQL, even if you don't have control over the underlying API(s).

In our movie application, instead of having our own database of films and actors we might have used the IMDB API instead. Apollo Server specifically provides us with abstractions around the data sources that we use to resolve our data from.

Conclusion

In conclusion, GraphQL is a powerful tool that can be used to ship less JavaScript to the client, resulting in improved performance for your web application. By defining well-crafted schemas, and utilizing resolvers effectively, you can reduce the amount of data shipped over the network and the amount of processing required by the client. If you are working with existing REST APIs already, you can use tools like Apollo Server to wrap them and take advantage of the benefits of GraphQL.

Whether you are building a new application or optimizing an existing one, consider using GraphQL to ship less JavaScript, and improve the performance of your app. If you want to learn more about GraphQL, check out graphql.framework.dev, our open-source library filled with curated GraphQL resources!

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.

Dane Grant

JavaScript developer building things on web, native, and server environments. Free time filled with reading, cooking, dog, sports, comedy, and music.

@danecando @danecando

Leveraging GraphQL Scalars to Enhance Your Schema

Introduction GraphQL has revolutionized the way developers approach application data and API layers, gaining well-deserved momentum in the tech world. Yet, for all its prowess, there's room for enhancement, especially when it comes to its scalar types. By default, GraphQL offers a limited set of these primitives — Int, Float, String, Boolean, and ID — that underpin every schema. While these types serve most use cases, there are scenarios where they fall short, leading developers to yearn for more specificity in their schemas. Enter graphql-scalars, a library designed to bridge this gap. By supplementing GraphQL with a richer set of scalar types, this tool allows for greater precision and flexibility in data representation. In this post, we'll unpack the potential of enhanced Scalars, delve into the extended capabilities provided by graphql-scalars, and demonstrate its transformative power using an existing starter project. Prepare to redefine the boundaries of what your GraphQL schema can achieve. Benefits of Using Scalars GraphQL hinges on the concept of "types." Scalars, being the foundational units of GraphQL's type system, play a pivotal role. While the default Scalars — Int, Float, String, Boolean, and ID — serve many use cases, there's an evident need for more specialized types in intricate web development scenarios. 1. Precision: Using default Scalars can sometimes lack specificity. Consider representing a date or time in your application with a String; this might lead to ambiguities in format interpretation and potential inconsistencies. 2. Validation: Specialized scalar types introduce inherent validation. Instead of using a String for an email or a URL, for example, distinct types ensure the data meets expected formats at the query level itself. 3. Expressiveness: Advanced Scalars provide clearer intentions. They eliminate ambiguity inherent in generic types, making the schema more transparent and self-explanatory. Acknowledging the limitations of the default Scalars, tools like graphql-scalars have emerged. By broadening the range of available data types, graphql-scalars allows developers to describe their data with greater precision and nuance. Demonstrating Scalars in Action with Our Starter Project To truly grasp the transformative power of enhanced Scalars, seeing them in action is pivotal. For this, we'll leverage a popular starter kit: the Serverless framework with Apollo and Contentful. This kit elegantly blends the efficiency of serverless functions with the power of Apollo's GraphQL and Contentful's content management capabilities. Setting Up the Starter: 1. Initialize the Project: ` 2. When prompted, name your project enhance-with-graphql-scalars. ` 3. For a detailed setup, including integrating with Contentful and deploying your serverless functions, please follow the comprehensive guide provided in the starter kit here. 4. And we add the graphql-scalars package ` Enhancing with graphql-scalars: Dive into the technology.typedefs.ts file, which is the beating heart of our GraphQL type definitions for the project. Initially, these are the definitions we encounter: ` Our enhancement strategy is straightforward: * Convert the url field from a String to the URL scalar type, bolstering field validation to adhere strictly to the URL format. Post-integration of graphql-scalars, and with our adjustments, the revised type definition emerges as: ` To cap it off, we integrate the URL type definition along with its resolvers (sourced from graphql-scalars) in the schema/index.ts file: ` This facelift doesn't just refine our GraphQL schema but infuses it with innate validation, acting as a beacon for consistent and accurate data. Testing in the GraphQL Sandbox Time to witness our changes in action within the GraphQL sandbox. Ensure your local server is humming along nicely. Kick off with verifying the list query: ` Output: ` Success! Each url in our dataset adheres to the pristine URL format. Any deviation would've slapped us with a format error. Now, let's court danger. Attempt to update the url field with a _wonky_ format: ` As anticipated, the API throws up a validation roadblock: ` For the final act, re-run the initial query to reassure ourselves that the original dataset remains untarnished. Conclusion Enhancing your GraphQL schemas with custom scalars not only amplifies the robustness of your data structures but also streamlines validation and transformation processes. By setting foundational standards at the schema level, we ensure error-free, consistent, and meaningful data exchanges right from the start. The graphql-scalars library offers an array of scalars that address common challenges developers face. Beyond the URL scalar we explored, consider diving into other commonly used scalars such as: * DateTime: Represents date and time in the ISO 8601 format. * Email: Validates strings as email addresses. * PositiveInt: Ensures integer values are positive. * NonNegativeFloat: Guarantees float values are non-negative. As a potential next step, consider crafting your own custom scalars tailored to your project's specific requirements. Building a custom scalar not only offers unparalleled flexibility but also provides deeper insights into GraphQL's inner workings and its extensibility. Remember, while GraphQL is inherently powerful, the granular enhancements like scalars truly elevate the data-fetching experience for developers and users alike. Always evaluate your project's needs and lean into enhancements that bring the most value. To richer and more intuitive GraphQL schemas!...

Nov 8, 2023

4 mins

GraphQL

How to Resolve Nested Queries in Apollo Server

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. 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 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. ` The next step is to set up a resolver for our Query to return all of the music accessories. ` When we run the following query and start the server, we will see this JSON output: ` ` 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. ` When we run the query, this will be the final result: ` ` 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: ` 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: - apollo-datasource - apollo-server-caching - dataloader We first need to create a BrandAccessoryDataSource class which will simulate the fetching of our data. ` We will then set up a constructor with a custom Dataloader. ` Right below our constructor, we will set up the context and cache. ` 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. ` 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. ` 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. ` 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. ` Inside the resolver, we will add the accessories key with a value for the function that returns the data source we created earlier. ` We also need to refactor our Brand resolver to include the data source we set up earlier. ` Lastly, we need to modify our ApolloServer object to include the BrandAccessoryDataSource. ` Here is the entire CodeSandbox example. When the server starts up, click on the Query your server button and run the following query: ` 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!...

May 17, 2023

6 mins

GraphQL

Building interactive forms with TanStack Form

TanStack Form is a new headless form library that makes building more complex and interactive forms easy. TanStack has understood the power of ‘headless’ UI libraries for quite some time with some really incredible tools like TanStack Table and TanStack Query. Given the high quality of all the other libraries in the TanStack suite, I was excited to give this new form library a try. If you’ve used react-hook-form before the two libraries have quite a bit in common. The transition should be mostly straightforward. Let's start by comparing the two libraries and bit and then dig into the TanStack Form API with some examples and code. Comparison to react-hook-form At a high level, the two libraries are pretty similar: - Headless, hook-based API - Performance (both libraries minimize amount of renders triggered by state changes) - Lightweight, zero-dependencies (TanStack 4.4kb, react-hook-form 9.7kb) - Comprehensive feature set - Type-safety / TypeScript support - Form / Input validation and schemas There are a few things that set TanStack Form apart: - UI Agnostic - TanStack Form offers support for other UI libraries and frameworks through a plugin-style system. Currently, React & Solid is supported out of the box. - Simpler API and documentation - The API surface area is a bit smaller, and the documentation makes it easy to find the details on all the APIs. - First-class TypeScript support - TanStack Form provides really impressive type inference. It stays out of your way and lets you focus on writing code instead of wrangling types. Building forms Since the API for TanStack Form is pretty small, we can walk through the important APIs pretty quickly to see how they work together to help us build interactive client-side forms. useForm(options) useForm accepts an options object that accepts defaultValues, defaultState, and event handler functions like onSubmit, onChange, etc. The types are clear, and the source code is easy to read so you can refer to FormApi.ts file for more specifics. Currently, the examples on the website don’t provide a type for the generic TData that useForm accepts. It will infer the form types based on the defaultValues that are provided, but in this example, I will provide the type explicitly. ` The API for your form is returned from the useForm hook. We will use this API to build the fields and their functionality in our component. useField(opts) If you want to abstract one of your form fields into its own component we can use the useField hook. The useField generic parameters take the type definition of your form and the field name. ` Validation is as simple as returning a string from your field onChange handler. For our password field we return an error message if the length isn’t at least 8 characters long. We bind our field states and event handlers to the form input by passing them in as props. Component API form includes a component API with a Context Provider, a component for rendering Field components, and a Subscribe component for subscribing to state changes. I’ve added the remaining fields to our form using the Field component and included our PasswordField from above. Using the Field component is similar to using the useField hook - the difference is our field instance gets passed in via a render prop. ` We wrapped our submit button with the Subscribe component which has a pretty interesting API. Subscribe allows you to subscribe to state changes granularly. Whatever state items you return from the selector gets passed into the render prop and re-render it on changes. This will be really useful in places where render performance is critical. Async event handlers We can use the built-in async handlers and debounce options to implement a search input. This feature makes a common pattern like this trivial. ` Async event handlers can be used for other things like async validation as well. We could update our email input from our create account form to check to see if the account already exists. ` Validation adapters Since this post was first written, TanStack Form has added adapters for popular schema validation libraries like Yup and Zod. The actual API for using the schemas is a little bit different then what you might be used to from react-hook-form. Instead of passing a schema definition for all of the fields to the root form API, you provide schemas for each field individually. We’ll look at the Zod example from the documentation. ` To use the schema validation you need to pass the schema validation adapter into the validatorAdapter option in the useForm declaration. Looking at the FieldInfo component from the example we can see that the internal state and API for form validation is the same. The adapter takes care of wiring up the schema validation library to handle the underlying field validation. ` So we can easily check the state of our field to see if there are any errors or if it’s processing some async validation logic. We mentioned that without the schema adapter we can just return an error message string from a validation function to indicate an error. With the schema adapter, we instead just return the schema itself. This works for async validations as well. ` Initially, I wasn’t sure that I would like defining a schema at the field level instead of providing a schema up front for the entire form. After sitting with it for a bit, I think it’s a better solution. The validations are decoupled from the value of the field and it allows a clean and simple API to decide when they run. In the example above validations against the schema will run on every change to the field value but we could easily change this to onBlur or any of the other available event handlers. Conclusion If you don’t mind taking a chance on a newer library from a well-established author in the ecosystem, Tanstack Form is a solid choice. - The APIs are easy to understand, and it has some nice async event handling features that are extremely useful. - It includes adapters for using schema validation libraries like Zod. - It is UI library/framework agnostic (currently has plugins to support React, React Native, and Solid) - Quality TypeScript support In my opinion, it’s the most intuitive and flexible form library out there. TanStack and all of its libraries are amazingly well designed. 10/10...

Jan 12, 2024

5 mins

TanStack QueryReact

How to Go from Software Engineer to AI Engineer with Shawn Wang

Shawn Wang discusses AI engineering’s potential impact on the software development labor market and developer experience. With the rise of artificial intelligence technologies, there is an increasing demand for professionals who can bridge the gap between AI and software engineering, and engineers are looking around for guidance on how to best learn AI. Shawn emphasizes the importance of acquiring core knowledge and skills in AI engineering, highlighting the need for a systematic approach to education and development. He envisions a future where AI engineering becomes a recognized profession, with specialized training programs and certifications. He further talks about mental models for approaching AI literacy, and skill building. Shawn also discusses the use of advanced AI technology in software development. He showcases tools like GPT Vision, which can automate tasks and generate code efficiently. While acknowledging the potential of AI in enhancing productivity, Shawn emphasizes the need to leverage AI tools to augment human capabilities rather than replace them. Download this episode here....

Apr 17, 2024

1 min

Artificial IntelligenceEngineering Leadership

Ship Less JavaScript with GraphQL Resolvers

Defining schemas to get the most out of your API

Sub-query resolvers

Moving client logic ito resolvers

Magic Fields

Transformational Resolvers

Wrapping REST APIs to leverage GraphQL features

Conclusion

Dane Grant

You might also like

Leveraging GraphQL Scalars to Enhance Your Schema

How to Resolve Nested Queries in Apollo Server

Building interactive forms with TanStack Form

How to Go from Software Engineer to AI Engineer with Shawn Wang

You might also like

Leveraging GraphQL Scalars to Enhance Your Schema

How to Resolve Nested Queries in Apollo Server

Building interactive forms with TanStack Form

How to Go from Software Engineer to AI Engineer with Shawn Wang