ranbot-ai/graphql

GraphQL

GraphQL gives clients exactly the data they need - no more, no less. One endpoint, typed schema, introspection. But the flexibility that makes it powerful also makes it dangerous. Without proper controls, clients can craft queries that bring down your server.

This skill covers schema design, resolvers, DataLoader for N+1 prevention, federation for microservices, and client integration with Apollo/urql. Key insight: GraphQL is a contract. The schema is the API documentation. Design it carefully.

2025 lesson: GraphQL isn't always the answer. For simple CRUD, REST is simpler. For high-performance public APIs, REST with caching wins. Use GraphQL when you have complex data relationships and diverse client needs.

Principles

• Schema-first design - the schema is the contract
• Prevent N+1 queries with DataLoader
• Limit query depth and complexity
• Use fragments for reusable selections
• Mutations should be specific, not generic update operations
• Errors are data - use union types for expected failures
• Nullability is meaningful - design it intentionally

Capabilities

• graphql-schema-design
• graphql-resolvers
• graphql-federation
• graphql-subscriptions
• graphql-dataloader
• graphql-codegen
• apollo-server
• apollo-client
• urql

Scope

• database-queries -> postgres-wizard
• authentication -> authentication-oauth
• rest-api-design -> backend
• websocket-infrastructure -> backend

Tooling

Server

• @apollo/server - When: Apollo Server v4 Note: Most popular GraphQL server
• graphql-yoga - When: Lightweight alternative Note: Good for serverless
• mercurius - When: Fastify integration Note: Fast, uses JIT

Client

• @apollo/client - When: Full-featured client Note: Caching, state management
• urql - When: Lightweight alternative Note: Smaller, simpler
• graphql-request - When: Simple requests Note: Minimal, no caching

Tools

• graphql-codegen - When: Type generation Note: Essential for TypeScript
• dataloader - When: N+1 prevention Note: Batches and caches

Patterns

Schema Design

Type-safe schema with proper nullability

When to use: Designing any GraphQL API

SCHEMA DESIGN:

""" The schema is your API contract. Design nullability intentionally - non-null fields must always resolve. """

type Query {

Non-null - will always return user or throw

user(id: ID!): User!

Nullable - returns null if not found

userByEmail(email: String!): User

Non-null list with non-null items

users(limit: Int = 10, offset: Int = 0): [User!]!

Search with pagination

searchUsers( query: String! first: Int after: String ): UserConnection! }

type Mutation {

Input types for complex mutations

createUser(input: CreateUserInput!): CreateUserPayload! updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload! deleteUser(id: ID!): DeleteUserPayload! }

type Subscription { userCreated: User! messageReceived(roomId: ID!): Message! }

Input types

input CreateUserInput { email: String! name: String! role: Role = USER }

input UpdateUserInput { email: String name: String role: Role }

Payload types (for errors as data)

type CreateUserPayload { user: User errors: [Error!]! }

union UpdateUserPayload = UpdateUserSuccess | NotFoundError | ValidationError

type UpdateUserSuccess { user: User! }

Enums

enum Role { USER ADMIN MODERATOR }

Types with relationships

type User { id: ID! email: String! name: String! role: Role! posts(limit: Int = 10): [Post!]! createdAt: DateTime! }

type Post { id: ID! title: String! content: String! author: User! comments: [Comment!]! published: Boolean! }

Pagination (Relay-style)

type UserConnection { edges: [UserEdge!]! pageInfo: PageInfo! totalCount: Int! }

type UserEdge { node: User! cursor: String! }

type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String }

DataLoader for N+1 Prevention

Batch and cache database queries

When to use: Resolving relationships

DATALOADER:

""" Without DataLoader, fetching 10 posts with authors makes 11 queries (1 for posts + 10 for each author). DataLoader batches into 2 queries. """

import DataLoader from 'dataloader';

// Create loaders per request function createLoaders(db) { return { userLoader: new DataLoader(async (ids) => { // Single query for all users const users = await db.user.findMany({ where: { id: { in: ids } } });

  // Return in same order as ids
  const userMap = new Map(users.map(u => [u.id, u]));
  return ids.map(id => userMap.get(id) || null);
}),

postsByAuthorLoader: new DataLoader(async (authorIds) => {
  const posts = await db.post.findMany({
    where: { authorId: { in: authorIds } }
  });

  // Group by author
  const postsByAuthor = new Map();
  posts.forEach(post => {
    const existing = postsByAuthor.get(post.authorId) || [];