feat(gql): support TypedDocumentNode

Uses DocumentNode in GraphQL tests

feat: remove @graphql-typed-document-node/core and duplicate `TypedDocumentNode` interface

fix: eslint issues

test: TypedDocumentNode expected typings

Adds positive assertions to "graphql.test-d.ts"

Author: longility

package.json

@@ -87,6 +87,7 @@
   "devDependencies": {
     "@babel/core": "^7.14.3",
     "@babel/preset-env": "^7.14.2",
+    "@graphql-typed-document-node/core": "^3.1.0",
     "@open-draft/test-server": "^0.2.3",
     "@rollup/plugin-commonjs": "^19.0.0",
     "@rollup/plugin-inject": "^4.0.2",

src/graphql.ts

@@ -1,3 +1,4 @@
+import { DocumentNode } from 'graphql'
 import { Mask } from './setupWorker/glossary'
 import { ResponseResolver } from './handlers/RequestHandler'
 import {
@@ -9,6 +10,18 @@ import {
   GraphQLHandlerNameSelector,
 } from './handlers/GraphQLHandler'
 
+export interface TypedDocumentNode<
+  Result = {
+    [key: string]: any
+  },
+  Variables = {
+    [key: string]: any
+  }
+> extends DocumentNode {
+  __resultType?: Result
+  __variablesType?: Variables
+}
+
 function createScopedGraphQLHandler(
   operationType: ExpectedOperationTypeNode,
   url: Mask,
@@ -17,7 +30,10 @@ function createScopedGraphQLHandler(
     Query extends Record<string, any>,
     Variables extends GraphQLVariables = GraphQLVariables
   >(
-    operationName: GraphQLHandlerNameSelector,
+    operationName:
+      | GraphQLHandlerNameSelector
+      | DocumentNode
+      | TypedDocumentNode<Query, Variables>,
     resolver: ResponseResolver<
       GraphQLRequest<Variables>,
       GraphQLContext<Query>

src/handlers/GraphQLHandler.test.ts

@@ -1,3 +1,4 @@
+import { parse } from 'graphql'
 import { Headers } from 'headers-utils/lib'
 import { context } from '..'
 import { createMockedRequest } from '../../test/support/utils'
@@ -7,6 +8,7 @@ import {
   GraphQLHandler,
   GraphQLRequest,
   GraphQLRequestBody,
+  isDocumentNode,
 } from './GraphQLHandler'
 import { MockedRequest, ResponseResolver } from './RequestHandler'
 
@@ -79,6 +81,51 @@ describe('info', () => {
     expect(handler.info).toHaveProperty('operationType', 'mutation')
     expect(handler.info).toHaveProperty('operationName', 'Login')
   })
+
+  test('parses a query operation name from a given DocumentNode', () => {
+    const node = parse(`
+      query GetUser {
+        user {
+          firstName
+        }
+      }
+    `)
+
+    const handler = new GraphQLHandler('query', node, '*', resolver)
+
+    expect(handler.info).toHaveProperty('header', 'query GetUser (origin: *)')
+    expect(handler.info).toHaveProperty('operationType', 'query')
+    expect(handler.info).toHaveProperty('operationName', 'GetUser')
+  })
+
+  test('parses a mutation operation name from a given DocumentNode', () => {
+    const node = parse(`
+      mutation Login {
+        user {
+          id
+        }
+      }
+    `)
+    const handler = new GraphQLHandler('mutation', node, '*', resolver)
+
+    expect(handler.info).toHaveProperty('header', 'mutation Login (origin: *)')
+    expect(handler.info).toHaveProperty('operationType', 'mutation')
+    expect(handler.info).toHaveProperty('operationName', 'Login')
+  })
+
+  test('throws an exception given a DocumentNode with a mismatched operation type', () => {
+    const node = parse(`
+      mutation CreateUser {
+        user {
+          firstName
+        }
+      }
+    `)
+
+    expect(() => new GraphQLHandler('query', node, '*', resolver)).toThrow(
+      'Failed to create a GraphQL handler: provided a DocumentNode with a mismatched operation type (expected "query", but got "mutation").',
+    )
+  })
 })
 
 describe('parse', () => {
@@ -371,3 +418,25 @@ describe('run', () => {
     expect(result).toBeNull()
   })
 })
+
+describe('isDocumentNode', () => {
+  it('returns true given a valid DocumentNode', () => {
+    const node = parse(`
+      query GetUser {
+        user {
+          login
+        }
+      }
+    `)
+
+    expect(isDocumentNode(node)).toEqual(true)
+  })
+
+  it('returns false given an arbitrary input', () => {
+    expect(isDocumentNode(null)).toEqual(false)
+    expect(isDocumentNode(undefined)).toEqual(false)
+    expect(isDocumentNode('')).toEqual(false)
+    expect(isDocumentNode('value')).toEqual(false)
+    expect(isDocumentNode(/value/)).toEqual(false)
+  })
+})

src/handlers/GraphQLHandler.ts

@@ -1,4 +1,4 @@
-import { OperationTypeNode } from 'graphql'
+import { DocumentNode, OperationTypeNode } from 'graphql'
 import { Mask, SerializedResponse } from '../setupWorker/glossary'
 import { set } from '../context/set'
 import { status } from '../context/status'
@@ -21,12 +21,13 @@ import {
   ParsedGraphQLRequest,
   GraphQLMultipartRequestBody,
   parseGraphQLRequest,
+  parseDocumentNode,
 } from '../utils/internal/parseGraphQLRequest'
 import { getPublicUrlFromRequest } from '../utils/request/getPublicUrlFromRequest'
 import { tryCatch } from '../utils/internal/tryCatch'
 
 export type ExpectedOperationTypeNode = OperationTypeNode | 'all'
-export type GraphQLHandlerNameSelector = RegExp | string
+export type GraphQLHandlerNameSelector = DocumentNode | RegExp | string
 
 // GraphQL related context should contain utility functions
 // useful for GraphQL. Functions like `xml()` bear no value
@@ -74,6 +75,16 @@ export interface GraphQLRequest<Variables extends GraphQLVariables>
   variables: Variables
 }
 
+export function isDocumentNode(
+  value: DocumentNode | any,
+): value is DocumentNode {
+  if (value == null) {
+    return false
+  }
+
+  return typeof value === 'object' && 'kind' in value && 'definitions' in value
+}
+
 export class GraphQLHandler<
   Request extends GraphQLRequest<any> = GraphQLRequest<any>
 > extends RequestHandler<
@@ -90,16 +101,36 @@ export class GraphQLHandler<
     endpoint: Mask,
     resolver: ResponseResolver<any, any>,
   ) {
+    let resolvedOperationName = operationName
+
+    if (isDocumentNode(operationName)) {
+      const parsedNode = parseDocumentNode(operationName)
+
+      if (parsedNode.operationType !== operationType) {
+        throw new Error(
+          `Failed to create a GraphQL handler: provided a DocumentNode with a mismatched operation type (expected "${operationType}", but got "${parsedNode.operationType}").`,
+        )
+      }
+
+      if (!parsedNode.operationName) {
+        throw new Error(
+          `Failed to create a GraphQL handler: provided a DocumentNode with no operation name.`,
+        )
+      }
+
+      resolvedOperationName = parsedNode.operationName
+    }
+
     const header =
       operationType === 'all'
         ? `${operationType} (origin: ${endpoint.toString()})`
-        : `${operationType} ${operationName} (origin: ${endpoint.toString()})`
+        : `${operationType} ${resolvedOperationName} (origin: ${endpoint.toString()})`
 
     super({
       info: {
         header,
         operationType,
-        operationName,
+        operationName: resolvedOperationName,
       },
       ctx: graphqlContext,
       resolver,

src/utils/internal/parseGraphQLRequest.ts

@@ -1,4 +1,9 @@
-import { OperationDefinitionNode, OperationTypeNode, parse } from 'graphql'
+import {
+  DocumentNode,
+  OperationDefinitionNode,
+  OperationTypeNode,
+  parse,
+} from 'graphql'
 import { GraphQLVariables } from '../../handlers/GraphQLHandler'
 import { MockedRequest } from '../../handlers/RequestHandler'
 import { getPublicUrlFromRequest } from '../request/getPublicUrlFromRequest'
@@ -22,18 +27,21 @@ export type ParsedGraphQLRequest<
     })
   | undefined
 
+export function parseDocumentNode(node: DocumentNode): ParsedGraphQLQuery {
+  const operationDef = node.definitions.find((def) => {
+    return def.kind === 'OperationDefinition'
+  }) as OperationDefinitionNode
+
+  return {
+    operationType: operationDef?.operation,
+    operationName: operationDef?.name?.value,
+  }
+}
+
 function parseQuery(query: string): ParsedGraphQLQuery | Error {
   try {
     const ast = parse(query)
-
-    const operationDef = ast.definitions.find((def) => {
-      return def.kind === 'OperationDefinition'
-    }) as OperationDefinitionNode
-
-    return {
-      operationType: operationDef?.operation,
-      operationName: operationDef?.name?.value,
-    }
+    return parseDocumentNode(ast)
   } catch (error) {
     return error
   }

test/typings/graphql.test-d.ts

@@ -1,4 +1,6 @@
+import { parse } from 'graphql'
 import { graphql } from 'msw'
+import { GetUserDetailDocument, LoginDocument } from 'graphql.test-data'
 
 graphql.query<{ key: string }>('', (req, res, ctx) => {
   return res(
@@ -50,3 +52,89 @@ graphql.operation<
 >((req, res, ctx) => {
   return res(ctx.data({ key: 'pass' }))
 })
+
+/**
+ * Supports `DocumentNode` as the GraphQL operation name.
+ */
+const getUser = parse(`
+  query GetUser {
+    user {
+      firstName
+    }
+  }
+`)
+graphql.query(getUser, (req, res, ctx) =>
+  res(
+    ctx.data({
+      // Cannot extract query type from the runtime `DocumentNode`.
+      arbitrary: true,
+    }),
+  ),
+)
+
+const createUser = parse(`
+  mutation CreateUser {
+    user {
+      id
+    }
+  }
+`)
+graphql.mutation(createUser, (req, res, ctx) =>
+  res(
+    ctx.data({
+      arbitrary: true,
+    }),
+  ),
+)
+
+/**
+ * Supports `TypedDocumentNode` as the GraphQL operation name.
+ */
+graphql.query(GetUserDetailDocument, (req, res, ctx) => {
+  return res(
+    ctx.data({
+      user: {
+        id: req.variables.userId,
+        firstName: 'John',
+        age: 24,
+      },
+    }),
+  )
+})
+
+graphql.mutation(LoginDocument, (req, res, ctx) => {
+  req.variables.username
+  return res(
+    ctx.data({
+      login: {
+        id: 'abc-123',
+      },
+    }),
+  )
+})
+
+graphql.query(GetUserDetailDocument, (req, res, ctx) => {
+  req.variables.userId
+  // @ts-expect-error Unknown operation variable.
+  req.variables.unknownVariable
+
+  return res(
+    ctx.data(
+      // @ts-expect-error Mocked response doesn't match the query type.
+      {},
+    ),
+  )
+})
+
+graphql.mutation(LoginDocument, (req, res, ctx) => {
+  req.variables.username
+  // @ts-expect-error Unknown operation variable.
+  req.variables.unknownVariable
+
+  return res(
+    ctx.data(
+      // @ts-expect-error Mocked response doesn't match the query type.
+      {},
+    ),
+  )
+})