GRAPHQL Patterns

GraphQL Patterns (Apollo + TypeScript)

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

Use When

• Designing a new GraphQL API or migrating from REST
• Building Apollo Server + TypeScript with typed resolvers and clients
• Adopting Relay pagination, DataLoader, directive auth, or federation
• Hardening a GraphQL service for production

Do Not Use When

• Pure REST/gRPC — use api-design-first
• Threat-modelling GraphQL against malicious input — load references/graphql-security.md first
• Single canonical UI shape, CDN caching dominant — REST is simpler

Required Inputs

Domain entities + UI shapes; auth model (JWT/roles/tenants); federation needs; target clients and pagination style.

Workflow

1. Draft SDL against real UI shapes before resolvers.
2. Model relationships in the schema, not in resolvers.
3. Wire context (auth + loaders) before the first resolver.
4. Add depth + complexity validationRules before the first public client.
5. Add graphql-codegen to CI before the schema has a second consumer.
6. Ship with formatError masking production stack traces.

Quality Standards

• Lists are [T!]! unless partial failure is legal.
• Every mutation takes input: XxxInput! and returns a payload type.
• Every resolver is pure: reads context, calls services/loaders, returns the schema shape.
• Every relationship crossing uses DataLoader — no direct DB calls in nested resolvers.
• Production always has depth limit, complexity limit, error masking.

Anti-Patterns

Monolithic schema.js/index.js; mixed auth patterns across resolvers; client-supplied userId trusted; introspection on with no cost analysis; bare throw new Error; String for dates.

Outputs

schema.graphql + operations + generated TS; Apollo Server bootstrap; per-request DataLoader factory; codegen.yml; security baseline (depth/complexity/introspection/CORS/helmet).

Evidence Produced

References

• Fullstack GraphQL (TS + Apollo + React); JavaScript Everywhere — Adam D. Scott (O'Reilly, 2020).
• Apollo Server + Federation v2 docs; Relay cursor connection spec (relay.dev/graphql/connections.htm).
• Companion skills: api-design-first, references/graphql-security.md, typescript-full-stack, nodejs-development.

Overview

GraphQL inverts REST: the client declares the shape, the server resolves. This kills endpoint proliferation at the cost of new problems (N+1, depth attacks, typed error plumbing). This skill prescribes a production-grade Apollo + TypeScript baseline that avoids those pitfalls by construction.

Cardinal rule: The schema is the contract. Design it first; every other layer derives from it.

1. Schema-First Design (SDL)

Order of work: UI shape → SDL types → DB model → resolvers. Never reverse this.

scalar DateTime

type Note {
  id: ID!
  content: String!
  author: User!
  createdAt: DateTime!
  favoritedBy: [User!]!
}

type User {
  id: ID!
  username: String!
  notes(first: Int = 20, after: String): NoteConnection!
}

input CreateNoteInput { content: String! }
type CreateNotePayload { note: Note, errors: [UserError!]! }
type UserError { field: String, message: String! }

type Query {
  me: User
  note(id: ID!): Note
}

type Mutation {
  createNote(input: CreateNoteInput!): CreateNotePayload!
}

Non-null rules:

• Note! — never null. [Note!]! — list never null, no null elements (the default for collection queries).
• [Note] only when partial results are legal.
• Nullable-string like description: String is right when the domain allows absence; everywhere else a null is a latent bug.

Input types are mandatory once a mutation has >2 scalar args. Wrapping in an input lets you add fields later without changing the call site.

Mutation payload types never return the bare entity. Return CreateNotePayload { note, errors } so clients can surface validation errors as typed data (see §6).

Interface vs union:

• interface when variants share fields: interface RepositoryOwner { login: String! } → User, Organization both implement.
• union when variants share nothing: union SearchResult = Issue | PullRequest | Repository.

Clients discriminate with __typename + inline fragments — always request __typename on interface/union queries or Apollo client cache normalisation breaks.

Custom scalars — never String for dates. Bind graphql-iso-date's GraphQLDateTime to the DateTime scalar. The resolver then receives a real Date, not an unvalidated string.

2. Resolvers

Canonical signature: (parent, args, context, info) — parent from parent resolver, args schema-typed, context per-request (built once), info AST (use for projection/cost, never for routing).

Split resolvers per type. One file per Query.ts, Mutation.ts, Note.ts (relationships), User.ts, scalars.ts.

// src/resolvers/Note.ts
import { NoteResolvers } from '../__generated__/graphql';
export const Note: NoteResolvers = {
  author:      (note, _a, { loaders }) => loaders.userById.load(note.author_id),
  favoritedBy: (note, _a, { loaders }) => loaders.usersByNoteId.load(note.id),
};

Thin root resolvers, relationship resolvers on the type. Apollo calls relationship resolvers only when the client selects the field — this is what makes "pay only for what you select" real.

3. Context Construction (where auth + loaders live)

// src/context.ts
import { readJwt } from './auth';
import { makeLoaders } from './loaders';

export type Context = {
  user: { id: string; roles: string[] } | null;
  loaders: ReturnType<typeof makeLoaders>;
  db: Db;
};

export async function buildContext({ req }: { req: IncomingMessage }): Promise<Context> {
  const user = readJwt(req.headers.authorization);
  return { user, loaders: makeLoaders(db), db };
}

Decode the JWT exactly once, then every resolver reads context.user. Never trust args.userId.

4. N+1 and DataLoader

The problem: notes { author { username } } hits the DB once per note. Logs show SELECT user WHERE id = 1, ... = 2, ... = 2, ... = 3.

The fix: one DataLoader per join, per request.

// src/loaders.ts
import DataLoader from 'dataloader';

export function makeLoaders(db: Db) {
  return {
    userById: new DataLoader<string, User>(async (ids) => {
      const rows = await db.users.findByIds([...ids]);
      const map = new Map(rows.map((r) => [r.id, r]));
      return ids.map((id) => map.get(id)!); // ORDER MUST MATCH INPUT
    }),
    usersByNoteId: new DataLoader<string, User[]>(async (noteIds) => {
      const rows = await db.noteFavorites.findByNoteIds([...noteIds]);
      const grouped = groupBy(rows, 'noteId');
      return noteIds.map((id) => grouped[id] ?? []);
    }),
  };
}

Two rules: (1) the returned array must match the keys array by index; (2) the loader must be built per-request — sharing across requests leaks data between tenants.

Per-request caching is the second win. In circular traversals (notes → author → notes) the Map-backed cache means each userById.load('u1') hits the DB once.

When not to use DataLoader:

• After a mutation that needs fresh data — call loaders.userById.clear(id) or bypass.
• Non-ID-keyed lookups (filter + sort combinations) — the loader key space becomes combinatorial; prefer a thin service layer.
• Multi-gigabyte value shapes — the Map blows heap; move caching to Redis.

DataLoader is a per-request optimisation. It does not replace HTTP or Redis caching.

5. Auth and Authz

JWT in the header, decoded once in context. Both web and mobile clients set Authorization: Bearer <token>. Never sessions for a public GraphQL API — they collapse under mobile clients.

Field-level authorisation — two patterns, pick one and hold it.

Code-based:

import { AuthenticationError, ForbiddenError } from 'apollo-server-errors';
export const Mutation: MutationResolvers = {
  deleteNote: async (_, { id }, { user, db }) => {
    if (!user) throw new AuthenticationError('Session invalid');
    const note = await db.notes.byId(id);
    if (String(note.author_id) !== user.id) throw new ForbiddenError('Not your note');
    await db.notes.delete(id);
    return { ok: true };
  },
};

Directive-based (declarative):

directive @auth(role: Role) on FIELD_DEFINITION | INPUT_FIELD_DEFINITION
type Mutation {
  publishNote(id: ID!, published: Boolean! @auth(role: ADMIN)): Note @auth
}

A custom @auth schema directive wraps defaultFieldResolver, inspects context.user.roles, and throws or proceeds. Put the directive implementation in one file; grep-readers see the rule on the field itself.

Pitfalls:

• Mixing both patterns → some paths are checked twice, some missed.
• AuthenticationError (unauthenticated) vs ForbiddenError (authenticated, not allowed) map to distinct UX — clients route on extensions.code.
• Normalise email on signup (.trim().toLowerCase()). Hash passwords with bcrypt, 10+ salt rounds.

6. Pagination (Relay Cursor Connection)

Offset pagination is simple and scales poorly. Use cursors for production.

type NoteConnection {
  edges: [NoteEdge!]!
  nodes: [Note!]!
  pageInfo: PageInfo!
  totalCount: Int
}
type NoteEdge { cursor: String!, node: Note! }
type PageInfo {
  startCursor: String
  endCursor: String
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
}
type Query { feed(first: Int = 20, after: String): NoteConnection! }

// src/resolvers/Query.ts
export const Query: QueryResolvers = {
  feed: async (_, { first = 20, after }, { db }) => {
    const limit = Math.min(first!, 100);
    const rows = await db.notes.page({ after, limit: limit + 1 });
    const hasNextPage = rows.length > limit;
    if (hasNextPage) rows.pop();
    return {
      edges: rows.map((n) => ({ cursor: encode(n.id), node: n })),
      nodes: rows,
      pageInfo: {
        startCursor: rows.length ? encode(rows[0].id) : null,
        endCursor:   rows.length ? encode(rows.at(-1)!.id) : null,
        hasNextPage,
        hasPreviousPage: false,
      },
    };
  },
};

Cursors are opaque — base64-encode them so clients do not parse IDs and so you can change the underlying ordering without breaking anyone. totalCount is expensive on large tables — make it nullable and only compute when asked.

7. Error Handling

Apollo ships typed error classes: AuthenticationError, ForbiddenError, UserInputError, ApolloError. Each sets extensions.code to a stable machine-readable string (UNAUTHENTICATED, FORBIDDEN, BAD_USER_INPUT). Clients route on code, not on message.

import { UserInputError } from 'apollo-server-errors';
if (!email.includes('@')) throw new UserInputError('Invalid email', { field: 'email' });

Prefer errors-as-data for field-level validation. Return them in the payload type so the UI renders per-field messages without reading the top-level errors[]:

type CreateNotePayload { note: Note, errors: [UserError!]! }
type UserError { field: String, message: String!, code: String! }

Mask in production. Stack traces and upstream messages leak internals. Use formatError:

new ApolloServer({
  formatError: (err) => {
    logger.error(err);
    if (err.extensions?.code === 'INTERNAL_SERVER_ERROR') {
      return new Error('Internal server error');
    }
    return err;
  },
});

8. Apollo Server Setup

import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@apollo/server/express4';
import { ApolloServerPluginLandingPageProductionDefault } from '@apollo/server/plugin/landingPage/default';
import depthLimit from 'graphql-depth-limit';
import { createComplexityLimitRule } from 'graphql-validation-complexity';

const server = new ApolloServer<Context>({
  typeDefs, resolvers,
  introspection: process.env.NODE_ENV !== 'production',
  validationRules: [
    depthLimit(7),
    createComplexityLimitRule(1000, { onCost: (c) => metrics.queryCost.observe(c) }),
  ],
  plugins: [ApolloServerPluginLandingPageProductionDefault()],
  formatError,
});
await server.start();
app.use('/graphql', helmet(), cors(corsOpts), express.json(), expressMiddleware(server, { context: buildContext }));

Middleware order matters: helmet → cors → json → Apollo. Validation rules run before execution — that is the correct layer for depth and complexity guards, not resolvers.

9. Subscriptions (graphql-ws)

Transport is graphql-ws (not deprecated subscriptions-transport-ws). Auth the connection_init frame, not every message.

useServer({
  schema,
  context: async (ctx) => {
    const user = readJwt(`Bearer ${ctx.connectionParams?.authToken}`);
    if (!user) throw new Error('unauthenticated');
    return { user, loaders: makeLoaders(db), db };
  },
}, new WebSocketServer({ server: httpServer, path: '/graphql' }));

Subscription: {
  noteAdded: {
    subscribe: withFilter(
      () => pubsub.asyncIterator('NOTE_ADDED'),
      (payload, _a, ctx) => payload.noteAdded.tenant_id === ctx.user.tenant_id,
    ),
  },
},

In a multi-node deploy use Redis-backed PubSub (graphql-redis-subscriptions) so events fan out across instances.

10. Federation v2

Apollo Federation v2 composes multiple subgraph schemas into one supergraph served by a router. Each team owns a subgraph.

# users subgraph
type User @key(fields: "id") {
  id: ID!
  username: String!
}

# notes subgraph — extends User with a shareable field
type Note @key(fields: "id") {
  id: ID!
  content: String!
  author: User!
}
type User @key(fields: "id") {
  id: ID! @external
  notes: [Note!]!
}

Directives to know:

• @key(fields: "...") — identifies the entity; the router uses it to stitch.
• @external — a field is declared here but owned elsewhere.
• @shareable — the field can be resolved by multiple subgraphs (router picks one).
• @requires(fields: "...") — this resolver needs fields from another subgraph before it can run.
• @provides(fields: "...") — this resolver already returns fields from another subgraph, no need to fetch.

Entity resolution happens in the subgraph that owns the @key:

Query: {
  _entities: (_, { representations }, { loaders }) =>
    representations.map((rep) => loaders.userById.load(rep.id)),
},

Composition runs in CI (rover supergraph compose); the router (Apollo Router or @apollo/gateway) serves the composed schema. Do not write supergraph schemas by hand.

11. TypeScript End-to-End (graphql-codegen)

# codegen.yml
schema: src/schema.graphql
documents: 'src/**/*.graphql'
generates:
  src/__generated__/graphql.ts:
    plugins: [typescript, typescript-operations, typescript-resolvers]
    config: { contextType: '../context#Context', useIndexSignature: true }

typescript generates schema types. typescript-operations generates one type per query matching exactly the fields that query selects — the anti-hallucination safeguard. typescript-resolvers types the resolver maps against the schema. Add typescript-react-apollo on the client for typed useFeedQuery() hooks.

Run yarn generate on every schema/operation change; CI fails if generated files drift. Without this discipline, TypeScript silently lies.

12. File Uploads

Apollo Server 4 does not ship uploads — use graphql-upload-minimal with the multipart request spec.

app.use('/graphql', graphqlUploadExpress({ maxFileSize: 10_000_000, maxFiles: 3 }));
// scalar Upload; type Mutation { uploadAvatar(file: Upload!): String! }

Resolver receives { createReadStream, filename, mimetype }. Stream directly to S3 — never buffer the full file. Enforce size at middleware and reverse proxy. If binary traffic is heavy, keep a plain HTTP POST endpoint and let the mutation return only a reference.

13. Testing

Unit: resolvers are just functions — call them directly with a faked context. await Query.feed!({}, { first: 5 }, ctx as any, {} as any).

Integration: @apollo/server exposes server.executeOperation({ query, variables }, { contextValue }) to run the pipeline in-process — preferred over hitting HTTP.

Mocked schema via addMocksToSchema (@graphql-tools/mock) for frontend dev without a backend.

Schema snapshot tests — printSchema(schema) → golden file. Any accidental breaking change fails CI before a resolver runs.

14. Production Hardening

Mandatory for any public endpoint: depth limit (depthLimit(7)); complexity/cost analysis (graphql-cost-analysis — cap per request, record score for rate-limiting and metering); introspection off in production (GitLab's 2019 DoS was unlimited introspection); persisted queries (APQ + whitelist — reject unknown hashes in strict mode); timeouts (HTTP 30 s at proxy, resolver AbortController on downstream); disable batching array requests unless used (bypasses per-request rate limits); CORS allow-list — never *; helmet + TLS at the edge; tracing (OpenTelemetry → Jaeger/Tempo + Apollo Studio).

Load references/graphql-security.md for the adversarial checklist (alias/directive overloading, SSRF via argument fields, CSRF on mutations).

15. When Not to Use GraphQL

Capability contract

Design and review schemas by default. Modify resolvers or generated clients only when authorised; never deploy a graph or alter production authorization implicitly.

Degraded mode

If registry, telemetry, or identity policy is unavailable, produce a read-only review and flag complexity, compatibility, and authorization checks as unverified.

Decision rules

Protected fields require field-level authorization; unbounded queries require pagination and complexity limits; breaking changes require deprecation before removal.

Domain Anti-Patterns

• Authorizing only at the HTTP endpoint. Fix: enforce resolver policy.

• Returning unbounded lists. Fix: require cursor pagination.

• Creating loaders per item. Fix: scope DataLoader per request.

• Exposing internal exceptions. Fix: map typed public errors.

• Removing fields without usage evidence. Fix: deprecate and measure first.

• Single canonical client, HTTP caching dominates, no N+1 pain → REST is cheaper.

• Heavy binary uploads or server-sent file streams → HTTP native.

• Public API where CDN edge caching is business-critical → GraphQL's POST-only default defeats it.

• One team, one service, <10 endpoints → the tooling weight does not pay back.

Hybrid default: GraphQL as a BFF over REST microservices — REST for webhooks and file upload, GraphQL for client-shaped reads of relational UIs. Pairs naturally with microservices-architecture, which owns the inter-service communication patterns.