Implementing GraphQL APIs with TypeScript

title: Implementing GraphQL APIs with TypeScript
description: Enforce best practices for building and consuming GraphQL APIs in TypeScript applications.
category: TypeScript Cursor Rules
rules:
  - id: graphql-schema-naming-conventions
    description: Ensure consistent naming conventions in GraphQL schemas.
    pattern: |
      type [A-Z][a-zA-Z0-9]* {
        [a-z][a-zA-Z0-9]*: [A-Za-z][a-zA-Z0-9]*!
      }
    message: "Type names should be in PascalCase, and field names in camelCase."
    severity: error
    references:
      - https://compositecode.blog/2023/07/24/graphql-schema-standards/

  - id: graphql-fragments-for-type-safety
    description: Utilize GraphQL fragments to enhance type safety and maintainability.
    pattern: |
      fragment [A-Z][a-zA-Z0-9]* on [A-Z][a-zA-Z0-9]* {
        [a-z][a-zA-Z0-9]*: [A-Za-z][a-zA-Z0-9]*!
      }
    message: "Define reusable fragments to ensure consistent and type-safe data structures."
    severity: warning
    references:
      - https://the-guild.dev/blog/graphql-with-typescript-done-right

  - id: graphql-pagination-implementation
    description: Implement pagination for handling large datasets in GraphQL queries.
    pattern: |
      type [A-Z][a-zA-Z0-9]*Connection {
        edges: \[[A-Z][a-zA-Z0-9]*Edge\]!
        pageInfo: PageInfo!
      }
    message: "Use connection types with edges and pageInfo for efficient pagination."
    severity: error
    references:
      - https://compositecode.blog/2023/08/01/graphql-best-practices-imho/

  - id: graphql-error-handling
    description: Standardize error handling in GraphQL APIs.
    pattern: |
      type Error {
        message: String!
        code: String!
      }
    message: "Define a consistent Error type with message and code fields for error responses."
    severity: warning
    references:
      - https://compositecode.blog/2023/08/01/graphql-best-practices-imho/

  - id: typescript-strict-mode
    description: Enforce strict mode in TypeScript for enhanced type safety.
    pattern: |
      "strict": true
    message: "Enable 'strict' mode in tsconfig.json to catch potential type errors."
    severity: error
    references:
      - https://medium.com/@nikhithsomasani/best-practices-for-using-typescript-in-2025-a-guide-for-experienced-developers-4fca1cfdf052

  - id: typescript-template-literal-types
    description: Leverage template literal types for dynamic string-based types.
    pattern: |
      type [A-Z][a-zA-Z0-9]* = `api/\${[a-z][a-zA-Z0-9]*}`;
    message: "Use template literal types to enforce specific string patterns."
    severity: warning
    references:
      - https://medium.com/@nikhithsomasani/best-practices-for-using-typescript-in-2025-a-guide-for-experienced-developers-4fca1cfdf052

  - id: typescript-satisfies-operator
    description: Use the 'satisfies' operator for type assertions.
    pattern: |
      const [a-z][a-zA-Z0-9]* = { [a-z][a-zA-Z0-9]*: [a-zA-Z0-9]* } satisfies { [a-z][a-zA-Z0-9]*: [A-Za-z][a-zA-Z0-9]* };
    message: "Apply the 'satisfies' operator to enforce type constraints while maintaining flexibility."
    severity: warning
    references:
      - https://medium.com/@nikhithsomasani/best-practices-for-using-typescript-in-2025-a-guide-for-experienced-developers-4fca1cfdf052

  - id: typescript-utility-types
    description: Utilize TypeScript utility types for type transformations.
    pattern: |
      type [A-Z][a-zA-Z0-9]* = Partial<[A-Z][a-zA-Z0-9]*>;
    message: "Use utility types like Partial, Pick, Omit, etc., for efficient type transformations."
    severity: warning
    references:
      - https://medium.com/@nikhithsomasani/best-practices-for-using-typescript-in-2025-a-guide-for-experienced-developers-4fca1cfdf052

  - id: typescript-as-const
    description: Prefer 'as const' for exact type matches.
    pattern: |
      const [a-z][a-zA-Z0-9]* = \[[a-zA-Z0-9, ]*\] as const;
    message: "Use 'as const' to ensure literals are inferred as their exact types."
    severity: warning
    references:
      - https://medium.com/@nikhithsomasani/best-practices-for-using-typescript-in-2025-a-guide-for-experienced-developers-4fca1cfdf052

  - id: typescript-avoid-any-unknown
    description: Avoid overusing 'any' and 'unknown' types.
    pattern: |
      function [a-z][a-zA-Z0-9]*\([a-z][a-zA-Z0-9]*: any\) {
        // ...
      }
    message: "Limit the use of 'any' and 'unknown' types to maintain type safety."
    severity: error
    references:
      - https://medium.com/@nikhithsomasani/best-practices-for-using-typescript-in-2025-a-guide-for-experienced-developers-4fca1cfdf052

  - id: typescript-runtime-validation
    description: Integrate runtime validation with libraries like 'zod' or 'io-ts'.
    pattern: |
      import { z } from 'zod';
      const [A-Z][a-zA-Z0-9]*Schema = z.object({
        [a-z][a-zA-Z0-9]*: z.[a-zA-Z0-9]*(),
      });
    message: "Use runtime validation libraries to complement TypeScript's compile-time checks."
    severity: warning
    references:
      - https://medium.com/@nikhithsomasani/best-practices-for-using-typescript-in-2025-a-guide-for-experienced-developers-4fca1cfdf052