autoworkflow 3.1.4 → 3.5.0

package/.claude/skills/graphql.md

@@ -0,0 +1,478 @@
+# GraphQL Skill
+
+## Schema Design
+\`\`\`graphql
+# schema.graphql
+
+# Scalars
+scalar DateTime
+scalar JSON
+
+# Enums
+enum Role {
+  USER
+  ADMIN
+  MODERATOR
+}
+
+enum PostStatus {
+  DRAFT
+  PUBLISHED
+  ARCHIVED
+}
+
+# Types
+type User {
+  id: ID!
+  email: String!
+  name: String
+  role: Role!
+  posts(first: Int, after: String): PostConnection!
+  createdAt: DateTime!
+  updatedAt: DateTime!
+}
+
+type Post {
+  id: ID!
+  title: String!
+  content: String!
+  status: PostStatus!
+  author: User!
+  comments(first: Int, after: String): CommentConnection!
+  tags: [String!]!
+  publishedAt: DateTime
+  createdAt: DateTime!
+}
+
+type Comment {
+  id: ID!
+  content: String!
+  author: User!
+  post: Post!
+  createdAt: DateTime!
+}
+
+# Pagination (Relay-style)
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+
+type PostEdge {
+  node: Post!
+  cursor: String!
+}
+
+type PostConnection {
+  edges: [PostEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+# Inputs
+input CreateUserInput {
+  email: String!
+  name: String!
+  password: String!
+}
+
+input CreatePostInput {
+  title: String!
+  content: String!
+  status: PostStatus = DRAFT
+  tags: [String!]
+}
+
+input UpdatePostInput {
+  title: String
+  content: String
+  status: PostStatus
+  tags: [String!]
+}
+
+input PostFilterInput {
+  status: PostStatus
+  authorId: ID
+  search: String
+}
+
+# Queries
+type Query {
+  # Single resources
+  user(id: ID!): User
+  post(id: ID!): Post
+  me: User
+
+  # Collections with filtering & pagination
+  users(first: Int, after: String): UserConnection!
+  posts(
+    first: Int
+    after: String
+    filter: PostFilterInput
+  ): PostConnection!
+}
+
+# Mutations
+type Mutation {
+  # User mutations
+  createUser(input: CreateUserInput!): CreateUserPayload!
+  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
+  deleteUser(id: ID!): DeleteUserPayload!
+
+  # Post mutations
+  createPost(input: CreatePostInput!): CreatePostPayload!
+  updatePost(id: ID!, input: UpdatePostInput!): UpdatePostPayload!
+  deletePost(id: ID!): DeletePostPayload!
+  publishPost(id: ID!): PublishPostPayload!
+}
+
+# Mutation Payloads
+type CreatePostPayload {
+  post: Post
+  errors: [Error!]
+}
+
+type Error {
+  field: String
+  message: String!
+}
+
+# Subscriptions
+type Subscription {
+  postCreated: Post!
+  postUpdated(id: ID!): Post!
+  commentAdded(postId: ID!): Comment!
+}
+\`\`\`
+
+## Resolvers (Apollo Server)
+\`\`\`typescript
+// resolvers.ts
+import { Resolvers } from './generated/graphql';
+import DataLoader from 'dataloader';
+
+export const resolvers: Resolvers = {
+  Query: {
+    user: async (_, { id }, { prisma }) => {
+      return prisma.user.findUnique({ where: { id } });
+    },
+
+    me: async (_, __, { user }) => {
+      if (!user) throw new AuthenticationError('Not authenticated');
+      return user;
+    },
+
+    posts: async (_, { first = 10, after, filter }, { prisma }) => {
+      const where = {
+        ...(filter?.status && { status: filter.status }),
+        ...(filter?.authorId && { authorId: filter.authorId }),
+        ...(filter?.search && {
+          OR: [
+            { title: { contains: filter.search } },
+            { content: { contains: filter.search } },
+          ],
+        }),
+      };
+
+      const posts = await prisma.post.findMany({
+        where,
+        take: first + 1,
+        ...(after && { cursor: { id: after }, skip: 1 }),
+        orderBy: { createdAt: 'desc' },
+      });
+
+      const hasNextPage = posts.length > first;
+      const edges = posts.slice(0, first).map((post) => ({
+        node: post,
+        cursor: post.id,
+      }));
+
+      return {
+        edges,
+        pageInfo: {
+          hasNextPage,
+          hasPreviousPage: !!after,
+          startCursor: edges[0]?.cursor,
+          endCursor: edges[edges.length - 1]?.cursor,
+        },
+        totalCount: await prisma.post.count({ where }),
+      };
+    },
+  },
+
+  Mutation: {
+    createPost: async (_, { input }, { user, prisma }) => {
+      if (!user) {
+        return { post: null, errors: [{ message: 'Not authenticated' }] };
+      }
+
+      try {
+        const post = await prisma.post.create({
+          data: { ...input, authorId: user.id },
+        });
+        return { post, errors: null };
+      } catch (error) {
+        return { post: null, errors: [{ message: 'Failed to create post' }] };
+      }
+    },
+
+    publishPost: async (_, { id }, { user, prisma }) => {
+      const post = await prisma.post.findUnique({ where: { id } });
+
+      if (!post) {
+        return { post: null, errors: [{ message: 'Post not found' }] };
+      }
+
+      if (post.authorId !== user.id) {
+        return { post: null, errors: [{ message: 'Not authorized' }] };
+      }
+
+      const updated = await prisma.post.update({
+        where: { id },
+        data: { status: 'PUBLISHED', publishedAt: new Date() },
+      });
+
+      return { post: updated, errors: null };
+    },
+  },
+
+  // Field resolvers
+  User: {
+    posts: async (user, { first, after }, { prisma }) => {
+      // Delegate to Query.posts with filter
+      return resolvers.Query.posts(
+        null,
+        { first, after, filter: { authorId: user.id } },
+        { prisma }
+      );
+    },
+  },
+
+  Post: {
+    author: async (post, _, { loaders }) => {
+      // Use DataLoader to batch & cache
+      return loaders.userLoader.load(post.authorId);
+    },
+  },
+
+  Subscription: {
+    postCreated: {
+      subscribe: (_, __, { pubsub }) => {
+        return pubsub.asyncIterator(['POST_CREATED']);
+      },
+    },
+  },
+};
+\`\`\`
+
+## DataLoader (N+1 Prevention)
+\`\`\`typescript
+// loaders.ts
+import DataLoader from 'dataloader';
+import { PrismaClient, User } from '@prisma/client';
+
+export function createLoaders(prisma: PrismaClient) {
+  return {
+    userLoader: new DataLoader<string, User>(async (ids) => {
+      const users = await prisma.user.findMany({
+        where: { id: { in: [...ids] } },
+      });
+
+      const userMap = new Map(users.map((u) => [u.id, u]));
+      return ids.map((id) => userMap.get(id) || null);
+    }),
+
+    postsByAuthorLoader: new DataLoader<string, Post[]>(async (authorIds) => {
+      const posts = await prisma.post.findMany({
+        where: { authorId: { in: [...authorIds] } },
+      });
+
+      const postsByAuthor = new Map<string, Post[]>();
+      posts.forEach((post) => {
+        const existing = postsByAuthor.get(post.authorId) || [];
+        postsByAuthor.set(post.authorId, [...existing, post]);
+      });
+
+      return authorIds.map((id) => postsByAuthor.get(id) || []);
+    }),
+  };
+}
+
+// Context setup
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  context: ({ req }) => ({
+    prisma,
+    user: req.user,
+    loaders: createLoaders(prisma),
+  }),
+});
+\`\`\`
+
+## Client Usage (Apollo Client)
+\`\`\`typescript
+// apollo-client.ts
+import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client';
+import { setContext } from '@apollo/client/link/context';
+
+const httpLink = createHttpLink({
+  uri: '/api/graphql',
+});
+
+const authLink = setContext((_, { headers }) => {
+  const token = localStorage.getItem('token');
+  return {
+    headers: {
+      ...headers,
+      authorization: token ? \`Bearer \${token}\` : '',
+    },
+  };
+});
+
+export const client = new ApolloClient({
+  link: authLink.concat(httpLink),
+  cache: new InMemoryCache({
+    typePolicies: {
+      Query: {
+        fields: {
+          posts: {
+            keyArgs: ['filter'],
+            merge(existing, incoming, { args }) {
+              if (!args?.after) return incoming;
+              return {
+                ...incoming,
+                edges: [...(existing?.edges || []), ...incoming.edges],
+              };
+            },
+          },
+        },
+      },
+    },
+  }),
+});
+
+// hooks/usePosts.ts
+import { gql, useQuery } from '@apollo/client';
+
+const GET_POSTS = gql\`
+  query GetPosts($first: Int, $after: String, $filter: PostFilterInput) {
+    posts(first: $first, after: $after, filter: $filter) {
+      edges {
+        node {
+          id
+          title
+          status
+          author {
+            id
+            name
+          }
+        }
+        cursor
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+    }
+  }
+\`;
+
+export function usePosts(filter?: PostFilterInput) {
+  const { data, loading, error, fetchMore } = useQuery(GET_POSTS, {
+    variables: { first: 10, filter },
+  });
+
+  const loadMore = () => {
+    if (!data?.posts.pageInfo.hasNextPage) return;
+
+    fetchMore({
+      variables: {
+        after: data.posts.pageInfo.endCursor,
+      },
+    });
+  };
+
+  return { posts: data?.posts.edges, loading, error, loadMore };
+}
+
+// Mutation hook
+const CREATE_POST = gql\`
+  mutation CreatePost($input: CreatePostInput!) {
+    createPost(input: $input) {
+      post {
+        id
+        title
+      }
+      errors {
+        field
+        message
+      }
+    }
+  }
+\`;
+
+export function useCreatePost() {
+  const [createPost, { loading }] = useMutation(CREATE_POST, {
+    update(cache, { data }) {
+      if (data?.createPost.post) {
+        cache.modify({
+          fields: {
+            posts(existing = { edges: [] }) {
+              const newEdge = {
+                __typename: 'PostEdge',
+                node: data.createPost.post,
+                cursor: data.createPost.post.id,
+              };
+              return {
+                ...existing,
+                edges: [newEdge, ...existing.edges],
+              };
+            },
+          },
+        });
+      }
+    },
+  });
+
+  return { createPost, loading };
+}
+\`\`\`
+
+## Error Handling
+\`\`\`typescript
+// Custom errors
+import { GraphQLError } from 'graphql';
+
+throw new GraphQLError('Not authenticated', {
+  extensions: {
+    code: 'UNAUTHENTICATED',
+    http: { status: 401 },
+  },
+});
+
+throw new GraphQLError('Resource not found', {
+  extensions: {
+    code: 'NOT_FOUND',
+    http: { status: 404 },
+  },
+});
+\`\`\`
+
+## ❌ DON'T
+- Return null without proper error handling
+- Skip DataLoader for relationship fields
+- Expose sensitive fields without authorization
+- Use deeply nested queries without limits
+- Forget input validation
+
+## ✅ DO
+- Use Relay-style pagination for lists
+- Implement DataLoader for all relationships
+- Return error payloads from mutations
+- Add query complexity limits
+- Use code generation for types
+- Implement field-level authorization
+- Cache and batch with DataLoader