graphql

name	GraphQL
slug	graphql
version	1.0.1
description	Design GraphQL schemas and resolvers with proper performance, security, and error handling.
metadata	{"clawdbot":{"emoji":"◈","os":["linux","darwin","win32"]}}

Quick Reference

Topic	File
Schema design patterns	schema.md
Security and limits	security.md
Performance optimization	performance.md
Client-side patterns	client.md

N+1 Problem (Critical)

• Each resolver runs independently—fetching user for each of 100 posts = 100 queries
• DataLoader required: batches requests within single tick—100 posts = 1 user query
• DataLoader per-request: create new instance per request—prevents cross-request caching
• Even with DataLoader, watch for nested N+1—posts → comments → authors chains

Schema Design

• Fields nullable by default—make non-null explicit: name: String!
• Input types separate from output—CreateUserInput vs User; allows different validation
• Connections for pagination: users(first: 10, after: "cursor") returns edges + pageInfo
• Avoid deeply nested types—flatten where possible; 5+ levels = resolver complexity

Pagination

• Cursor-based (Relay style): first/after, last/before—stable across insertions
• Offset-based: limit/offset—simpler but skips or duplicates on concurrent writes
• Return pageInfo { hasNextPage, endCursor }—client knows when to stop
• totalCount expensive on large datasets—make optional or estimate

Security Traps

• Query depth limiting—prevent { user { friends { friends { friends... } } } }
• Query complexity scoring—count fields, multiply by list sizes; reject above threshold
• Disable introspection in production—or protect with auth; schema is attack surface
• Timeout per query—malicious queries can be slow without being deep
• Rate limit by complexity, not just requests—one complex query = many simple ones

Error Handling

• Partial success normal—query returns data AND errors; check both
• Errors array with path—shows which field failed: "path": ["user", "posts", 0]
• Error extensions for codes—"extensions": {"code": "FORBIDDEN"}; don't parse message
• Throw in resolver = null + error—parent nullable = partial data; parent non-null = error propagates up

Resolver Patterns

• Return object with ID, let sub-resolvers fetch details—avoids over-fetching at top level
• __resolveType for unions/interfaces—required to determine concrete type
• Context for auth, DataLoaders, DB connection—pass through resolver chain
• Field-level auth in resolvers—check permissions per field, not just per query

Mutations

• Return modified object—client updates cache without re-fetch
• Input validation before DB—return user-friendly error, not DB constraint violation
• Idempotency for critical mutations—accept client-generated ID or idempotency key
• One mutation per operation typically—batch mutations exist but complicate error handling

Performance

• Persisted queries: hash → query mapping—smaller payloads, prevents arbitrary queries
• @defer for slow fields—returns fast fields first, streams slow ones (if supported)
• Fragment colocation: components define data needs—reduces over-fetching
• Query allowlisting: only registered queries in production—blocks exploratory attacks

Subscriptions

• WebSocket-based—graphql-ws protocol; separate from HTTP
• Scaling: pub/sub needed—Redis or similar for multi-server broadcast
• Filter at subscription level—don't push everything and filter client-side
• Unsubscribe on disconnect—clean up resources; connection tracking required

Client-Side

• Normalized cache (Apollo, Relay)—deduplicate by ID; updates propagate automatically
• Optimistic UI: predict mutation result—rollback if server differs
• Error policies: decide per-query—ignore errors, return partial, or treat as failure
• Fragment reuse—define once, use in multiple queries; keeps fields in sync

Common Mistakes

• No DataLoader—N+1 kills performance; one query becomes hundreds
• Exposing internal errors—stack traces leak implementation details
• No query limits—attackers craft expensive queries; DoS with single request
• Over-fetching in resolvers—fetching full object when query only needs ID + name
• Treating like REST—GraphQL is a graph; design for traversal, not resources