// This is not just a type definition — it is a node in the data graph
type User {
  id: ID!
  name: String!
  orders: [Order!]!  // ← This is an EDGE: User → Order
}

type Order {
  id: ID!
  total: Float!
  items: [Item!]!   // ← This is an EDGE: Order → Item
}

type Item {
  id: ID!
  quantity: Int!
  product: Product! // ← This is an EDGE: Item → Product
}

# ❌ REST: four round trips for one page
GET /users/1
GET /users/1/orders
GET /orders/42/items
GET /items/7/product

# ✅ GraphQL: one request, client chooses the traversal depth
query GetOrderPage($userId: ID!) {
  user(id: $userId) {
    name
    orders {
      id
      total
      items {
        quantity
        product {
          title
          price
        }
      }
    }
  }
}

type Product {
  id: ID!          # → string in TypeScript (not number — ID is always a string)
  title: String!   # → string
  price: Float!    # → number
  inStock: Boolean # → boolean | null (no ! means nullable)
  tags: [String!]  # → string[] | null (the list is nullable, items are not)
}

interface SearchResult {
  id: ID!
  title: String!
}

type Article implements SearchResult {
  id: ID!
  title: String!
  publishedAt: String!
}

type Product implements SearchResult {
  id: ID!
  title: String!
  price: Float!
}

type Query {
  search(term: String!): [SearchResult!]!
}

query Search($term: String!) {
  search(term: $term) {
    id
    title
    ... on Article {
      publishedAt
    }
    ... on Product {
      price
    }
  }
}

type Query {
  user(id: ID!): User        # Read — safe to cache
  products: [Product!]!      # Read — safe to cache
}

type Mutation {
  updateUser(id: ID!, name: String!): User   # Write — invalidates cache
  placeOrder(input: OrderInput!): Order      # Write — side effects
}

type Subscription {
  orderStatusChanged(orderId: ID!): Order    # Live — WebSocket channel
}

// ❌ String interpolation — breaks security and caching
const query = `
  query {
    user(id: "${userId}") { name }
  }
`

// ✅ Variables — APQ-compatible, type-safe, injection-proof
const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) { name }
  }
`
const { data } = useQuery(GET_USER, { variables: { id: userId } })

# ❌ Anonymous — undebuggable in APM, untraceable in error logs
query {
  user(id: $id) { name }
}

# ✅ Named — shows up in Apollo Studio, Datadog, error reports, rate limits
query GetUserProfile($id: ID!) {
  user(id: $id) { name }
}

fragment UserCardFragment on User {
  id
  name
  avatarUrl
}

query GetProfilePage($id: ID!) {
  user(id: $id) {
    ...UserCardFragment
    orders { id total }
  }
}

npm install -D @graphql-codegen/cli @graphql-codegen/client-preset

// codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  schema: 'http://localhost:4000/graphql',
  documents: ['src/**/*.tsx', 'src/**/*.ts'],
  generates: {
    './src/gql/': {
      preset: 'client',  // v5 client preset — generates per-operation types
    },
  },
}
export default config

import { useQuery } from '@apollo/client'
import { graphql } from '../gql'

// graphql() is generated — it returns a TypedDocumentNode<GetUserQuery, GetUserQueryVariables>
const GET_USER = graphql(`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
      orders { id total }
    }
  }
`)

function UserProfile({ id }: { id: string }) {
  const { data } = useQuery(GET_USER, { variables: { id } })
  // data.user.name is typed — no `any`, no manual interface needed
  return <h1>{data?.user?.name}</h1>
}