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