javi-forge 1.2.0 → 1.3.0

package/ai-config/skills/backend/graphql-concepts/SKILL.md

@@ -1,352 +0,0 @@
----
-name: graphql-concepts
-description: >
-  GraphQL concepts. Schema design, queries, mutations, subscriptions, best practices.
-  Trigger: GraphQL, schema, query, mutation, subscription, resolver
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-metadata:
-  author: apigen-team
-  version: "1.0"
-  tags: [graphql, api, schema, queries]
-  scope: ["**/graphql/**"]
----
-
-# GraphQL Concepts
-
-## Core Concepts
-
-### Schema Definition Language (SDL)
-```graphql
-# Types
-type User {
-  id: ID!
-  email: String!
-  name: String
-  posts: [Post!]!
-  createdAt: DateTime!
-}
-
-type Post {
-  id: ID!
-  title: String!
-  content: String!
-  author: User!
-  comments: [Comment!]!
-  status: PostStatus!
-}
-
-# Enums
-enum PostStatus {
-  DRAFT
-  PUBLISHED
-  ARCHIVED
-}
-
-# Input types
-input CreateUserInput {
-  email: String!
-  name: String
-  password: String!
-}
-
-# Root types
-type Query {
-  user(id: ID!): User
-  users(page: Int, size: Int): UserConnection!
-  post(id: ID!): Post
-}
-
-type Mutation {
-  createUser(input: CreateUserInput!): User!
-  updateUser(id: ID!, input: UpdateUserInput!): User!
-  deleteUser(id: ID!): Boolean!
-}
-
-type Subscription {
-  postCreated: Post!
-  commentAdded(postId: ID!): Comment!
-}
-```
-
-### Type System
-```
-Scalar Types:
-- ID: Unique identifier
-- String: UTF-8 text
-- Int: 32-bit integer
-- Float: Double-precision float
-- Boolean: true/false
-
-Custom Scalars:
-- DateTime: ISO 8601 timestamp
-- JSON: Arbitrary JSON
-- UUID: UUID string
-- URL: Valid URL
-
-Modifiers:
-- !: Non-nullable
-- []: List
-- [!]!: Non-null list of non-null items
-```
-
-## Queries
-
-### Basic Query
-```graphql
-query GetUser {
-  user(id: "123") {
-    id
-    name
-    email
-  }
-}
-```
-
-### Nested Query
-```graphql
-query GetUserWithPosts {
-  user(id: "123") {
-    id
-    name
-    posts {
-      id
-      title
-      comments {
-        id
-        content
-      }
-    }
-  }
-}
-```
-
-### Variables
-```graphql
-query GetUser($userId: ID!) {
-  user(id: $userId) {
-    id
-    name
-  }
-}
-
-# Variables:
-{
-  "userId": "123"
-}
-```
-
-### Fragments
-```graphql
-fragment UserFields on User {
-  id
-  name
-  email
-}
-
-query GetUsers {
-  user1: user(id: "1") {
-    ...UserFields
-  }
-  user2: user(id: "2") {
-    ...UserFields
-  }
-}
-```
-
-## Mutations
-
-```graphql
-mutation CreateUser($input: CreateUserInput!) {
-  createUser(input: $input) {
-    id
-    email
-    name
-  }
-}
-
-# Variables:
-{
-  "input": {
-    "email": "john@example.com",
-    "name": "John Doe",
-    "password": "SecurePass123"
-  }
-}
-```
-
-## Subscriptions
-
-```graphql
-subscription OnPostCreated {
-  postCreated {
-    id
-    title
-    author {
-      name
-    }
-  }
-}
-```
-
-## Pagination
-
-### Cursor-based (Relay Connection Spec)
-```graphql
-type UserConnection {
-  edges: [UserEdge!]!
-  pageInfo: PageInfo!
-  totalCount: Int!
-}
-
-type UserEdge {
-  cursor: String!
-  node: User!
-}
-
-type PageInfo {
-  hasNextPage: Boolean!
-  hasPreviousPage: Boolean!
-  startCursor: String
-  endCursor: String
-}
-
-# Query
-query GetUsers($first: Int, $after: String) {
-  users(first: $first, after: $after) {
-    edges {
-      cursor
-      node {
-        id
-        name
-      }
-    }
-    pageInfo {
-      hasNextPage
-      endCursor
-    }
-  }
-}
-```
-
-### Offset-based
-```graphql
-type UserPage {
-  content: [User!]!
-  page: Int!
-  size: Int!
-  totalElements: Int!
-  totalPages: Int!
-}
-
-query GetUsers($page: Int!, $size: Int!) {
-  users(page: $page, size: $size) {
-    content {
-      id
-      name
-    }
-    totalPages
-  }
-}
-```
-
-## Error Handling
-
-```graphql
-# Union approach
-union CreateUserResult = User | ValidationError | ConflictError
-
-type ValidationError {
-  field: String!
-  message: String!
-}
-
-type ConflictError {
-  message: String!
-  existingId: ID!
-}
-
-# Query
-mutation CreateUser($input: CreateUserInput!) {
-  createUser(input: $input) {
-    ... on User {
-      id
-      email
-    }
-    ... on ValidationError {
-      field
-      message
-    }
-    ... on ConflictError {
-      message
-    }
-  }
-}
-```
-
-## N+1 Problem
-
-```
-Problem:
-1. Query users (1 query)
-2. For each user, query posts (N queries)
-Total: N+1 queries
-
-Solutions:
-1. DataLoader - Batch and cache
-2. Join fetching - Eager load
-3. Look-ahead - Analyze query, optimize
-```
-
-## Security Considerations
-
-```
-Query depth limiting:
-- Prevent deeply nested queries
-- Set max depth (e.g., 10)
-
-Query complexity:
-- Assign costs to fields
-- Limit total complexity
-
-Rate limiting:
-- Per query/mutation
-- Per operation complexity
-
-Field authorization:
-- Per-field access control
-- Role-based visibility
-```
-
-## Best Practices
-
-```
-Schema Design:
-✅ Use non-null (!) where appropriate
-✅ Consistent naming (camelCase)
-✅ Avoid generic "data" fields
-✅ Use enums for fixed values
-✅ Input types for mutations
-
-Performance:
-✅ Use DataLoader for batching
-✅ Implement pagination
-✅ Limit query depth/complexity
-✅ Cache resolved data
-
-Security:
-✅ Validate input
-✅ Authorize at resolver level
-✅ Limit query complexity
-✅ Disable introspection in production
-```
-
-## Related Skills
-
-- `graphql-spring`: Spring Boot GraphQL implementation
-- `apigen-architecture`: Overall system architecture
-
-