# Apollo Server - Advanced Patterns

> Subscriptions, federation, and custom plugins. See [SKILL.md](../SKILL.md) for concepts and [core.md](core.md) for server setup.

**Additional Examples:**

- [core.md](core.md) - Server setup, resolvers, context, error handling
- [data-sources.md](data-sources.md) - RESTDataSource, DataLoader, caching

---

## Pattern 1: Subscriptions with graphql-ws

### Good Example - WebSocket server alongside HTTP

```typescript
import { ApolloServer } from "@apollo/server";
import { ApolloServerPluginDrainHttpServer } from "@apollo/server/plugin/drainHttpServer";
import { expressMiddleware } from "@as-integrations/express4";
import { makeExecutableSchema } from "@graphql-tools/schema";
import { WebSocketServer } from "ws";
import { useServer } from "graphql-ws/use/ws";
import { PubSub } from "graphql-subscriptions";
import express from "express";
import http from "http";
import cors from "cors";

// PubSub instance -- in-memory, dev only
// Production: use a distributed pub/sub system (Redis, Kafka, etc.)
const pubsub = new PubSub();

const POST_CREATED = "POST_CREATED";

const typeDefs = `#graphql
  type Post {
    id: ID!
    title: String!
    content: String!
  }

  type Query {
    posts: [Post!]!
  }

  type Mutation {
    createPost(title: String!, content: String!): Post!
  }

  type Subscription {
    postCreated: Post!
  }
`;

const resolvers = {
  Query: {
    posts: async (
      _parent: undefined,
      _args: Record<string, never>,
      ctx: MyContext,
    ) => {
      return ctx.dataSources.postsAPI.getAll();
    },
  },
  Mutation: {
    createPost: async (
      _parent: undefined,
      args: { title: string; content: string },
      ctx: MyContext,
    ) => {
      const post = await ctx.dataSources.postsAPI.create(args);

      // Publish event to subscribers
      await pubsub.publish(POST_CREATED, { postCreated: post });

      return post;
    },
  },
  Subscription: {
    postCreated: {
      // subscribe returns an AsyncIterator
      subscribe: () => pubsub.asyncIterator([POST_CREATED]),
      // resolve is optional -- transforms the published payload before sending
    },
  },
};

// Build executable schema (required for graphql-ws)
const schema = makeExecutableSchema({ typeDefs, resolvers });

const app = express();
const httpServer = http.createServer(app);

// WebSocket server for subscriptions
const WS_PATH = "/subscriptions";

const wsServer = new WebSocketServer({
  server: httpServer,
  path: WS_PATH,
});

const serverCleanup = useServer({ schema }, wsServer);

// Apollo Server with drain plugins for both HTTP and WS
const server = new ApolloServer<MyContext>({
  schema,
  plugins: [
    // Drain HTTP connections on shutdown
    ApolloServerPluginDrainHttpServer({ httpServer }),
    // Drain WebSocket connections on shutdown
    {
      async serverWillStart() {
        return {
          async drainServer() {
            await serverCleanup.dispose();
          },
        };
      },
    },
  ],
});

await server.start();

app.use(
  "/graphql",
  cors<cors.CorsRequest>(),
  express.json(),
  expressMiddleware(server, {
    context: async ({ req }) => ({
      dataSources: { postsAPI: new PostsAPI({ cache: server.cache }) },
    }),
  }),
);

const DEFAULT_PORT = 4000;

await new Promise<void>((resolve) => {
  httpServer.listen({ port: DEFAULT_PORT }, resolve);
});
```

**Why good:** separate drain plugins for HTTP and WebSocket, event name is a named constant, `makeExecutableSchema` creates schema usable by both Apollo Server and graphql-ws, subscription resolver returns `AsyncIterator`

### Bad Example - Missing drain and in-memory PubSub in production

```typescript
// BAD: no drain plugin for WebSocket server
const server = new ApolloServer({
  schema,
  plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
  // Missing WebSocket drain!
});

// BAD: startStandaloneServer does NOT support subscriptions
const { url } = await startStandaloneServer(server);

// BAD: in-memory PubSub doesn't work across multiple server instances
const pubsub = new PubSub(); // Fine for dev, breaks in production
```

**Why bad:** WebSocket connections hang on shutdown without drain plugin, `startStandaloneServer` has no WebSocket support, in-memory PubSub loses events across instances

---

## Pattern 2: Subscription with Filtering

### Good Example - Filtered subscriptions

```typescript
import { withFilter } from "graphql-subscriptions";

const COMMENT_ADDED = "COMMENT_ADDED";

const resolvers = {
  Subscription: {
    // Filter: only send events for the post the client is watching
    commentAdded: {
      subscribe: withFilter(
        () => pubsub.asyncIterator([COMMENT_ADDED]),
        (payload, variables) => {
          // Only send to subscribers watching this specific post
          return payload.commentAdded.postId === variables.postId;
        },
      ),
    },
  },
};

// Schema: subscription field with argument
// type Subscription {
//   commentAdded(postId: ID!): Comment!
// }
```

**Why good:** `withFilter` prevents sending events to unrelated subscribers, filter function compares payload to subscription variables, reduces unnecessary WebSocket traffic

---

## Pattern 3: Custom Plugins

### Good Example - Request logging plugin

```typescript
import type { ApolloServerPlugin } from "@apollo/server";

function requestLoggingPlugin(): ApolloServerPlugin<MyContext> {
  return {
    async requestDidStart(requestContext) {
      const operationName = requestContext.request.operationName ?? "anonymous";
      const start = Date.now();

      return {
        // Log parsing errors
        async parsingDidStart() {
          return async (err) => {
            if (err) {
              console.error(`Parse error in ${operationName}:`, err);
            }
          };
        },

        // Log validation errors
        async validationDidStart() {
          return async (errors) => {
            if (errors) {
              console.error(`Validation errors in ${operationName}:`, errors);
            }
          };
        },

        // Log all encountered errors
        async didEncounterErrors(ctx) {
          for (const err of ctx.errors) {
            console.error(
              `Error in ${operationName}:`,
              err.message,
              err.extensions,
            );
          }
        },

        // Log operation completion
        async willSendResponse() {
          const duration = Date.now() - start;
          console.log(`${operationName} completed in ${duration}ms`);
        },
      };
    },
  };
}

// Register plugin
const server = new ApolloServer<MyContext>({
  typeDefs,
  resolvers,
  plugins: [requestLoggingPlugin()],
});
```

**Why good:** typed with `ApolloServerPlugin<MyContext>`, end hooks (returned functions) capture errors from parsing/validation, timing measured from request start to response, wrapped in factory function for reuse

### Good Example - Depth limiting plugin

```typescript
import type { ApolloServerPlugin } from "@apollo/server";
import { GraphQLError } from "graphql";

const MAX_QUERY_DEPTH = 10;

function depthLimitPlugin(
  maxDepth = MAX_QUERY_DEPTH,
): ApolloServerPlugin<MyContext> {
  return {
    async requestDidStart() {
      return {
        async didResolveOperation(requestContext) {
          const { document } = requestContext;
          const depth = calculateQueryDepth(document);

          if (depth > maxDepth) {
            throw new GraphQLError(
              `Query depth ${depth} exceeds maximum of ${maxDepth}`,
              {
                extensions: { code: "QUERY_TOO_DEEP", depth, maxDepth },
              },
            );
          }
        },
      };
    },
  };
}
```

**Why good:** named constant for max depth, plugin factory accepts configuration, throws `GraphQLError` with structured extensions, runs after operation is resolved but before execution

---

## Pattern 4: Server Lifecycle Plugin

### Good Example - Graceful startup and shutdown

```typescript
import type { ApolloServerPlugin } from "@apollo/server";

function lifecyclePlugin(): ApolloServerPlugin<MyContext> {
  return {
    // Runs when server starts
    async serverWillStart() {
      console.log("Apollo Server starting...");

      // Return object with shutdown hooks
      return {
        // Runs when server begins shutdown
        async drainServer() {
          console.log("Draining server connections...");
          // Close external connections (Redis, message queues, etc.)
        },

        // Runs after all connections are drained
        async serverWillStop() {
          console.log("Server stopped.");
        },
      };
    },

    // schemaDidLoadOrUpdate is synchronous (not async)
    schemaDidLoadOrUpdate(schemaContext) {
      console.log("Schema loaded/updated");
    },
  };
}
```

**Why good:** demonstrates the full server lifecycle, `drainServer` handles cleanup before shutdown, `schemaDidLoadOrUpdate` is correctly synchronous (only lifecycle hook that is)

---

## Pattern 5: Federation Subgraph

### Good Example - Subgraph with entity resolution

```typescript
import { ApolloServer } from "@apollo/server";
import { buildSubgraphSchema } from "@apollo/subgraph";
import gql from "graphql-tag";

// Federation 2 schema with @link directive
const typeDefs = gql`
  extend schema
    @link(
      url: "https://specs.apollo.dev/federation/v2.0"
      import: ["@key", "@external", "@requires"]
    )

  type Product @key(fields: "id") {
    id: ID!
    name: String!
    price: Float!
    inStock: Boolean!
  }

  type Query {
    products: [Product!]!
    product(id: ID!): Product
  }
`;

const resolvers = {
  Query: {
    products: async (
      _parent: undefined,
      _args: Record<string, never>,
      ctx: MyContext,
    ) => {
      return ctx.dataSources.productsAPI.getAll();
    },
    product: async (
      _parent: undefined,
      args: { id: string },
      ctx: MyContext,
    ) => {
      return ctx.dataSources.productsAPI.getById(args.id);
    },
  },
  Product: {
    // Reference resolver: called by the gateway to resolve entities by @key fields
    __resolveReference: async (reference: { id: string }, ctx: MyContext) => {
      return ctx.dataSources.productsAPI.getById(reference.id);
    },
  },
};

const server = new ApolloServer({
  schema: buildSubgraphSchema({ typeDefs, resolvers }),
});
```

**Why good:** Federation 2 `@link` directive, `@key` designates entity identity, `__resolveReference` fetches entities by key for cross-subgraph resolution, `buildSubgraphSchema` adds federation metadata

### Good Example - Contributing to another subgraph's type

```typescript
// Reviews subgraph extends Product from Products subgraph
const typeDefs = gql`
  extend schema
    @link(
      url: "https://specs.apollo.dev/federation/v2.0"
      import: ["@key", "@external"]
    )

  type Review {
    id: ID!
    rating: Int!
    comment: String!
    product: Product!
  }

  # Extend Product from another subgraph
  type Product @key(fields: "id") {
    id: ID! @external
    reviews: [Review!]!
  }

  type Query {
    reviews: [Review!]!
  }
`;

const resolvers = {
  Product: {
    reviews: async (
      parent: { id: string },
      _args: Record<string, never>,
      ctx: MyContext,
    ) => {
      return ctx.dataSources.reviewsAPI.getByProductId(parent.id);
    },
  },
};
```

**Why good:** `@external` marks `id` as owned by another subgraph, `reviews` field is contributed by this subgraph, gateway composes both subgraphs into a unified API

---

## Pattern 6: Custom Directives

### Good Example - Schema directive for field-level authorization

```typescript
import { mapSchema, getDirective, MapperKind } from "@graphql-tools/utils";
import { GraphQLError } from "graphql";
import type { GraphQLSchema } from "graphql";

const AUTH_DIRECTIVE_NAME = "auth";

// Schema directive definition
// directive @auth(requires: Role = ADMIN) on FIELD_DEFINITION
// enum Role { ADMIN USER }

function authDirectiveTransformer(schema: GraphQLSchema): GraphQLSchema {
  return mapSchema(schema, {
    [MapperKind.OBJECT_FIELD]: (fieldConfig) => {
      const authDirective = getDirective(
        schema,
        fieldConfig,
        AUTH_DIRECTIVE_NAME,
      )?.[0];

      if (authDirective) {
        const { requires: requiredRole } = authDirective;
        const { resolve: originalResolve } = fieldConfig;

        fieldConfig.resolve = async (source, args, contextValue, info) => {
          if (!contextValue.user) {
            throw new GraphQLError("Authentication required", {
              extensions: { code: "UNAUTHENTICATED" },
            });
          }
          if (contextValue.user.role !== requiredRole) {
            throw new GraphQLError(`Requires ${requiredRole} role`, {
              extensions: { code: "FORBIDDEN", requiredRole },
            });
          }

          return originalResolve
            ? originalResolve(source, args, contextValue, info)
            : source[info.fieldName];
        };
      }

      return fieldConfig;
    },
  });
}

// Apply directive to schema
const schema = authDirectiveTransformer(
  makeExecutableSchema({ typeDefs, resolvers }),
);

const server = new ApolloServer({ schema });
```

**Why good:** directive transformer uses `@graphql-tools/utils` (the standard approach), wraps original resolve to preserve behavior, falls back to default field resolution, auth checks before field execution

### Usage in schema

```graphql
type Query {
  publicPosts: [Post!]!
  adminDashboard: Dashboard! @auth(requires: ADMIN)
  userProfile: Profile! @auth(requires: USER)
}
```

# Apollo Server - Core Examples

> Server setup, resolvers, context, and error handling. See [SKILL.md](../SKILL.md) for concepts and [reference.md](../reference.md) for decision frameworks.

**Additional Examples:**

- [data-sources.md](data-sources.md) - RESTDataSource, DataLoader, caching
- [advanced.md](advanced.md) - Subscriptions, federation, custom plugins

---

## Pattern 1: Standalone Server Setup

### Good Example - Typed standalone server

```typescript
import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";

// Schema definition using SDL
const typeDefs = `#graphql
  type Book {
    id: ID!
    title: String!
    author: Author!
  }

  type Author {
    id: ID!
    name: String!
    books: [Book!]!
  }

  type Query {
    books: [Book!]!
    book(id: ID!): Book
    authors: [Author!]!
  }

  type Mutation {
    addBook(title: String!, authorId: ID!): Book!
  }
`;

// Context type shared across all resolvers
interface MyContext {
  token: string | undefined;
  dataSources: {
    booksAPI: BooksAPI;
    authorsAPI: AuthorsAPI;
  };
}

// Pass context type as generic for type safety
const server = new ApolloServer<MyContext>({ typeDefs, resolvers });

const DEFAULT_PORT = 4000;

const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => {
    const token = req.headers.authorization;
    const { cache } = server;
    return {
      token,
      dataSources: {
        booksAPI: new BooksAPI({ cache, token }),
        authorsAPI: new AuthorsAPI({ cache }),
      },
    };
  },
  listen: { port: DEFAULT_PORT },
});

console.log(`Server ready at ${url}`);
```

**Why good:** generic type parameter ensures context type safety across resolvers, new data source instances per request prevent data leaks, named constant for port

### Bad Example - Shared instances and no types

```typescript
import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";

// BAD: data sources created once and shared across all requests
const booksAPI = new BooksAPI();
const authorsAPI = new AuthorsAPI();

const server = new ApolloServer({ typeDefs, resolvers }); // No context type

const { url } = await startStandaloneServer(server, {
  context: async () => ({
    dataSources: { booksAPI, authorsAPI }, // BAD: shared instances
  }),
  listen: { port: 4000 }, // BAD: magic number
});
```

**Why bad:** shared data source instances leak cached data between requests and users, missing generic type means resolver context is `any`, magic port number

---

## Pattern 2: Framework Middleware Integration

### Good Example - Express integration with graceful shutdown

```typescript
import { ApolloServer } from "@apollo/server";
import { ApolloServerPluginDrainHttpServer } from "@apollo/server/plugin/drainHttpServer";
// v5: import from integration package (not @apollo/server/express4)
import { expressMiddleware } from "@as-integrations/express4";
import express from "express";
import http from "http";
import cors from "cors";

interface MyContext {
  token: string | undefined;
  dataSources: { booksAPI: BooksAPI };
}

const app = express();
const httpServer = http.createServer(app);

const server = new ApolloServer<MyContext>({
  typeDefs,
  resolvers,
  plugins: [
    // REQUIRED: enables graceful shutdown
    ApolloServerPluginDrainHttpServer({ httpServer }),
  ],
});

// MUST call start() before using expressMiddleware
await server.start();

const GRAPHQL_PATH = "/graphql";
const ALLOWED_ORIGINS = ["https://app.example.com"];

app.use(
  GRAPHQL_PATH,
  cors<cors.CorsRequest>({ origin: ALLOWED_ORIGINS }),
  express.json(),
  expressMiddleware(server, {
    context: async ({ req }) => {
      const token = req.headers.authorization;
      const { cache } = server;
      return {
        token,
        dataSources: {
          booksAPI: new BooksAPI({ cache, token }),
        },
      };
    },
  }),
);

const DEFAULT_PORT = 4000;

await new Promise<void>((resolve) => {
  httpServer.listen({ port: DEFAULT_PORT }, resolve);
});

console.log(`Server ready at http://localhost:${DEFAULT_PORT}${GRAPHQL_PATH}`);
```

**Why good:** drain plugin enables graceful shutdown, `server.start()` called before middleware, CORS configured with specific origins, new data source per request

### Bad Example - Missing drain plugin and calling start too late

```typescript
// BAD: no drain plugin
const server = new ApolloServer({ typeDefs, resolvers });

// BAD: using removed v4 import path
import { expressMiddleware } from "@apollo/server/express4";

// BAD: missing server.start() before middleware
app.use("/graphql", expressMiddleware(server)); // Throws!

// BAD: wildcard CORS with no configuration
app.use(cors()); // Allows all origins
```

**Why bad:** no drain plugin means connections hang on shutdown, v4 import path removed in v5, missing `start()` throws at runtime, wildcard CORS is a security risk

---

## Pattern 3: Resolver Patterns

### Good Example - Typed resolvers with parent chaining

```typescript
import { GraphQLError } from "graphql";

const resolvers = {
  Query: {
    // Top-level resolver: parent is undefined
    books: async (
      _parent: undefined,
      _args: Record<string, never>,
      contextValue: MyContext,
    ) => {
      return contextValue.dataSources.booksAPI.getAllBooks();
    },

    // Args typed from schema
    book: async (
      _parent: undefined,
      args: { id: string },
      contextValue: MyContext,
    ) => {
      const book = await contextValue.dataSources.booksAPI.getBook(args.id);
      if (!book) {
        throw new GraphQLError(`Book with id "${args.id}" not found`, {
          extensions: { code: "NOT_FOUND" },
        });
      }
      return book;
    },
  },

  // Field resolver: parent is the Book returned by Query.book
  Book: {
    author: async (
      parent: Book,
      _args: Record<string, never>,
      contextValue: MyContext,
    ) => {
      return contextValue.dataSources.authorsAPI.getAuthor(parent.authorId);
    },
  },

  // Field resolver: parent is the Author
  Author: {
    books: async (
      parent: Author,
      _args: Record<string, never>,
      contextValue: MyContext,
    ) => {
      return contextValue.dataSources.booksAPI.getBooksByAuthor(parent.id);
    },
  },

  Mutation: {
    addBook: async (
      _parent: undefined,
      args: { title: string; authorId: string },
      contextValue: MyContext,
    ) => {
      if (!contextValue.token) {
        throw new GraphQLError("Authentication required", {
          extensions: { code: "UNAUTHENTICATED" },
        });
      }
      return contextValue.dataSources.booksAPI.addBook(
        args.title,
        args.authorId,
      );
    },
  },
};
```

**Why good:** parent type matches return type of parent resolver, data access delegated to data sources, auth check before mutation, `GraphQLError` with codes for client-facing errors

### Bad Example - Fat resolvers with direct data access

```typescript
const resolvers = {
  Query: {
    books: async () => {
      // BAD: direct DB call in resolver -- not testable, not reusable
      const result = await db.query("SELECT * FROM books");
      return result.rows;
    },
    book: async (_parent, args) => {
      const result = await db.query("SELECT * FROM books WHERE id = $1", [
        args.id,
      ]);
      if (!result.rows[0]) {
        // BAD: generic Error exposes stack trace
        throw new Error("Not found");
      }
      return result.rows[0];
    },
  },
};
```

**Why bad:** direct database calls make resolvers untestable and non-reusable, generic `Error` exposes internals to client, no context usage means no per-request isolation

---

## Pattern 4: Error Handling

### Good Example - Custom error codes and formatError

```typescript
import { GraphQLError } from "graphql";
import { ApolloServerErrorCode } from "@apollo/server/errors";
import { unwrapResolverError } from "@apollo/server/errors";

// Custom error codes for your domain
const ErrorCode = {
  NOT_FOUND: "NOT_FOUND",
  UNAUTHENTICATED: "UNAUTHENTICATED",
  FORBIDDEN: "FORBIDDEN",
  VALIDATION_ERROR: "VALIDATION_ERROR",
  RATE_LIMITED: "RATE_LIMITED",
} as const;

// Reusable error factory
function notFoundError(resource: string, id: string): GraphQLError {
  return new GraphQLError(`${resource} with id "${id}" not found`, {
    extensions: {
      code: ErrorCode.NOT_FOUND,
      resource,
      id,
    },
  });
}

function authError(message: string): GraphQLError {
  return new GraphQLError(message, {
    extensions: { code: ErrorCode.UNAUTHENTICATED },
  });
}

// formatError to sanitize errors before sending to clients
const server = new ApolloServer<MyContext>({
  typeDefs,
  resolvers,
  formatError: (formattedError, error) => {
    // Unwrap resolver errors to access the original error
    const originalError = unwrapResolverError(error);

    // Log internal errors for debugging
    if (
      formattedError.extensions?.code ===
      ApolloServerErrorCode.INTERNAL_SERVER_ERROR
    ) {
      console.error("Internal error:", originalError);
    }

    // Never send stack traces to clients in production
    // (Apollo Server already strips them when NODE_ENV=production)
    return {
      message: formattedError.message,
      extensions: {
        code: formattedError.extensions?.code,
      },
    };
  },
});
```

**Why good:** named error code constants, reusable error factories, `formatError` sanitizes internal details, `unwrapResolverError` accesses original error for logging

### Bad Example - Leaking internal details

```typescript
const resolvers = {
  Query: {
    user: async (_parent, args, contextValue) => {
      try {
        return await contextValue.dataSources.usersAPI.getUser(args.id);
      } catch (error) {
        // BAD: leaks database error message to client
        throw new Error(`Database query failed: ${error.message}`);
      }
    },
  },
};
```

**Why bad:** database error messages leak to clients, no error code for client-side handling, no structured extensions

---

## Pattern 5: Schema Organization

### Good Example - Modular schema with type composition

```typescript
// types/book.ts - Schema fragment for books
export const bookTypeDefs = `#graphql
  type Book {
    id: ID!
    title: String!
    publishedYear: Int!
    author: Author!
  }

  input CreateBookInput {
    title: String!
    publishedYear: Int!
    authorId: ID!
  }

  extend type Query {
    books(limit: Int, offset: Int): [Book!]!
    book(id: ID!): Book
  }

  extend type Mutation {
    createBook(input: CreateBookInput!): Book!
    deleteBook(id: ID!): Boolean!
  }
`;

// types/author.ts - Schema fragment for authors
export const authorTypeDefs = `#graphql
  type Author {
    id: ID!
    name: String!
    books: [Book!]!
  }

  extend type Query {
    authors: [Author!]!
    author(id: ID!): Author
  }
`;

// schema.ts - Root schema assembles fragments
const rootTypeDefs = `#graphql
  type Query
  type Mutation
`;

const server = new ApolloServer<MyContext>({
  // typeDefs accepts an array -- fragments are merged
  typeDefs: [rootTypeDefs, bookTypeDefs, authorTypeDefs],
  resolvers: [bookResolvers, authorResolvers],
});
```

**Why good:** each domain owns its schema fragment, `extend type` adds fields without modifying root types, `typeDefs` array merges fragments automatically, resolvers also merge from arrays

### Bad Example - Monolithic schema

```typescript
// BAD: 500+ line SDL in a single string
const typeDefs = `#graphql
  type Book { ... }
  type Author { ... }
  type Publisher { ... }
  type Review { ... }
  # ... 50 more types
  type Query {
    # ... 30 query fields
  }
  type Mutation {
    # ... 20 mutation fields
  }
`;
```

**Why bad:** single-file schema becomes unmaintainable, can't tell which team/module owns which types, merge conflicts in version control

---

## Pattern 6: Authentication in Context

### Good Example - Auth verification in context function

```typescript
interface MyContext {
  user: User | null;
  dataSources: { usersAPI: UsersAPI };
}

const server = new ApolloServer<MyContext>({ typeDefs, resolvers });

const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => {
    const token = req.headers.authorization?.replace("Bearer ", "");

    // Verify token and get user (null if invalid/missing)
    let user: User | null = null;
    if (token) {
      try {
        user = await verifyAndDecodeToken(token);
      } catch {
        // Invalid token -- user stays null, resolvers decide what to allow
      }
    }

    return {
      user,
      dataSources: {
        usersAPI: new UsersAPI({ cache: server.cache }),
      },
    };
  },
});

// In resolvers: check auth where needed
const resolvers = {
  Mutation: {
    deleteBook: async (
      _parent: undefined,
      args: { id: string },
      contextValue: MyContext,
    ) => {
      if (!contextValue.user) {
        throw new GraphQLError("Authentication required", {
          extensions: { code: "UNAUTHENTICATED" },
        });
      }
      if (contextValue.user.role !== "admin") {
        throw new GraphQLError("Admin access required", {
          extensions: { code: "FORBIDDEN" },
        });
      }
      return contextValue.dataSources.booksAPI.deleteBook(args.id);
    },
  },
};
```

**Why good:** context function handles token verification once per request, resolvers check `contextValue.user` for auth, invalid tokens don't crash the context function, role-based authorization at the resolver level

# Apollo Server - Data Sources

> RESTDataSource, DataLoader, and caching patterns. See [SKILL.md](../SKILL.md) for concepts and [core.md](core.md) for server setup.

**Additional Examples:**

- [core.md](core.md) - Server setup, resolvers, context, error handling
- [advanced.md](advanced.md) - Subscriptions, federation, custom plugins

---

## Pattern 1: RESTDataSource

### Good Example - Typed REST API wrapper with caching

```typescript
import { RESTDataSource, type AugmentedRequest } from "@apollo/datasource-rest";
import type { KeyValueCache } from "@apollo/utils.keyvaluecache";

interface Movie {
  id: string;
  title: string;
  releaseYear: number;
}

interface MoviesResponse {
  results: Movie[];
  total: number;
}

const DEFAULT_PAGE_SIZE = 20;

class MoviesAPI extends RESTDataSource {
  override baseURL = "https://movies-api.example.com/v1/";

  // Add auth headers to all outgoing requests
  override willSendRequest(_path: string, request: AugmentedRequest) {
    request.headers.authorization = this.token;
  }

  private token: string;

  constructor(options: { cache: KeyValueCache; token: string }) {
    super(options); // passes cache to parent
    this.token = options.token;
  }

  // GET with query params
  async getMovies(
    page = 1,
    pageSize = DEFAULT_PAGE_SIZE,
  ): Promise<MoviesResponse> {
    return this.get<MoviesResponse>("movies", {
      params: {
        page: page.toString(),
        page_size: pageSize.toString(),
      },
    });
  }

  // GET with dynamic path segment -- ALWAYS encode user input
  async getMovie(id: string): Promise<Movie> {
    return this.get<Movie>(`movies/${encodeURIComponent(id)}`);
  }

  // POST with JSON body
  async createMovie(input: {
    title: string;
    releaseYear: number;
  }): Promise<Movie> {
    return this.post<Movie>("movies", {
      body: input,
    });
  }

  // PUT replaces entire resource
  async updateMovie(id: string, input: Partial<Movie>): Promise<Movie> {
    return this.put<Movie>(`movies/${encodeURIComponent(id)}`, {
      body: input,
    });
  }

  // PATCH for partial updates
  async patchMovie(id: string, input: Partial<Movie>): Promise<Movie> {
    return this.patch<Movie>(`movies/${encodeURIComponent(id)}`, {
      body: input,
    });
  }

  // DELETE
  async deleteMovie(id: string): Promise<void> {
    await this.delete(`movies/${encodeURIComponent(id)}`);
  }
}
```

**Why good:** typed return values, `willSendRequest` adds auth to every request, `encodeURIComponent` prevents path traversal, cache passed through constructor, named constant for page size

### Bad Example - Missing security and no types

```typescript
class MoviesAPI extends RESTDataSource {
  override baseURL = "https://movies-api.example.com/v1/";

  // BAD: no encodeURIComponent -- path traversal vulnerability
  async getMovie(id: string) {
    return this.get(`movies/${id}`);
  }

  // BAD: no type parameter -- return type is unknown
  async getMovies() {
    return this.get("movies");
  }
}
```

**Why bad:** unencoded user input enables path traversal attacks, untyped responses require unsafe casts downstream

---

## Pattern 2: RESTDataSource Caching Control

### Good Example - Custom cache TTL and deduplication

```typescript
import { RESTDataSource } from "@apollo/datasource-rest";
import type { RequestDeduplicationPolicy } from "@apollo/datasource-rest";

const CACHE_TTL_SECONDS = 300; // 5 minutes

class CatalogAPI extends RESTDataSource {
  override baseURL = "https://catalog-api.example.com/";

  // Override HTTP cache TTL (ignores response cache-control headers)
  override cacheOptionsFor() {
    return { ttl: CACHE_TTL_SECONDS };
  }

  // Override cache key (default is method + URL)
  override cacheKeyFor(url: URL, request: RequestInit) {
    // Include auth header in cache key so different users get different results
    const auth =
      (request.headers as Record<string, string>)?.authorization ?? "anonymous";
    return `${request.method}:${url.toString()}:${auth}`;
  }

  // Control request deduplication behavior
  override requestDeduplicationPolicyFor(
    url: URL,
    request: RequestInit,
  ): RequestDeduplicationPolicy {
    if (request.method === "GET") {
      // Default: deduplicate concurrent GET requests
      return {
        policy: "deduplicate-during-request-lifetime",
        deduplicationKey: url.toString(),
      };
    }
    // Don't deduplicate mutations
    return { policy: "do-not-deduplicate" };
  }

  async getProductById(id: string): Promise<Product> {
    return this.get<Product>(`products/${encodeURIComponent(id)}`);
  }

  async getCategories(): Promise<Category[]> {
    return this.get<Category[]>("categories");
  }
}
```

**Why good:** explicit cache TTL, cache key includes auth for user-specific data, deduplication policy documented, named constant for TTL

---

## Pattern 3: DataLoader for N+1 Prevention

### Good Example - Batched loading in context

```typescript
import DataLoader from "dataloader";

// Batch function: receives array of keys, returns array of results in same order
async function batchUsers(ids: readonly string[]): Promise<(User | Error)[]> {
  // Single query fetches all requested users
  const users = await db.users.findMany({
    where: { id: { in: [...ids] } },
  });

  // Map results to match input order -- DataLoader requires 1:1 correspondence
  const userMap = new Map(users.map((u) => [u.id, u]));
  return ids.map((id) => userMap.get(id) ?? new Error(`User ${id} not found`));
}

// Context factory -- new DataLoader per request
interface MyContext {
  loaders: {
    userLoader: DataLoader<string, User>;
    postLoader: DataLoader<string, Post[]>;
  };
}

const server = new ApolloServer<MyContext>({ typeDefs, resolvers });

const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => ({
    loaders: {
      // CRITICAL: new instances per request -- DataLoader caches for request lifetime
      userLoader: new DataLoader<string, User>(batchUsers),
      postLoader: new DataLoader<string, Post[]>(batchPostsByAuthor),
    },
  }),
});

// In resolvers: use loader instead of direct calls
const resolvers = {
  Post: {
    author: async (
      parent: Post,
      _args: Record<string, never>,
      contextValue: MyContext,
    ) => {
      // If 50 posts reference 10 unique authors, this makes 1 batch call, not 50
      return contextValue.loaders.userLoader.load(parent.authorId);
    },
  },
  Author: {
    posts: async (
      parent: Author,
      _args: Record<string, never>,
      contextValue: MyContext,
    ) => {
      return contextValue.loaders.postLoader.load(parent.id);
    },
  },
};
```

**Why good:** batch function fetches all users in one query, result mapping preserves DataLoader's required order, new loaders per request prevent stale data, type parameters ensure key/value types match

### Bad Example - Direct calls causing N+1

```typescript
const resolvers = {
  Post: {
    // BAD: called once per post in the list -- N+1 queries
    author: async (parent, _args, contextValue) => {
      return contextValue.dataSources.usersAPI.getUser(parent.authorId);
    },
  },
};
// If query returns 50 posts, this makes 50 separate getUser calls
```

**Why bad:** each post triggers a separate database/API call, query with 50 posts makes 51 total calls (1 for posts + 50 for authors)

---

## Pattern 4: Combining RESTDataSource with DataLoader

### Good Example - DataLoader inside RESTDataSource

```typescript
import { RESTDataSource } from "@apollo/datasource-rest";
import DataLoader from "dataloader";

class UsersAPI extends RESTDataSource {
  override baseURL = "https://users-api.example.com/";

  // Private DataLoader as implementation detail
  private batchLoader = new DataLoader<string, User>(async (ids) => {
    // Single batch request for multiple IDs
    const users = await this.get<User[]>("users", {
      params: { ids: [...ids].join(",") },
    });
    const userMap = new Map(users.map((u) => [u.id, u]));
    return ids.map(
      (id) => userMap.get(id) ?? new Error(`User ${id} not found`),
    );
  });

  // Public API uses DataLoader internally
  async getUser(id: string): Promise<User> {
    return this.batchLoader.load(id);
  }

  // Non-batched operations bypass DataLoader
  async searchUsers(query: string): Promise<User[]> {
    return this.get<User[]>("users/search", {
      params: { q: query },
    });
  }
}
```

**Why good:** DataLoader is an internal optimization detail, callers use simple `getUser(id)` API, batch requests combine multiple IDs into one HTTP call, RESTDataSource's deduplication layer still applies

---

## Pattern 5: Database Data Source Pattern

### Good Example - Typed database data source

```typescript
// Custom data source class (no base class needed for databases)
class BooksDataSource {
  private db: DatabaseConnection;

  constructor(db: DatabaseConnection) {
    this.db = db;
  }

  async getAll(limit: number, offset: number): Promise<Book[]> {
    return this.db.query<Book>(
      "SELECT * FROM books ORDER BY created_at DESC LIMIT $1 OFFSET $2",
      [limit, offset],
    );
  }

  async getById(id: string): Promise<Book | null> {
    const [book] = await this.db.query<Book>(
      "SELECT * FROM books WHERE id = $1",
      [id],
    );
    return book ?? null;
  }

  async getByAuthorId(authorId: string): Promise<Book[]> {
    return this.db.query<Book>("SELECT * FROM books WHERE author_id = $1", [
      authorId,
    ]);
  }

  async create(input: { title: string; authorId: string }): Promise<Book> {
    const [book] = await this.db.query<Book>(
      "INSERT INTO books (title, author_id) VALUES ($1, $2) RETURNING *",
      [input.title, input.authorId],
    );
    return book;
  }
}

// In context function
const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => {
    const db = await getDbConnection();
    return {
      dataSources: {
        books: new BooksDataSource(db),
      },
    };
  },
});
```

**Why good:** data source encapsulates all SQL, resolver only calls `dataSources.books.getById(id)`, new instance per request with dedicated connection, typed return values