GraphQL

Design GraphQL schemas and resolvers with proper performance, security, and error handling.

Security Scan

This is an instruction-only GraphQL design guide; its requested footprint (no installs, no env vars, no code) matches its stated purpose and I found no incoherent or suspicious requirements.

Purpose & Capability

The name/description (GraphQL schema/resolver design) matches the content and required resources: it's purely documentation and does not request unrelated credentials, binaries, or config paths.

Instruction Scope

SKILL.md and the companion files contain best-practice guidance (N+1, pagination, security limits, etc.). They do not instruct the agent to read arbitrary files, access environment secrets, call external endpoints, or perform other out-of-scope actions.

Install Mechanism

No install spec and no code files — instruction-only. This is the lowest-risk delivery mechanism and is proportionate to an educational/reference skill.

Credentials

The skill declares no environment variables, credentials, or config paths. Nothing requested appears excessive or unrelated to designing GraphQL schemas and resolvers.

Persistence & Privilege

The skill does not request persistent presence (always:false) and does not modify global config; autonomous invocation is allowed by platform default but is not combined with any sensitive access here.

Assessment

This skill is a documentation-only guide for GraphQL design and appears internally consistent. It does not request credentials or install code, so the install risk is low. Still review any code the agent generates from these instructions before deploying (especially auth/authorization and rate-limiting details), and avoid giving the agent production secrets or direct access to production systems when experimenting with schema/mutation changes. If you need an implementation (binaries, libraries, or persisted query storage), prefer installing well-known packages rather than following ad-hoc instructions added to the agent.

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