GraphQL Resolver Pattern

Implement resolvers with clean separation between data fetching, business logic, and response shaping

When to Use

• Writing resolvers for queries, mutations, or subscriptions
• Structuring resolver files across a growing schema
• Deciding where to place business logic vs. data access
• Debugging N+1 queries or resolver chain issues
• Setting up the resolver context object

Instructions

1. Understand the resolver signature. Every resolver receives four arguments:

   (parent, args, context, info)

   . Use them intentionally —

   parent

   carries the result from the parent resolver,

   args

   contains the field arguments,

   context

   is the per-request shared state,

   info

   holds the AST and field metadata.

const resolvers = {
  Query: {
    user: (_parent: unknown, args: { id: string }, context: Context) => {
      return context.dataSources.users.findById(args.id);
    },
  },
};

2. Keep resolvers thin. A resolver should validate input, delegate to a service or data source, and return the result. It should not contain business logic, raw SQL, or HTTP calls directly.

// Good — resolver delegates to service
const resolvers = {
  Mutation: {
    cancelOrder: async (_parent, { input }, { dataSources, currentUser }) => {
      const result = await dataSources.orders.cancel(input.orderId, input.reason, currentUser);
      return {
        order: result.order,
        refundAmount: result.refund,
        errors: result.errors,
      };
    },
  },
};

// Bad — business logic in resolver
const resolvers = {
  Mutation: {
    cancelOrder: async (_parent, { input }, { db }) => {
      const order = await db.query('SELECT * FROM orders WHERE id = $1', [input.orderId]);
      if (order.status === 'SHIPPED') throw new Error('Cannot cancel shipped order');
      // ... 50 lines of business logic
    },
  },
};

3. Use field resolvers for derived data. When a field on a type needs computation or a separate data fetch, write a field resolver on the type instead of pre-loading everything in the parent query resolver.

const resolvers = {
  User: {
    fullName: (user) => `${user.firstName} ${user.lastName}`,
    orders: (user, _args, { dataSources }) => {
      return dataSources.orders.findByUserId(user.id);
    },
  },
};

4. Build a rich context object. Initialize

   context

   in your server setup with authenticated user, data sources, and request-scoped services. Avoid putting the raw

   req

   /

   res

   objects in context — wrap what you need.

const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: async ({ req }) => ({
    currentUser: await authenticateToken(req.headers.authorization),
    dataSources: {
      users: new UserDataSource(db),
      orders: new OrderDataSource(db),
    },
    logger: createRequestLogger(req),
  }),
});

5. Organize resolvers by domain. Split resolvers into files matching your domain areas —

   user.resolvers.ts

   ,

   order.resolvers.ts

   — then merge them using

   lodash.merge

   or a resolver merging utility.

6. Return promises, not awaited values, when possible. GraphQL execution handles promises natively. Returning the promise directly (without

   await

   ) allows the executor to parallelize sibling field resolution.

7. Use the

   info

   argument sparingly. It provides the full query AST, useful for advanced optimizations (look-ahead to avoid over-fetching), but parsing it adds complexity. Prefer DataLoader for batching over manual

   info

   inspection.

8. Handle null propagation deliberately. If a field resolver throws or returns

   null

   for a non-null field, the error bubbles up. Consider wrapping risky resolvers in try-catch and returning

   null

   (for nullable fields) or structured errors (for mutation payloads).

Details

Resolver chain execution: GraphQL resolves fields top-down, breadth-first within each level. The return value of a parent resolver becomes the

parent

argument of its child field resolvers. If a Query resolver returns

{ id: '1', name: 'Alice' }

, the

User.name

field resolver receives that object as

parent

.

Default resolver: If no resolver is defined for a field, GraphQL uses the default resolver:

parent[fieldName]

. This means you only need explicit resolvers for fields that require computation, transformation, or separate data fetching.

Data source pattern (Apollo): Encapsulate data access in classes that extend

DataSource

. Each data source gets access to the request context and can implement caching, batching, and error handling independently.

Testing resolvers: Test resolvers by calling them directly with mocked

context

and

args

. Test the full GraphQL execution path separately with integration tests using

executeOperation

or

server.executeOperation

.

Common pitfalls:

• Forgetting that field resolvers run per-item in a list (causes N+1 without DataLoader)
• Mutating the

  parent

  object in a field resolver (shared reference across sibling fields)
• Throwing raw errors instead of returning structured

  UserError

  types in mutations
• Over-fetching in parent resolvers to avoid field resolvers (defeats lazy resolution)

Source

https://graphql.org/learn/execution/

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.