# schema.graphql
type User {
  id: ID!
  name: String!
  email: String!
  orders: [Order!]!
}

type Order {
  id: ID!
  total: Float!
  items: [OrderItem!]!
}

type Query {
  user(id: ID!): User
}

// ❌ Schema-first with hand-written types — drift is guaranteed at scale
// The resolver type here is manually maintained; any SDL change that isn't
// reflected here compiles fine but fails at runtime.
const resolvers: Resolvers = {
  Query: {
    user: async (_, { id }, context) => {
      return context.db.users.findById(id);
    },
  },
};

// ✅ Code-first with Pothos v4 — SDL is generated from type-safe definitions
import SchemaBuilder from '@pothos/core';

const builder = new SchemaBuilder<{
  Context: { db: DatabaseClient };
}>();

const UserRef = builder.objectRef<{ id: string; name: string; email: string }>('User');

UserRef.implement({
  fields: (t) => ({
    id: t.exposeID('id'),
    name: t.exposeString('name'),
    email: t.exposeString('email'),
    orders: t.field({
      type: [OrderRef],
      resolve: async (user, _, ctx) => ctx.db.orders.findByUserId(user.id),
    }),
  }),
});

builder.queryField('user', (t) =>
  t.field({
    type: UserRef,
    nullable: true,
    args: { id: t.arg.id({ required: true }) },
    resolve: async (_, { id }, ctx) => ctx.db.users.findById(id),
  })
);

# ❌ Database-mirrored schema — exposes implementation, traps evolution
type users_table {
  user_id: Int!          # DB column name exposed directly
  created_at: String!    # Leaks storage layer
  updated_at: String!    # Leaks storage layer
}

type orders_table {
  order_id: Int!
  user_id: Int!          # Join table foreign key leaked to client
  order_total: Float!    # Column alias leaked
}

type Query {
  getOrdersByUserId(userId: Int!): [orders_table]   # Endpoint-style, not traversal
  getUserByEmail(email: String!): users_table        # GET /users?email= in disguise
}

# ✅ Domain-contract schema — traversal model, semantic types, no implementation leak
type User {
  id: ID!                   # Stable semantic ID — UUID, not DB integer
  name: String!
  email: String!
  orders(first: Int, after: String): OrderConnection!   # Traversal, not endpoint
  createdAt: DateTime!      # Semantic scalar, not raw String
}

type Order {
  id: ID!
  total: Money!             # Semantic type, not Float
  status: OrderStatus!      # Enum — not a raw String column
  items: [OrderItem!]!
}

enum OrderStatus {
  PENDING
  CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED
}

type Query {
  user(id: ID!): User       # Node query — graph traversal entry point
  viewer: User              # Current authenticated user — no ID argument needed
}

// ✅ Use graphql-scalars v2 instead of defining empty scalar stubs
import { DateTimeResolver, MoneyResolver, UUIDResolver } from 'graphql-scalars';

// In Pothos:
builder.addScalarType('DateTime', DateTimeResolver, {});
builder.addScalarType('UUID', UUIDResolver, {});

# ❌ Over-aggressive non-null — a federation subgraph outage makes this a lie
type User {
  id: ID!
  name: String!        # You are guaranteeing this NEVER returns null.
                       # If your DB is down, what happens?
  loyaltyPoints: Int!  # What if the loyalty service is unavailable?
}

# ✅ Non-null only where the guarantee is unconditional
type User {
  id: ID!              # Always present — existence precondition
  name: String!        # Core identity field — always populated at write time
  email: String!       # Always populated at registration
  loyaltyPoints: Int   # nullable — external service; may be unavailable
  preferredAddress: Address  # nullable — optional relationship
}

# ✅ Input type non-null semantics — required fields at write time
input CreateOrderInput {
  userId: ID!          # Required — no order without an owner
  items: [OrderItemInput!]!  # Required — no empty orders
  shippingAddressId: ID      # Optional — may use account default
  notes: String              # Optional — free-form
}

# ❌ Inline arguments — adding a new required arg is a breaking change
type Mutation {
  createOrder(userId: ID!, items: [ID!]!, addressId: ID!): Order!
}

# Adding `couponCode` as a new required arg breaks every existing client operation.
# Even adding it as optional changes the resolver signature.

# ✅ Input type — safe to add optional fields forever
type Mutation {
  createOrder(input: CreateOrderInput!): CreateOrderPayload!
}

input CreateOrderInput {
  userId: ID!
  items: [OrderItemInput!]!
  addressId: ID
  couponCode: String     # Added in v2 — zero breaking change for existing clients
  giftMessage: String    # Added in v3 — still zero breaking change
}

# Wrapping the return in a Payload type allows adding fields to the response
# without a breaking change as well.
type CreateOrderPayload {
  order: Order
  errors: [UserError!]!
}

# Scenario: A notification feed returns different notification types
interface Notification {
  id: ID!
  createdAt: DateTime!
  read: Boolean!
}

type OrderNotification implements Notification {
  id: ID!
  createdAt: DateTime!
  read: Boolean!
  order: Order!
  message: String!
}

type SystemNotification implements Notification {
  id: ID!
  createdAt: DateTime!
  read: Boolean!
  severity: NotificationSeverity!
  body: String!
}

// ✅ __resolveType is required for interface resolution
const NotificationResolver = {
  Notification: {
    __resolveType(obj: { order?: unknown; severity?: unknown }) {
      if (obj.order !== undefined) return 'OrderNotification';
      if (obj.severity !== undefined) return 'SystemNotification';
      return null;
    },
  },
};

# Scenario: Search returns heterogeneous result types with no shared fields
union SearchResult = User | Product | Article | BlogPost

type Query {
  search(query: String!, first: Int): [SearchResult!]!
}

query Search($q: String!) {
  search(query: $q, first: 10) {
    ... on User { id name }
    ... on Product { id title price }
    ... on Article { id headline slug }
  }
}

type User {
  # ❌ This marks the field — it does NOT remove it, hide it, or notify clients.
  # Client tooling (Apollo Studio, GraphQL IDE) will show a warning.
  # The field is still fully executable. Traffic continues until clients migrate.
  email: String @deprecated(reason: "Use `primaryEmail` instead. Removal planned: 2026-Q4.")
  primaryEmail: EmailAddress!
}

# With @semanticNonNull (Stage 2 RFC, not yet stable):
type User {
  id: ID!                        # Hard non-null: guaranteed by existence
  name: String @semanticNonNull  # Non-null in the happy path, but nullable on resolver error
                                 # Clients can treat it as non-null for rendering
                                 # but error boundaries still catch resolver failures
}