Why You Should Avoid Utility Methods in GraphQL Resolvers

GraphQL has revolutionized how we fetch and shape data, providing a clean abstraction layer between clients and servers. One of its core features, resolvers, allows us to define how each field in our schema gets its data. In some cases, developers may unintentionally diminish the benefits of GraphQL by relying on utility methods in resolvers. This practice not only defeats the purpose of GraphQL's design but also introduces unnecessary complexity and potential bugs.

Let’s dive into why this is problematic and how to do better.

The Power of Resolvers

In GraphQL, resolvers are invoked for every instance of a type, regardless of where that type appears in your schema. This abstraction ensures that the logic for resolving data stays consistent across the board. For example:

schema {
  query: Query
}

type Query {
  project(id: ID!): Project
  user(id: ID!): User
}

type Project {
  id: ID!
  name: String!
  owner: User!
}

type User {
  id: ID!
  name: String!
  email: String!
}

Here, the User type is used in two places: directly in the Query for fetching users and nested within the Project type as the owner. Thanks to GraphQL's resolver system, we can define a single User resolver to handle how User fields are resolved, ensuring consistent behavior everywhere User appears.

The Problem with utils

When you introduce utility methods to shape data outside of your resolvers, you break this abstraction. Consider this example:

// utils.ts
function mapToUser(userData: DataSourceUser) {
  return {
    id: userData.id,
    name: userData.full_name,
    email: userData.contact_email,
  };
}

// resolvers.ts
const resolvers: Resolvers<Context> = {
  Query: {
    project: async (_, { id }, { dataSources }) => {
      const project = await dataSources.projectAPI.getProject(id);
      return {
        ...project,
        owner: mapToUser(project.owner), // Utility method called here
      };
    },
    user: async (_, { id }, { dataSources }) => {
      const user = await dataSources.userAPI.getUser(id);
      return mapToUser(user); // Utility method called here
    },
  },
};

At first glance, this might seem fine. But here’s why it’s problematic:

1. Duplicated Logic

You’re forced to call mapToUser in every resolver where a User type appears. Forgetting to call it or calling it incorrectly can lead to inconsistent behavior across your API.

2. Breaking Abstraction

GraphQL's resolver system is designed to centralize how each type is resolved. By using a utility method, you’re sidestepping this feature and making your code less intuitive.

3. Loss of Flexibility

If you ever need to modify how a User type is resolved (e.g., adding new fields or handling errors), you’ll have to hunt down every place where mapToUser is called instead of updating a single resolver.

The Better Approach: Leverage Type Resolvers

Instead of using utility methods, define resolvers for your GraphQL types. Here’s how you can rewrite the above example:

const resolvers: Resolvers<Context> = {
  Query: {
    project: async (_, { id }, { dataSources }) => {
      return dataSources.projectAPI.getProject(id);
    },
    user: async (_, { id }, { dataSources }) => {
      return dataSources.userAPI.getUser(id);
    },
  },
  User: {
    id: (user) => user.id,
    name: (user) => user.full_name,
    email: (user) => user.contact_email,
  },
  Project: {
    owner: (project, _, { dataSources }) => {
      return dataSources.userAPI.getUser(project.ownerId);
    },
  },
};

Why This is Better

1. Consistency: The User resolver ensures that all User instances are resolved the same way, no matter where they appear in the schema.
2. Centralized Logic: Changes to how a User is resolved only need to be made in one place.
3. Harnessing GraphQL’s Strengths: By embracing the resolver system, you’re aligning with GraphQL’s core design principles and leveraging its full potential.

Conclusion

Using utility methods in your resolvers may seem like a shortcut, but it ultimately undermines the power and elegance of GraphQL. By defining resolvers for your types, you can maintain a clean, consistent, and scalable API. So stop using utils in your resolvers and embrace the abstraction that GraphQL provides—your future self will thank you!