GraphQL SDL Schemas, Queries & Mutations

+-----------------------------------------------------------------------------------+
| Network Request Topologies: REST vs GraphQL                                       |
|                                                                                   |
|  REST Multi-Roundtrip Waterfall (Under-fetching):                                 |
|  Client                                Server Endpoints                           |
|    |                                          |                                   |
|    |--- 1. GET /v1/users/42 ----------------->| Returns User (1.8 KB JSON)        |
|    |<-- Response (id, name, email, etc.) -----|                                   |
|    |                                          |                                   |
|    |--- 2. GET /v1/users/42/posts ----------->| Returns Posts Array (14.2 KB JSON)|
|    |<-- Response ([{ id, title, ... }]) ------|                                   |
|    |                                          |                                   |
|    |--- 3. GET /v1/posts/101/comments ------->| Returns Comments (8.5 KB JSON)    |
|    |<-- Response ([{ id, text, ... }]) -------|                                   |
|    |                                          |                                   |
|    Total Network Latency = RTT1 + RTT2 + RTT3 (3 Round-trips across WAN)          |
|    Total Payload Received = 24.5 KB (Contains 70% unused metadata)                |
|                                                                                   |
|  -------------------------------------------------------------------------------  |
|                                                                                   |
|  GraphQL Single Query Execution (Declarative Fetching):                           |
|  Client                                Single Endpoint (/graphql)                 |
|    |                                          |                                   |
|    |--- POST /graphql ----------------------->| Single Request:                   |
|    |    query {                               | - Resolves User, Posts, Comments  |
|    |      user(id: "42") {                    |   concurrently in memory          |
|    |        name                              | - Trims all unrequested fields    |
|    |        posts(limit: 5) {                 |                                   |
|    |          title                           |                                   |
|    |          comments { text }               |                                   |
|    |        }                                 |                                   |
|    |      }                                   |                                   |
|    |    }                                     |                                   |
|    |<-- Exact Response Shape (1.9 KB) --------| Returns exact JSON hierarchy      |
|                                                                                   |
|    Total Network Latency = 1 RTT (Single Round-trip)                              |
|    Total Payload Received = 1.9 KB (Zero wasted bytes, 92.2% bandwidth reduction) |
+-----------------------------------------------------------------------------------+

+-----------------------------------------------------------------------------------+
| GraphQL Type System Taxonomy                                                      |
|                                                                                   |
|  +-----------------------------------------------------------------------------+  |
|  | Root Operation Types (Entry Points)                                         |  |
|  | - Query (Read operations)                                                   |  |
|  | - Mutation (Write operations with side effects)                             |  |
|  | - Subscription (Real-time push events via WebSockets)                       |  |
|  +-------------------------------------+---------------------------------------+  |
|                                        | Defines Operations                       |
|                                        v                                          |
|  +-----------------------------------------------------------------------------+  |
|  | Composite Types (Graph Nodes)                                               |  |
|  | - Object Types (Entities: User, Product, Order)                             |  |
|  | - Interfaces (Abstract contracts implemented by Object Types)               |  |
|  | - Union Types (Disjoint polymorphic collections: SearchResult)              |  |
|  +-------------------------------------+---------------------------------------+  |
|                                        | Contains Fields of                       |
|                                        v                                          |
|  +-----------------------------------------------------------------------------+  |
|  | Leaf Types (Graph Terminals)                                                |  |
|  | - Scalar Types (Int, Float, String, Boolean, ID, Custom Scalars)            |  |
|  | - Enum Types (Fixed set of discrete string constants: Status)               |  |
|  +-----------------------------------------------------------------------------+  |
|                                        ^                                          |
|                                        | Accepts Arguments As                     |
|  +-------------------------------------+---------------------------------------+  |
|  | Input Types                                                                 |  |
|  | - Input Object Types (input CreateUserInput { ... })                        |  |
|  | - Strict validation rule: Cannot contain fields with arguments or interfaces|  |
|  +-----------------------------------------------------------------------------+  |
+-----------------------------------------------------------------------------------+

scalar DateTime
scalar EmailAddress
scalar BigInt
scalar JSON

+-----------------------------------------------------------------------------------+
| The Null Bubbling Cascade Principle                                               |
|                                                                                   |
|  Schema Definition:                                                               |
|  type Query {                                                                     |
|    user(id: ID!): User                                                            |
|  }                                                                                |
|  type User {                                                                      |
|    id: ID!                                                                        |
|    profile: Profile!  <-- Non-nullable field!                                     |
|  }                                                                                |
|  type Profile {                                                                   |
|    bio: String!       <-- Non-nullable field!                                     |
|  }                                                                                |
|                                                                                   |
|  Runtime Execution Failure:                                                       |
|  1. Database error causes Profile.bio resolver to throw an exception / return null.|
|  2. Profile.bio is non-nullable (String!), so the null violates the invariant.     |
|  3. The error bubbles up to the parent: Profile is forced to become null.         |
|  4. However, User.profile is ALSO non-nullable (Profile!).                        |
|  5. The null bubbles up again: User is forced to become null.                     |
|  6. Query.user is nullable (User), so bubbling stops at the root.                 |
|                                                                                   |
|  Resulting Payload:                                                               |
|  {                                                                                |
|    "data": { "user": null },                                                      |
|    "errors": [{ "message": "Cannot return null for non-nullable field Profile.bio"|
|  }                                                                                |
|  An entire sub-tree was obliterated due to aggressive non-nullability!           |
+-----------------------------------------------------------------------------------+

interface Node {
  id: ID!
}

interface ContentItem {
  id: ID!
  title: String!
  publishedAt: DateTime!
  author: User!
}

type Article implements ContentItem & Node {
  id: ID!
  title: String!
  publishedAt: DateTime!
  author: User!
  wordCount: Int!
  bodyHtml: String!
}

type Video implements ContentItem & Node {
  id: ID!
  title: String!
  publishedAt: DateTime!
  author: User!
  durationSeconds: Int!
  videoUrl: String!
}

union SearchResult = Article | Video | User

query GlobalSearch(term: String!) {
  search(query: term) {
    __typename
    ... on Article {
      id
      title
      wordCount
    }
    ... on Video {
      id
      title
      durationSeconds
    }
    ... on User {
      id
      displayName
      avatarUrl
    }
  }
}

query FetchUserDashboard(userId: ID!, includeTelemetry: Boolean = false) {
  user(id: userId) {
    id
    fullName
    email
    orders(limit: 5) {
      id
      totalCents
      status
    }
    telemetry @include(if: includeTelemetry) {
      lastLoginIp
      failedLoginAttempts
    }
  }
}

query CompareProfiles {
  primaryUser: user(id: "1") { name }
  secondaryUser: user(id: "2") { name }
}

mutation ExecuteSequencedOrders {
  firstOrder: createOrder(input: { sku: "ITEM-A" }) { id status }
  secondOrder: createOrder(input: { sku: "ITEM-B" }) { id status }
}

input CreateOrderInput {
  customerId: ID!
  items: [OrderItemInput!]!
  clientMutationId: String
}

type OrderError {
  field: String
  message: String!
  code: OrderErrorCode!
}

type CreateOrderPayload {
  order: Order
  errors: [OrderError!]!
  clientMutationId: String
}

type Mutation {
  createOrder(input: CreateOrderInput!): CreateOrderPayload!
}

  [ Incoming HTTP POST Payload: { "query": "...", "variables": { ... } } ]
                                      |
                                      v
  +-----------------------------------------------------------------------------+
  | Phase 1: Lexical Analysis & Parsing                                         |
  | - Lexer tokenizes raw query string.                                         |
  | - Parser constructs Abstract Syntax Tree (AST).                             |
  | - Detects syntax errors (e.g., missing closing braces).                     |
  +-------------------------------------+---------------------------------------+
                                        | Valid AST
                                        v
  +-----------------------------------------------------------------------------+
  | Phase 2: Schema Validation & Security Inspection                            |
  | - AST is validated against the GraphQL Schema definition.                   |
  | - Verifies: Do fields exist? Are arguments valid? Are types compatible?    |
  | - Security checks: Calculates query depth and complexity limits.            |
  | - Detects fragment cycles (e.g., Fragment A spreads B, B spreads A).        |
  +-------------------------------------+---------------------------------------+
                                        | Validated & Safe AST
                                        v
  +-----------------------------------------------------------------------------+
  | Phase 3: Runtime Execution & Field Resolution                               |
  | - Traverses AST nodes top-down starting at Root Query / Mutation.           |
  | - Dispatches field resolvers (parent, args, context, info).                 |
  | - Batches field database lookups via DataLoader.                            |
  | - Handles null bubbling and formats JSON error arrays.                      |
  +-------------------------------------+---------------------------------------+
                                        |
                                        v
  [ HTTP Response Payload: { "data": { ... }, "errors": [ ... ] } ]

query MaliciousDoS {
  user(id: "1") {
    posts {
      author {
        posts {
          author {
            posts {
              author {
                # Infinite recursion crashing server RAM and CPU
              }
            }
          }
        }
      }
    }
  }
}

query GetFeed {
  articles(limit: 20) {
    id
    title
    author { displayName }
    thumbnailUrl
  }
}

type Query {
  organization(id: ID!): Organization!
}

type Organization {
  id: ID!
  name: String!
  headquarters: Location!
  departments: [Department!]!
}

type Location {
  city: String!
  country: String!
  coordinates: GeoCoordinates!
}

type GeoCoordinates {
  latitude: Float!
  longitude: Float!
}

type Department {
  id: ID!
  manager: Employee!
}

type Employee {
  id: ID!
  salaryCents: Int!
}

query GetOrgData {
  organization(id: "org_99") {
    name
    headquarters {
      city
      coordinates {
        latitude
        longitude
      }
    }
    departments {
      id
      manager {
        id
        salaryCents
      }
    }
  }
}

// depth-limiter.ts
import {
  ValidationContext,
  ASTVisitor,
  FieldNode,
  InlineFragmentNode,
  FragmentSpreadNode,
  OperationDefinitionNode,
  GraphQLError
} from 'graphql';

export function createDepthLimitRule(maxDepth: number) {
  return function depthLimitValidationRule(context: ValidationContext): ASTVisitor {
    return {
      OperationDefinition(node: OperationDefinitionNode) {
        const depth = calculateNodeDepth(node, 0, context);
        if (depth > maxDepth) {
          context.reportError(
            new GraphQLError(
              `Operation '{node.name?.value || 'anonymous'}' exceeds maximum permitted query depth of {maxDepth}. Detected depth: {depth}.`,
              { nodes: [node] }
            )
          );
        }
      }
    };
  };
}

function calculateNodeDepth(node: any, currentDepth: number, context: ValidationContext): number {
  if (!node.selectionSet || !node.selectionSet.selections) {
    return currentDepth;
  }

  let maxChildDepth = currentDepth;

  for (const selection of node.selectionSet.selections) {
    let childDepth = currentDepth;

    if (selection.kind === 'Field') {
      const fieldNode = selection as FieldNode;
      // Introspection fields (__schema, __typename) do not count toward depth
      if (fieldNode.name.value.startsWith('__')) {
        continue;
      }
      childDepth = calculateNodeDepth(fieldNode, currentDepth + 1, context);
    } else if (selection.kind === 'InlineFragment') {
      const inlineFrag = selection as InlineFragmentNode;
      // Inline fragments don't increase depth on their own
      childDepth = calculateNodeDepth(inlineFrag, currentDepth, context);
    } else if (selection.kind === 'FragmentSpread') {
      const spreadNode = selection as FragmentSpreadNode;
      const fragment = context.getFragment(spreadNode.name.value);
      if (fragment) {
        childDepth = calculateNodeDepth(fragment, currentDepth, context);
      }
    }

    if (childDepth > maxChildDepth) {
      maxChildDepth = childDepth;
    }
  }

  return maxChildDepth;
}

# schema.graphql

# An ISO-8601 compliant datetime string.
scalar DateTime

# An integer strictly greater than zero.
scalar PositiveInt

enum OrderStatus {
  PENDING_PAYMENT
  PAYMENT_CONFIRMED
  PROCESSING
  DISPATCHED
  DELIVERED
  CANCELLED
}

interface Node {
  id: ID!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPrevPage: Boolean!
  startCursor: String
  endCursor: String
}

type Product implements Node {
  id: ID!
  sku: String!
  name: String!
  priceCents: PositiveInt!
  inStock: Boolean!
  createdAt: DateTime!
}

type Category implements Node {
  id: ID!
  slug: String!
  displayName: String!
  productCount: Int!
}

type Brand implements Node {
  id: ID!
  name: String!
  websiteUrl: String
}

union SearchResult = Product | Category | Brand

type OrderItem {
  product: Product!
  quantity: PositiveInt!
  unitPriceCents: PositiveInt!
}

type Order implements Node {
  id: ID!
  orderNumber: String!
  status: OrderStatus!
  items: [OrderItem!]!
  totalCents: PositiveInt!
  createdAt: DateTime!
}

type OrderEdge {
  cursor: String!
  node: Order!
}

type OrderConnection {
  edges: [OrderEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

# --- MUTATION INPUTS & PAYLOADS ---

input CartItemInput {
  productId: ID!
  quantity: PositiveInt!
}

input CheckoutOrderInput {
  customerId: ID!
  items: [CartItemInput!]!
  shippingAddressId: ID!
  clientMutationId: String
}

enum CheckoutErrorCode {
  OUT_OF_STOCK
  INVALID_PAYMENT_METHOD
  INSUFFICIENT_FUNDS
  CUSTOMER_SUSPENDED
}

type CheckoutUserError {
  field: String
  message: String!
  code: CheckoutErrorCode!
}

type CheckoutOrderPayload {
  order: Order
  userErrors: [CheckoutUserError!]!
  clientMutationId: String
}

# --- ROOT OPERATIONS ---

type Query {
  node(id: ID!): Node
  product(id: ID!): Product
  search(query: String!, limit: Int = 10): [SearchResult!]!
  orders(
    first: Int
    after: String
    status: OrderStatus
  ): OrderConnection!
}

type Mutation {
  checkoutOrder(input: CheckoutOrderInput!): CheckoutOrderPayload!
}