pn-graphql

GraphQL

When to use

• Designing or implementing a GraphQL API (schema-first or code-first)
• Writing resolvers, mutations, or subscriptions
• Reviewing a GraphQL schema for N+1 problems, over-fetching, or security issues
• Setting up Apollo Server, GraphQL Yoga, or Pothos
• Adding GraphQL Federation (supergraph / subgraph split)

Core principles

1. Schema is the contract — design the schema from the consumer's perspective, not the database shape.
2. Solve N+1 before shipping — every list resolver that calls a data source must use DataLoader or a batch-aware fetcher.
3. Depth and complexity limits are non-negotiable — unprotected GraphQL endpoints are trivially DoS-able via nested queries.
4. Mutations are commands, not CRUD — name mutations after business operations (placeOrder, cancelSubscription) not database verbs (updateOrder).
5. Never expose internal IDs — use opaque cursor-based pagination and global IDs (node(id: "User:123")).

Schema design

# Use clear domain language; avoid database column names as field names
type User {
  id: ID!
  email: String!
  displayName: String!
  orders(first: Int, after: String): OrderConnection!
  createdAt: DateTime!
}

type OrderConnection {
  edges: [OrderEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type OrderEdge {
  cursor: String!
  node: Order!
}

# Errors as values — union return types for mutations
type PlaceOrderResult {
  order: Order
  error: PlaceOrderError
}

enum PlaceOrderError {
  INSUFFICIENT_INVENTORY
  PAYMENT_DECLINED
  INVALID_ADDRESS
}

Resolvers (Apollo Server / GraphQL Yoga)

import { ApolloServer } from "@apollo/server";
import DataLoader from "dataloader";

// Batch loader — resolves N users in one query
const userLoader = new DataLoader<string, User>(async (ids) => {
  const users = await db.user.findMany({ where: { id: { in: [...ids] } } });
  return ids.map((id) => users.find((u) => u.id === id) ?? new Error(`User ${id} not found`));
});

const resolvers = {
  Query: {
    user: (_: unknown, { id }: { id: string }, { loaders }: Context) =>
      loaders.user.load(id),
  },
  Order: {
    // Field resolver — batched via DataLoader, not N+1
    customer: (order: Order, _: unknown, { loaders }: Context) =>
      loaders.user.load(order.customerId),
  },
  Mutation: {
    placeOrder: async (_: unknown, args: PlaceOrderInput, { user }: Context) => {
      if (!user) throw new GraphQLError("Unauthorized", { extensions: { code: "UNAUTHENTICATED" } });
      // business logic
    },
  },
};