Architecture Teardown: tRPC 11 vs GraphQL 2026 API Schema Design for TypeScript 5.6 Apps

// tRPC 11 Server + Client Example (TypeScript 5.6)
// Dependencies: @trpc/server@11.0.0-beta.4, @trpc/client@11.0.0-beta.4, zod@3.25.0, express@4.18.0, @trpc/server/express
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
import express from 'express';
import { createExpressMiddleware } from '@trpc/server/express';
import { createTRPCClient, httpBatchLink } from '@trpc/client';

// 1. Initialize tRPC with context type for TypeScript 5.6 type safety
interface AppContext {
  user?: { id: string; role: 'admin' | 'user' };
  req: express.Request;
}

const t = initTRPC.context().create({
  errorFormatter({ shape, error }) {
    return {
      ...shape,
      data: {
        ...shape.data,
        zodError: error.cause instanceof z.ZodError ? error.cause.flatten() : null,
      },
    };
  },
});

// 2. Define tRPC router with CRUD procedures
const appRouter = t.router({
  // Health check procedure
  health: t.procedure.query(() => {
    return { status: 'ok', timestamp: new Date().toISOString() };
  }),

  // Get user by ID (protected, requires auth)
  getUser: t.procedure
    .input(z.object({ userId: z.string().uuid() }))
    .query(({ input, ctx }) => {
      if (!ctx.user) {
        throw new t.TRPCError({ code: 'UNAUTHORIZED', message: 'Authentication required' });
      }
      // Mock database call
      const mockUsers = new Map();
      mockUsers.set('123e4567-e89b-12d3-a456-426614174000', { id: '123e4567-e89b-12d3-a456-426614174000', name: 'Alice', role: 'admin' });

      const user = mockUsers.get(input.userId);
      if (!user) {
        throw new t.TRPCError({ code: 'NOT_FOUND', message: `User ${input.userId} not found` });
      }
      // Check authorization: admins can see any user, users can only see themselves
      if (ctx.user.role !== 'admin' && ctx.user.id !== input.userId) {
        throw new t.TRPCError({ code: 'FORBIDDEN', message: 'Insufficient permissions' });
      }
      return user;
    }),

  // Create user (admin only)
  createUser: t.procedure
    .input(z.object({
      name: z.string().min(2).max(50),
      role: z.enum(['admin', 'user']).default('user'),
    }))
    .mutation(({ input, ctx }) => {
      if (!ctx.user || ctx.user.role !== 'admin') {
        throw new t.TRPCError({ code: 'FORBIDDEN', message: 'Admin access required' });
      }
      // Mock user creation
      const newUser = {
        id: crypto.randomUUID(),
        ...input,
      };
      return { success: true, user: newUser };
    }),
});

// 3. Create Express server with tRPC middleware
const app = express();
app.use(express.json());

// Context creation middleware
app.use((req, _res, next) => {
  // Mock auth: extract user from Authorization header
  const authHeader = req.headers.authorization;
  let user: AppContext['user'] = undefined;
  if (authHeader?.startsWith('Bearer ')) {
    const token = authHeader.slice(7);
    // Mock token validation
    if (token === 'admin-token') {
      user = { id: 'admin-1', role: 'admin' };
    } else if (token === 'user-token') {
      user = { id: 'user-1', role: 'user' };
    }
  }
  req.trpcContext = { user, req };
  next();
});

// Mount tRPC middleware
app.use('/trpc', createExpressMiddleware({
  router: appRouter,
  createContext: ({ req }) => req.trpcContext,
}));

// 4. tRPC Client setup (TypeScript 5.6)
const trpcClient = createTRPCClient({
  links: [
    httpBatchLink({
      url: 'http://localhost:3000/trpc',
      headers() {
        return { authorization: 'Bearer admin-token' };
      },
    }),
  ],
});

// 5. Example client call with error handling
async function testTRPCClient() {
  try {
    const health = await trpcClient.health.query();
    console.log('Health check:', health);

    const newUser = await trpcClient.createUser.mutate({ name: 'Bob', role: 'user' });
    console.log('Created user:', newUser);

    const fetchedUser = await trpcClient.getUser.query({ userId: newUser.user.id });
    console.log('Fetched user:', fetchedUser);
  } catch (error) {
    if (error instanceof t.TRPCClientError) {
      console.error('tRPC Error:', error.message, error.data);
    } else {
      console.error('Unexpected error:', error);
    }
  }
}

// Start server
const PORT = 3000;
app.listen(PORT, () => {
  console.log(`tRPC 11 server running on http://localhost:${PORT}`);
  testTRPCClient();
});

// Export router type for client type safety
export type AppRouter = typeof appRouter;

// GraphQL 2026 Server + Client Example (TypeScript 5.6)
// Dependencies: graphql@16.9.0, @graphql-tools/schema@10.1.0, express-graphql@0.12.0, apollo-client@3.12.0, zod@3.25.0
import { GraphQLSchema, GraphQLObjectType, GraphQLString, GraphQLNonNull, GraphQLID, GraphQLInputObjectType, GraphQLEnumType, GraphQLList } from 'graphql';
import { makeExecutableSchema } from '@graphql-tools/schema';
import express from 'express';
import graphqlHTTP from 'express-graphql';
import { ApolloClient, InMemoryCache, gql, HttpLink } from '@apollo/client';
import { z } from 'zod';

// 1. Define GraphQL Schema (GraphQL 2026 syntax)
const RoleEnum = new GraphQLEnumType({
  name: 'Role',
  values: {
    ADMIN: { value: 'admin' },
    USER: { value: 'user' },
  },
});

const UserType = new GraphQLObjectType({
  name: 'User',
  fields: {
    id: { type: new GraphQLNonNull(GraphQLID) },
    name: { type: new GraphQLNonNull(GraphQLString) },
    role: { type: new GraphQLNonNull(RoleEnum) },
  },
});

const CreateUserInput = new GraphQLInputObjectType({
  name: 'CreateUserInput',
  fields: {
    name: { type: new GraphQLNonNull(GraphQLString) },
    role: { type: RoleEnum, defaultValue: 'user' },
  },
});

const RootQuery = new GraphQLObjectType({
  name: 'Query',
  fields: {
    health: {
      type: new GraphQLObjectType({
        name: 'HealthResponse',
        fields: {
          status: { type: new GraphQLNonNull(GraphQLString) },
          timestamp: { type: new GraphQLNonNull(GraphQLString) },
        },
      }),
      resolve: () => ({ status: 'ok', timestamp: new Date().toISOString() }),
    },
    getUser: {
      type: UserType,
      args: {
        userId: { type: new GraphQLNonNull(GraphQLID) },
      },
      resolve: (_parent, args, context) => {
        if (!context.user) {
          throw new Error('UNAUTHORIZED: Authentication required');
        }
        // Mock database
        const mockUsers = new Map();
        mockUsers.set('123e4567-e89b-12d3-a456-426614174000', { id: '123e4567-e89b-12d3-a456-426614174000', name: 'Alice', role: 'admin' });

        const user = mockUsers.get(args.userId);
        if (!user) {
          throw new Error(`NOT_FOUND: User ${args.userId} not found`);
        }
        if (context.user.role !== 'admin' && context.user.id !== args.userId) {
          throw new Error('FORBIDDEN: Insufficient permissions');
        }
        return user;
      },
    },
  },
});

const RootMutation = new GraphQLObjectType({
  name: 'Mutation',
  fields: {
    createUser: {
      type: new GraphQLObjectType({
        name: 'CreateUserResponse',
        fields: {
          success: { type: new GraphQLNonNull(GraphQLString) },
          user: { type: UserType },
        },
      }),
      args: {
        input: { type: new GraphQLNonNull(CreateUserInput) },
      },
      resolve: (_parent, args, context) => {
        if (!context.user || context.user.role !== 'admin') {
          throw new Error('FORBIDDEN: Admin access required');
        }
        // Validate input with Zod (GraphQL 2026 supports Zod integration)
        const inputSchema = z.object({
          name: z.string().min(2).max(50),
          role: z.enum(['admin', 'user']).default('user'),
        });
        const validatedInput = inputSchema.parse(args.input);
        // Mock creation
        const newUser = {
          id: crypto.randomUUID(),
          ...validatedInput,
        };
        return { success: 'true', user: newUser };
      },
    },
  },
});

// 2. Create executable schema
const schema = makeExecutableSchema({
  typeDefs: `
    enum Role { ADMIN USER }
    type User { id: ID! name: String! role: Role! }
    input CreateUserInput { name: String! role: Role = USER }
    type HealthResponse { status: String! timestamp: String! }
    type CreateUserResponse { success: String! user: User }
    type Query { health: HealthResponse! getUser(userId: ID!): User }
    type Mutation { createUser(input: CreateUserInput!): CreateUserResponse! }
  `,
  resolvers: {
    Query: RootQuery.getFields(),
    Mutation: RootMutation.getFields(),
  },
});

// 3. Express server setup
const app = express();
app.use(express.json());

// Auth middleware to populate context
app.use((req, _res, next) => {
  const authHeader = req.headers.authorization;
  let user: { id: string; role: 'admin' | 'user' } | undefined = undefined;
  if (authHeader?.startsWith('Bearer ')) {
    const token = authHeader.slice(7);
    if (token === 'admin-token') user = { id: 'admin-1', role: 'admin' };
    else if (token === 'user-token') user = { id: 'user-1', role: 'user' };
  }
  req.graphqlContext = { user };
  next();
});

// Mount GraphQL middleware
app.use('/graphql', graphqlHTTP((req) => ({
  schema,
  context: req.graphqlContext,
  graphiql: true,
})));

// 4. Apollo Client setup (TypeScript 5.6)
const apolloClient = new ApolloClient({
  link: new HttpLink({
    uri: 'http://localhost:4000/graphql',
    headers: { authorization: 'Bearer admin-token' },
  }),
  cache: new InMemoryCache(),
});

// 5. Example client query with error handling
async function testGraphQLClient() {
  try {
    const healthQuery = gql`
      query { health { status timestamp } }
    `;
    const healthRes = await apolloClient.query({ query: healthQuery });
    console.log('GraphQL Health:', healthRes.data.health);

    const createUserMutation = gql`
      mutation CreateUser($input: CreateUserInput!) {
        createUser(input: $input) {
          success
          user { id name role }
        }
      }
    `;
    const createRes = await apolloClient.mutate({
      mutation: createUserMutation,
      variables: { input: { name: 'Bob', role: 'USER' } },
    });
    console.log('Created user:', createRes.data.createUser.user);

    const getUserQuery = gql`
      query GetUser($userId: ID!) {
        getUser(userId: $userId) { id name role }
      }
    `;
    const getRes = await apolloClient.query({
      query: getUserQuery,
      variables: { userId: createRes.data.createUser.user.id },
    });
    console.log('Fetched user:', getRes.data.getUser);
  } catch (error) {
    console.error('GraphQL Error:', error);
  }
}

// Start server
const PORT = 4000;
app.listen(PORT, () => {
  console.log(`GraphQL 2026 server running on http://localhost:${PORT}/graphql`);
  testGraphQLClient();
});

// Benchmark Script: tRPC 11 vs GraphQL 2026 (TypeScript 5.6, k6 0.52.0)
// Run with: k6 run --out json=benchmark.json benchmark.ts
import http from 'k6/http';
import { check, sleep } from 'k6';
import { Trend, Rate } from 'k6/metrics';
import { randomString } from 'https://jslib.k6.io/k6-utils/1.4.0/index.js';

// Custom metrics
const trpcLatency = new Trend('trpc_latency');
const graphqlLatency = new Trend('graphql_latency');
const trpcErrorRate = new Rate('trpc_error_rate');
const graphqlErrorRate = new Rate('graphql_error_rate');

// Benchmark configuration
const TRPC_URL = 'http://localhost:3000/trpc/getUser';
const GRAPHQL_URL = 'http://localhost:4000/graphql';
const AUTH_TOKEN = 'Bearer admin-token';
const TEST_USER_ID = '123e4567-e89b-12d3-a456-426614174000';
const VUS = 100; // 100 virtual users
const DURATION = '30s'; // 30 second test

// k6 options
export const options = {
  vus: VUS,
  duration: DURATION,
  thresholds: {
    trpc_latency: ['p(50)<200', 'p(99)<300'], // tRPC target: p50 <200ms, p99 <300ms
    graphqlLatency: ['p(50)<300', 'p(99)<400'], // GraphQL target: p50 <300ms, p99 <400ms
    trpc_error_rate: ['rate<0.01'], // <1% error rate
    graphql_error_rate: ['rate<0.01'],
  },
};

// tRPC 11 batch request payload (tRPC uses batch link by default)
const trpcPayload = JSON.stringify([
  {
    id: randomString(10),
    method: 'query',
    params: {
      path: 'getUser',
      input: { userId: TEST_USER_ID },
    },
  },
]);

// GraphQL request payload
const graphqlPayload = JSON.stringify({
  query: `
    query GetUser($userId: ID!) {
      getUser(userId: $userId) {
        id
        name
        role
      }
    }
  `,
  variables: { userId: TEST_USER_ID },
});

export default function () {
  // Test tRPC 11 endpoint
  const trpcRes = http.post(TRPC_URL, trpcPayload, {
    headers: {
      'Content-Type': 'application/json',
      Authorization: AUTH_TOKEN,
    },
  });

  // Record tRPC metrics
  trpcLatency.add(trpcRes.timings.duration);
  const trpcSuccess = check(trpcRes, {
    'tRPC status is 200': (r) => r.status === 200,
    'tRPC response has user': (r) => JSON.parse(r.body)[0].result.data.name === 'Alice',
  });
  trpcErrorRate.add(!trpcSuccess);

  // Test GraphQL 2026 endpoint
  const graphqlRes = http.post(GRAPHQL_URL, graphqlPayload, {
    headers: {
      'Content-Type': 'application/json',
      Authorization: AUTH_TOKEN,
    },
  });

  // Record GraphQL metrics
  graphqlLatency.add(graphqlRes.timings.duration);
  const graphqlSuccess = check(graphqlRes, {
    'GraphQL status is 200': (r) => r.status === 200,
    'GraphQL response has user': (r) => JSON.parse(r.body).data.getUser.name === 'Alice',
  });
  graphqlErrorRate.add(!graphqlSuccess);

  // Sleep to simulate real user behavior
  sleep(1);
}

// Benchmark summary (runs after test)
export function handleSummary(data: any) {
  const trpcP50 = data.metrics.trpc_latency.values.p50;
  const trpcP99 = data.metrics.trpc_latency.values.p99;
  const graphqlP50 = data.metrics.graphql_latency.values.p50;
  const graphqlP99 = data.metrics.graphql_latency.values.p99;
  const trpcThroughput = data.metrics.http_reqs.values.rate * (VUS / 2); // split VUs between both
  const graphqlThroughput = data.metrics.http_reqs.values.rate * (VUS / 2);

  return {
    stdout: `
=== Benchmark Results (TypeScript 5.6, Node 22.9, AWS t4g.medium) ===
tRPC 11 (v11.0.0-beta.4):
  p50 Latency: ${trpcP50.toFixed(2)}ms
  p99 Latency: ${trpcP99.toFixed(2)}ms
  Throughput: ${trpcThroughput.toFixed(2)} req/s

GraphQL 2026 (graphql@16.9.0):
  p50 Latency: ${graphqlP50.toFixed(2)}ms
  p99 Latency: ${graphqlP99.toFixed(2)}ms
  Throughput: ${graphqlThroughput.toFixed(2)} req/s

Performance Gap (tRPC vs GraphQL):
  p50 Latency: ${((graphqlP50 - trpcP50) / graphqlP50 * 100).toFixed(2)}% faster
  p99 Latency: ${((graphqlP99 - trpcP99) / graphqlP99 * 100).toFixed(2)}% faster
    `,
  };
}

const updateUser = t.procedure
  .input(z.object({
    userId: z.string().uuid(),
    name: z.string().min(2).max(50).optional(),
    role: z.enum(['admin', 'user']).optional(),
  }).strict())
  .mutation(({ input, ctx }) => {
    // TypeScript knows input is { userId: string; name?: string; role?: 'admin' | 'user' }
    // Strict mode throws error if unknown fields are passed
  });

// codegen.ts (GraphQL 2026)
import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: 'http://localhost:4000/graphql',
  documents: ['src/**/*.graphql'],
  generates: {
    'src/generated/graphql.ts': {
      plugins: ['typescript', 'typescript-operations', 'typescript-react-apollo'],
      config: {
        strict: true,
        useTypeImports: true, // TypeScript 5.6 supports type-only imports natively
        constEnums: true, // Use const enums for better tree-shaking
        enumsAsTypes: true, // Use TypeScript enums instead of union strings
      },
    },
  },
};

export default config;

// Instrumented tRPC procedure (TypeScript 5.6)
const getUsers = t.procedure
  .input(z.object({ page: z.number().min(1).default(1) }))
  .query(async ({ input, ctx }) => {
    performance.mark('getUsers-start');

    // Simulate database query
    const users = await db.user.findMany({ take: 10, skip: (input.page - 1) * 10 });

    performance.mark('getUsers-db-end');
    performance.measure('getUsers-db', 'getUsers-start', 'getUsers-db-end');

    // Log performance entry
    const measure = performance.getEntriesByName('getUsers-db')[0];
    console.log(`DB query took ${measure.duration.toFixed(2)}ms`);

    performance.mark('getUsers-end');
    performance.measure('getUsers-total', 'getUsers-start', 'getUsers-end');

    return users;
  });

const legacyGraphQLUser = t.procedure
  .input(z.object({ userId: z.string().uuid() }))
  .query(async ({ input }) => {
    const res = await fetch('http://localhost:4000/graphql', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        query: `query GetUser($userId: ID!) { getUser(userId: $userId) { id name role } }`,
        variables: { userId: input.userId },
      }),
    });
    const data = await res.json();
    return data.data.getUser;
  });