graphql-schema-designer

What this skill does

# GraphQL Schema Designer

Build efficient, type-safe GraphQL APIs with proper schema design and resolver patterns.

## Core Workflow

1. **Design schema**: Define types, queries, mutations
2. **Implement resolvers**: Connect to data sources
3. **Add DataLoader**: Batch and cache queries
4. **Enable subscriptions**: Real-time updates
5. **Add validation**: Input validation and errors
6. **Document**: Schema descriptions

## Project Setup

```bash
npm install @apollo/server graphql graphql-tag dataloader
npm install -D @graphql-codegen/cli @graphql-codegen/typescript
```

## Schema Design

### Type Definitions

```graphql
# schema.graphql
scalar DateTime
scalar JSON

"""
A registered user in the system
"""
type User {
  id: ID!
  email: String!
  name: String!
  avatar: String
  role: UserRole!
  posts: [Post!]!
  comments: [Comment!]!
  createdAt: DateTime!
  updatedAt: DateTime!
}

enum UserRole {
  ADMIN
  USER
  GUEST
}

type Post {
  id: ID!
  title: String!
  content: String!
  published: Boolean!
  author: User!
  comments: [Comment!]!
  tags: [Tag!]!
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Comment {
  id: ID!
  content: String!
  author: User!
  post: Post!
  createdAt: DateTime!
}

type Tag {
  id: ID!
  name: String!
  posts: [Post!]!
}

"""
Pagination info for cursor-based pagination
"""
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

type PostEdge {
  cursor: String!
  node: Post!
}

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}
```

### Queries

```graphql
type Query {
  """
  Get current authenticated user
  """
  me: User

  """
  Get a user by ID
  """
  user(id: ID!): User

  """
  List all users with optional filtering
  """
  users(
    role: UserRole
    search: String
    limit: Int = 10
    offset: Int = 0
  ): [User!]!

  """
  Get a post by ID
  """
  post(id: ID!): Post

  """
  List posts with cursor pagination
  """
  posts(
    first: Int
    after: String
    last: Int
    before: String
    published: Boolean
    authorId: ID
  ): PostConnection!

  """
  Search posts by title or content
  """
  searchPosts(query: String!, limit: Int = 10): [Post!]!
}
```

### Mutations

```graphql
input CreateUserInput {
  email: String!
  name: String!
  password: String!
  role: UserRole = USER
}

input UpdateUserInput {
  name: String
  avatar: String
}

input CreatePostInput {
  title: String!
  content: String!
  published: Boolean = false
  tagIds: [ID!]
}

input UpdatePostInput {
  title: String
  content: String
  published: Boolean
  tagIds: [ID!]
}

type Mutation {
  # Auth
  signUp(input: CreateUserInput!): AuthPayload!
  signIn(email: String!, password: String!): AuthPayload!
  signOut: Boolean!

  # Users
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!

  # Posts
  createPost(input: CreatePostInput!): Post!
  updatePost(id: ID!, input: UpdatePostInput!): Post!
  deletePost(id: ID!): Boolean!
  publishPost(id: ID!): Post!

  # Comments
  createComment(postId: ID!, content: String!): Comment!
  deleteComment(id: ID!): Boolean!
}

type AuthPayload {
  token: String!
  user: User!
}
```

### Subscriptions

```graphql
type Subscription {
  """
  Subscribe to new posts
  """
  postCreated: Post!

  """
  Subscribe to comments on a specific post
  """
  commentAdded(postId: ID!): Comment!

  """
  Subscribe to post updates
  """
  postUpdated(id: ID!): Post!
}
```

## Resolvers

### Basic Resolver Structure

```typescript
// resolvers/index.ts
import { Resolvers } from '../generated/graphql';
import { userResolvers } from './user';
import { postResolvers } from './post';
import { commentResolvers } from './comment';
import { scalarResolvers } from './scalars';

export const resolvers: Resolvers = {
  ...scalarResolvers,
  Query: {
    ...userResolvers.Query,
    ...postResolvers.Query,
  },
  Mutation: {
    ...userResolvers.Mutation,
    ...postResolvers.Mutation,
    ...commentResolvers.Mutation,
  },
  Subscription: {
    ...postResolvers.Subscription,
    ...commentResolvers.Subscription,
  },
  User: userResolvers.User,
  Post: postResolvers.Post,
  Comment: commentResolvers.Comment,
};
```

### User Resolvers

```typescript
// resolvers/user.ts
import { Resolvers } from '../generated/graphql';
import { Context } from '../context';

export const userResolvers: Resolvers<Context> = {
  Query: {
    me: async (_, __, { user }) => {
      if (!user) return null;
      return user;
    },

    user: async (_, { id }, { dataSources }) => {
      return dataSources.users.findById(id);
    },

    users: async (_, { role, search, limit, offset }, { dataSources }) => {
      return dataSources.users.findMany({ role, search, limit, offset });
    },
  },

  Mutation: {
    signUp: async (_, { input }, { dataSources }) => {
      const user = await dataSources.users.create(input);
      const token = generateToken(user);
      return { token, user };
    },

    updateUser: async (_, { id, input }, { dataSources, user }) => {
      // Authorization check
      if (user?.id !== id && user?.role !== 'ADMIN') {
        throw new ForbiddenError('Not authorized');
      }
      return dataSources.users.update(id, input);
    },
  },

  User: {
    posts: async (parent, _, { loaders }) => {
      return loaders.postsByAuthor.load(parent.id);
    },

    comments: async (parent, _, { loaders }) => {
      return loaders.commentsByAuthor.load(parent.id);
    },
  },
};
```

### Post Resolvers with Pagination

```typescript
// resolvers/post.ts
import { Resolvers } from '../generated/graphql';

export const postResolvers: Resolvers<Context> = {
  Query: {
    post: async (_, { id }, { dataSources }) => {
      return dataSources.posts.findById(id);
    },

    posts: async (_, { first, after, last, before, published, authorId }, { dataSources }) => {
      const { edges, pageInfo, totalCount } = await dataSources.posts.findMany({
        first,
        after,
        last,
        before,
        where: { published, authorId },
      });

      return { edges, pageInfo, totalCount };
    },

    searchPosts: async (_, { query, limit }, { dataSources }) => {
      return dataSources.posts.search(query, limit);
    },
  },

  Mutation: {
    createPost: async (_, { input }, { dataSources, user, pubsub }) => {
      if (!user) throw new AuthenticationError('Must be logged in');

      const post = await dataSources.posts.create({
        ...input,
        authorId: user.id,
      });

      // Publish to subscribers
      pubsub.publish('POST_CREATED', { postCreated: post });

      return post;
    },

    publishPost: async (_, { id }, { dataSources, user }) => {
      const post = await dataSources.posts.findById(id);

      if (post.authorId !== user?.id) {
        throw new ForbiddenError('Not your post');
      }

      return dataSources.posts.update(id, { published: true });
    },
  },

  Subscription: {
    postCreated: {
      subscribe: (_, __, { pubsub }) => pubsub.asyncIterator(['POST_CREATED']),
    },

    postUpdated: {
      subscribe: (_, { id }, { pubsub }) => {
        return pubsub.asyncIterator([`POST_UPDATED_${id}`]);
      },
    },
  },

  Post: {
    author: async (parent, _, { loaders }) => {
      return loaders.users.load(parent.authorId);
    },

    comments: async (parent, _, { loaders }) => {
      return loaders.commentsByPost.load(parent.id);
    },

    tags: async (parent, _, { loaders }) => {
      return loaders.tagsByPost.load(parent.id);
    },
  },
};
```

## DataLoader Pattern

### Create Loaders

```typescript
// loaders/index.ts
import DataLoader from 'dataloader';
import { db } from '../db';

export function createLoaders() {
  return {
    users: new DataLoader<string, User>(async (ids) => {
      const users = await db.user.findMany({
        where: { id: { in: [...ids] } },
      });
      // Return in same order as requested
      return id