query GetUsersWithOrders {
  users {
    id
    name
    orders {
      id
      total
      items {
        product { title }
      }
    }
  }
}

// ❌ The N+1 resolver — looks harmless, is catastrophic in production
const resolvers = {
  Query: {
    users: async (_, __, ctx) => {
      return ctx.db.query('SELECT * FROM users LIMIT 50');
      // Returns 50 users. Now the runtime calls User.orders 50 times.
    },
  },
  User: {
    orders: async (user, _, ctx) => {
      // 💥 This fires 50 times — once per user
      // In development: 50 × 0.3ms = 15ms total (invisible)
      // In production: 50 × 50ms = 2,500ms (2.5 second page load from DB alone)
      return ctx.db.query('SELECT * FROM orders WHERE user_id = $1', [user.id]);
    },
  },
};

// ✅ The correct resolver with DataLoader
import DataLoader from 'dataloader';
import type { User, Order } from './types';

// The batchLoadFn contract:
// - Receives: an array of keys (user IDs) collected across all resolver calls in one tick
// - Returns: a Promise resolving to an array of values IN THE SAME ORDER as the input keys
//
// This is the most critical invariant: if keys are [1, 3, 2] and DB returns
// rows in ID order [1, 2, 3], you must re-order to [user1, user3, user2].
// Returning in wrong order silently maps data to the wrong parent.
async function batchLoadOrders(userIds: readonly string[]): Promise<Order[][]> {
  const rows = await db.query(
    'SELECT * FROM orders WHERE user_id = ANY($1)',
    [userIds]
  );

  // Group by user_id and return in the same order as userIds
  const ordersByUserId = new Map<string, Order[]>();
  for (const row of rows) {
    const existing = ordersByUserId.get(row.user_id) ?? [];
    existing.push(row);
    ordersByUserId.set(row.user_id, existing);
  }

  // CRITICAL: return in exactly the same order as the input keys
  return userIds.map((id) => ordersByUserId.get(id) ?? []);
}

// Usage in resolvers:
const resolvers = {
  User: {
    orders: async (user, _, ctx) => {
      // This does NOT immediately fire a DB query.
      // It registers user.id with the DataLoader for this tick.
      // After all 50 User.orders resolver calls have registered their keys,
      // DataLoader fires ONE batched query: WHERE user_id IN (1,2,3,...,50)
      return ctx.ordersLoader.load(user.id);
    },
  },
};

WITHOUT DataLoader (N+1):
  SELECT * FROM orders WHERE user_id = 1;   -- ~50ms
  SELECT * FROM orders WHERE user_id = 2;   -- ~50ms
  SELECT * FROM orders WHERE user_id = 3;   -- ~50ms
  -- ... (47 more queries)
  -- Total: 50 × 50ms = 2,500ms

WITH DataLoader (1 batch):
  SELECT * FROM orders WHERE user_id = ANY('{1,2,3,...,50}');  -- ~55ms
  -- Total: 1 × 55ms = 55ms

import DataLoader from 'dataloader';

const ordersLoader = new DataLoader(batchLoadOrders, {
  // v2: limits how many keys are batched in a single batchLoadFn call
  // Without this, a single tick with 10,000 resolver calls produces a
  // query with 10,000 IDs — which may exceed DB parameter limits or
  // cause the query planner to skip index usage.
  maxBatchSize: 500,

  // v2: replaces the default setTimeout(resolve, 0) batching window
  // Useful for replacing Node.js microtask-based batching with a
  // custom timing strategy in high-throughput event loops
  batchScheduleFn: (callback) => setTimeout(callback, 0),

  // Cache: per-request cache (prevents double-loading the same key in one request)
  // Set to false if your data is write-heavy and cache invalidation is complex
  cache: true,
});

// ❌ Module-level singleton DataLoader — leaks user data across requests
// Because DataLoader has an internal cache, User A's request could return
// cached data from User B's previous request that resolved the same key.
// This is a data leakage vulnerability, not just a staleness bug.
const globalOrdersLoader = new DataLoader(batchLoadOrders); // ❌ Never do this

const resolvers = {
  User: {
    // This loader's cache persists across all requests on this process
    orders: async (user) => globalOrdersLoader.load(user.id), // ❌
  },
};

// ✅ Per-request DataLoader creation via the context factory
import type { IncomingMessage, ServerResponse } from 'http';
import DataLoader from 'dataloader';
import { db } from './db';

// The context interface — typed per-request state
interface GraphQLContext {
  user: AuthenticatedUser | null;
  ordersLoader: DataLoader<string, Order[]>;
  productsLoader: DataLoader<string, Product>;
  db: typeof db;
}

// This factory function runs ONCE per request, not once per server start
async function createContext(req: IncomingMessage): Promise<GraphQLContext> {
  const user = await authenticateRequest(req);

  return {
    user,
    // ✅ Fresh DataLoader instances per request
    // Each request gets its own cache and batch window
    ordersLoader: new DataLoader<string, Order[]>(batchLoadOrders),
    productsLoader: new DataLoader<string, Product>(batchLoadProducts),
    db,
  };
}

// In graphql-yoga:
const yoga = createYoga({
  schema,
  context: createContext, // yoga calls this per request
});

// ✅ Pothos DataLoader plugin — eliminates the any cast in batchLoadFn
import PothosDataLoader from '@pothos/plugin-dataloader';

const builder = new SchemaBuilder({
  plugins: [PothosDataLoader],
});

// The plugin infers the key type from the object type's identifier
builder.objectType('User', {
  dataloader: {
    // Type-safe: TypeScript knows batchLoadFn receives string[] not any[]
    load: async (ids: string[], ctx: GraphQLContext) => {
      return ctx.db.users.findManyByIds(ids);
    },
    toKey: (user) => user.id, // How to extract the key from the parent object
  },
  fields: (t) => ({
    orders: t.loadMany({
      load: async (ids: string[], ctx: GraphQLContext) => {
        const rows = await ctx.db.orders.findByUserIds(ids);
        const grouped = groupBy(rows, 'userId');
        return ids.map((id) => grouped[id] ?? []);
      },
    }),
  }),
});

const resolvers = {
  Query: {
    user: async (_, { id }, ctx) => {
      const user = await ctx.db.users.findById(id);

      // ✅ Return null when the entity legitimately does not exist.
      // GraphQL interprets null as "no data for this field" — not an error.
      // The client receives { data: { user: null } } with no errors array.
      if (!user) return null;

      return user;
    },
  },
};

import { GraphQLError } from 'graphql';

const resolvers = {
  Query: {
    user: async (_, { id }, ctx) => {
      // ✅ Throw when the failure is operational — not a "not found" case
      if (!ctx.user) {
        throw new GraphQLError('Authentication required', {
          extensions: {
            code: 'UNAUTHENTICATED',
            // Machine-readable code — the client error handler keys on this
            // NOT on the message string (which can change without warning)
          },
        });
      }

      if (!ctx.user.canAccessUser(id)) {
        throw new GraphQLError('Insufficient permissions', {
          extensions: { code: 'FORBIDDEN' },
        });
      }

      const user = await ctx.db.users.findById(id);
      if (!user) return null; // ← null, not throw — entity doesn't exist

      return user;
    },
  },
};

import { createYoga } from 'graphql-yoga';
import { useDataLoader } from '@graphql-yoga/plugin-dataloader';
import { schema } from './schema';

const yoga = createYoga({
  schema,
  plugins: [
    useDataLoader({
      // The plugin creates a fresh DataLoader per request, automatically
      // scoped to the request context — no manual createContext factory required
      ordersLoader: ({ context }) =>
        new DataLoader<string, Order[]>(
          async (userIds) => batchLoadOrders(userIds, context.db)
        ),
      productsLoader: ({ context }) =>
        new DataLoader<string, Product>(
          async (productIds) => batchLoadProducts(productIds, context.db)
        ),
    }),
  ],
});