msw 2.14.7 → 3.0.0

package/src/graphql/graphql.test.ts

@@ -0,0 +1,14 @@
+import { graphql } from './graphql'
+
+test('exposes the link-first GraphQL api', () => {
+  expect(graphql).toBeDefined()
+  expect(Object.keys(graphql)).toEqual(['link'])
+
+  const link = graphql.link('https://api.example.com/graphql')
+  expect(Object.keys(link)).toEqual([
+    'operation',
+    'query',
+    'mutation',
+    'subscription',
+  ])
+})

package/src/graphql/graphql.ts

@@ -0,0 +1,179 @@
+import type {
+  ResponseResolver,
+  RequestHandlerOptions,
+} from '#core/handlers/request-handler'
+import {
+  GraphQLHandler,
+  type GraphQLVariables,
+  type GraphQLOperationType,
+  type GraphQLResolverExtras,
+  type GraphQLResponseBody,
+  type GraphQLQuery,
+  type GraphQLPredicate,
+} from './graphql-handler'
+import { createRequestId } from '@mswjs/interceptors'
+import { getAllRequestCookies } from '#core/utils/request/get-request-cookies'
+import type { Path } from '#core/utils/matching/match-request-url'
+import { attachSiblingHandlers } from '#core/utils/internal/attach-sibling-handlers'
+import {
+  createGraphQLSubscriptionHandler,
+  type GraphQLSubscriptionHandlerFactory,
+} from './graphql-subscription'
+
+export type GraphQLRequestHandler = <
+  Query extends GraphQLQuery = GraphQLQuery,
+  Variables extends GraphQLVariables = GraphQLVariables,
+>(
+  predicate: GraphQLPredicate<Query, Variables>,
+  resolver: GraphQLResponseResolver<
+    [Query] extends [never] ? GraphQLQuery : Query,
+    Variables
+  >,
+  options?: RequestHandlerOptions,
+) => GraphQLHandler
+
+export type GraphQLOperationHandler = <
+  Query extends GraphQLQuery = GraphQLQuery,
+  Variables extends GraphQLVariables = GraphQLVariables,
+>(
+  resolver: GraphQLResponseResolver<
+    [Query] extends [never] ? GraphQLQuery : Query,
+    Variables
+  >,
+  options?: RequestHandlerOptions,
+) => GraphQLHandler
+
+export type GraphQLResponseResolver<
+  Query extends GraphQLQuery = GraphQLQuery,
+  Variables extends GraphQLVariables = GraphQLVariables,
+> = ResponseResolver<
+  GraphQLResolverExtras<Variables>,
+  null,
+  GraphQLResponseBody<[Query] extends [never] ? GraphQLQuery : Query>
+>
+
+function createScopedGraphQLHandler(
+  operationType: GraphQLOperationType,
+  url: Path,
+): GraphQLRequestHandler {
+  return (predicate, resolver, options = {}) => {
+    return new GraphQLHandler(operationType, predicate, url, resolver, options)
+  }
+}
+
+function createGraphQLOperationHandler(
+  url: Path,
+  subscriptionFactory?: GraphQLSubscriptionHandlerFactory,
+): GraphQLOperationHandler {
+  /**
+   * @note An explicitly generic function so the subscription sibling
+   * can be created with the same `Query`/`Variables` types as the
+   * operation resolver, without casting its resolver info.
+   */
+  return <
+    Query extends GraphQLQuery = GraphQLQuery,
+    Variables extends GraphQLVariables = GraphQLVariables,
+  >(
+    resolver: GraphQLResponseResolver<
+      [Query] extends [never] ? GraphQLQuery : Query,
+      Variables
+    >,
+    options?: RequestHandlerOptions,
+  ): GraphQLHandler => {
+    const handler = new GraphQLHandler(
+      'all',
+      new RegExp('.*'),
+      url,
+      resolver,
+      options,
+    )
+
+    if (!subscriptionFactory) {
+      return handler
+    }
+
+    // Attach a catch-all subscription handler as a sibling so the
+    // operation handler also matches GraphQL subscriptions over WebSocket.
+    // The subscription transport guarantees only actual GraphQL
+    // subscriptions are dispatched to it.
+    const subscriptionCatchAllHandler = subscriptionFactory<Query, Variables>(
+      new RegExp('.*'),
+      ({ operationName, subscription, request, finalize }) => {
+        /**
+         * @note Subscriptions are resolved imperatively, so the return
+         * value of the resolver is ignored. The request describes the
+         * WebSocket connection this subscription is multiplexed over.
+         */
+        resolver({
+          operationName,
+          query: subscription.query,
+          variables: subscription.variables,
+          cookies: getAllRequestCookies(request),
+          request,
+          requestId: createRequestId(),
+          finalize,
+        })
+      },
+      // Forward the handler options so a one-time operation handler is
+      // also consumed by the first subscription it matches.
+      options,
+    )
+
+    return attachSiblingHandlers(handler, [subscriptionCatchAllHandler])
+  }
+}
+
+export interface GraphQLLink {
+  query: GraphQLRequestHandler
+  mutation: GraphQLRequestHandler
+  operation: GraphQLOperationHandler
+  /**
+   * Intercept a GraphQL subscription.
+   *
+   * @example
+   * const api = graphql.link('https://api.example.com/graphql')
+   * api.subscription('OnPostAdded', ({ subscription }) => {
+   *   subscription.publish({
+   *    data: { postAdded: { id: 'abc-123' } },
+   *   })
+   * })
+   */
+  subscription: GraphQLSubscriptionHandlerFactory
+}
+
+/**
+ * A namespace to intercept and mock GraphQL operations
+ *
+ * @example
+ * const api = graphql.link('https://api.example.com/graphql')
+ * api.query('GetUser', resolver)
+ * api.mutation('DeletePost', resolver)
+ *
+ * @see {@link https://mswjs.io/docs/api/graphql `graphql` API reference}
+ */
+export const graphql = {
+  /**
+   * Intercepts GraphQL operations scoped by the given URL.
+   *
+   * @example
+   * const github = graphql.link('https://api.github.com/graphql')
+   * github.query('GetRepo', resolver)
+   *
+   * @see {@link https://mswjs.io/docs/api/graphql#graphqllinkurl `graphql.link()` API reference}
+   */
+  link(url: Path): GraphQLLink {
+    /**
+     * @note Create the subscription handler factory once per link so
+     * the `subscription()` and `operation()` handlers share the same
+     * underlying subscription transport (deduped by reference).
+     */
+    const subscription = createGraphQLSubscriptionHandler(url)
+
+    return {
+      operation: createGraphQLOperationHandler(url, subscription),
+      query: createScopedGraphQLHandler('query', url),
+      mutation: createScopedGraphQLHandler('mutation', url),
+      subscription,
+    }
+  },
+}

package/src/graphql/index.ts

@@ -0,0 +1,34 @@
+export {
+  graphql,
+  type GraphQLRequestHandler,
+  type GraphQLOperationHandler,
+  type GraphQLResponseResolver,
+  type GraphQLLink,
+} from './graphql'
+
+export {
+  GraphQLHandler,
+  type GraphQLQuery,
+  type GraphQLVariables,
+  type GraphQLRequestBody,
+  type GraphQLResponseBody,
+  type GraphQLJsonRequestBody,
+  type GraphQLOperationType,
+  type GraphQLCustomPredicate,
+} from './graphql-handler'
+
+export type { ParsedGraphQLRequest } from './parse-graphql-request'
+
+export {
+  createGraphQLSubscriptionHandler,
+  GraphQLSubscription,
+  GraphQLSubscriptionHandler,
+  GraphQLPassthroughSubscription,
+  type GraphQLSubscriptionHandlerFactory,
+  type GraphQLSubscriptionHandlerOptions,
+  type GraphQLSubscriptionName,
+  type GraphQLSubscriptionPayload,
+  type GraphQLSubscriptionResolver,
+  type GraphQLSubscriptionResolverInfo,
+  type GraphQLPassthroughSubscriptionEventMap,
+} from './graphql-subscription'

package/src/{core/utils/internal/parseGraphQLRequest.test.ts → graphql/parse-graphql-request.test.ts}

@@ -1,10 +1,11 @@
-/**
- * @vitest-environment jsdom
- */
 import { encodeBuffer } from '@mswjs/interceptors'
-import { OperationTypeNode } from 'graphql'
-import type { ParsedGraphQLRequest } from './parseGraphQLRequest'
-import { parseGraphQLRequest } from './parseGraphQLRequest'
+import { OperationTypeNode, parse } from 'graphql'
+import {
+  parseDocumentNode,
+  parseGraphQLRequest,
+  type ParsedGraphQLQuery,
+  type ParsedGraphQLRequest,
+} from './parse-graphql-request'
 
 test('returns true given a GraphQL-compatible request', async () => {
   const getRequest = new Request(
@@ -95,3 +96,43 @@ test('does not read the original request body', async () => {
   // is an internal operation that must not lock the body stream.
   expect(request.bodyUsed).toBe(false)
 })
+
+describe('parseDocumentNode', () => {
+  const document = parse(`
+    query GetComments {
+      comments {
+        text
+      }
+    }
+
+    subscription OnCommentAdded {
+      commentAdded {
+        text
+      }
+    }
+  `)
+
+  test('returns the first operation given no operation name', () => {
+    expect(parseDocumentNode(document)).toEqual<ParsedGraphQLQuery>({
+      operationType: OperationTypeNode.QUERY,
+      operationName: 'GetComments',
+    })
+  })
+
+  test('returns the operation matching the given operation name', () => {
+    expect(
+      parseDocumentNode(document, 'OnCommentAdded'),
+    ).toEqual<ParsedGraphQLQuery>({
+      operationType: OperationTypeNode.SUBSCRIPTION,
+      operationName: 'OnCommentAdded',
+    })
+  })
+
+  test('resolves no operation given an unknown operation name', () => {
+    expect(parseDocumentNode(document, 'Unknown')).toEqual<ParsedGraphQLQuery>({
+      operationType: undefined,
+      // The requested name is echoed back for diagnostics.
+      operationName: 'Unknown',
+    })
+  })
+})

package/src/{core/utils/internal/parseGraphQLRequest.ts → graphql/parse-graphql-request.ts}

@@ -1,21 +1,27 @@
-import type {
-  DocumentNode,
-  OperationDefinitionNode,
-  OperationTypeNode,
+import {
+  parse,
+  type DocumentNode,
+  type OperationDefinitionNode,
+  type OperationTypeNode,
 } from 'graphql'
-import type { GraphQLVariables } from '../../handlers/GraphQLHandler'
-import { toPublicUrl } from '../request/toPublicUrl'
-import { devUtils } from './devUtils'
-import { jsonParse } from './jsonParse'
-import { parseMultipartData } from './parseMultipartData'
+import type { GraphQLVariables } from './graphql-handler'
+import { toPublicUrl } from '#core/utils/request/to-public-url'
+import { devUtils } from '#core/utils/internal/dev-utils'
+import { jsonParse } from '#core/utils/internal/json-parse'
+import { parseMultipartData } from '#core/utils/internal/parse-multipart-data'
 
 interface GraphQLInput {
   query: string | null
   variables?: GraphQLVariables
+  operationName?: string | null
 }
 
 export interface ParsedGraphQLQuery {
-  operationType: OperationTypeNode
+  /**
+   * Undefined if the document has no operation matching the
+   * requested operation name.
+   */
+  operationType?: OperationTypeNode
   operationName?: string
 }
 
@@ -28,36 +34,51 @@ export type ParsedGraphQLRequest<
     })
   | undefined
 
-export function parseDocumentNode(node: DocumentNode): ParsedGraphQLQuery {
-  const operationDef = node.definitions.find((definition) => {
+export function parseDocumentNode(
+  node: DocumentNode,
+  operationName?: string | null,
+): ParsedGraphQLQuery {
+  const operationDefs = node.definitions.filter((definition) => {
     return definition.kind === 'OperationDefinition'
-  }) as OperationDefinitionNode
+  }) as Array<OperationDefinitionNode>
+
+  /**
+   * @note A document may bundle multiple operations (e.g. the ones
+   * emitted by GraphQL Code Generator). Honor the requested operation
+   * name, and resolve nothing if the document has no such operation.
+   * Falling back to the first operation would silently resolve one the
+   * client never asked for.
+   */
+  const operationDef = operationName
+    ? operationDefs.find((definition) => {
+        return definition.name?.value === operationName
+      })
+    : operationDefs[0]
 
   return {
     operationType: operationDef?.operation,
-    operationName: operationDef?.name?.value,
+    /**
+     * @note Echo the requested operation name even when the document
+     * has no such operation. It makes the "unhandled operation" warnings
+     * name the operation the client actually asked for.
+     */
+    operationName: operationDef?.name?.value || operationName || undefined,
   }
 }
 
-async function parseQuery(query: string): Promise<ParsedGraphQLQuery | Error> {
-  /**
-   * @note Use `require` to get the "graphql" module here.
-   * It has to be scoped to this function because this module leaks to the
-   * root export. It has to be `require` because tools like Jest have trouble
-   * handling dynamic imports. It gets replaced with a dynamic import on build time.
-   */
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const { parse } = require('graphql')
-
+async function parseQuery(
+  query: string,
+  operationName?: string | null,
+): Promise<ParsedGraphQLQuery | Error> {
   try {
     const ast = parse(query)
-    return parseDocumentNode(ast)
+    return parseDocumentNode(ast, operationName)
   } catch (error) {
     return error as Error
   }
 }
 
-export type GraphQLParsedOperationsMap = Record<string, string[]>
+type GraphQLParsedOperationsMap = Record<string, string[]>
 export type GraphQLMultipartRequestBody = {
   operations: string
   map?: string
@@ -107,6 +128,7 @@ async function getGraphQLInput(request: Request): Promise<GraphQLInput | null> {
       return {
         query,
         variables: jsonParse(variables),
+        operationName: url.searchParams.get('operationName'),
       }
     }
 
@@ -130,9 +152,11 @@ async function getGraphQLInput(request: Request): Promise<GraphQLInput | null> {
 
         const { operations, map, ...files } = responseJson
         const parsedOperations =
-          jsonParse<{ query?: string; variables?: GraphQLVariables }>(
-            operations,
-          ) || {}
+          jsonParse<{
+            query?: string
+            variables?: GraphQLVariables
+            operationName?: string | null
+          }>(operations) || {}
 
         if (!parsedOperations.query) {
           return null
@@ -150,6 +174,7 @@ async function getGraphQLInput(request: Request): Promise<GraphQLInput | null> {
         return {
           query: parsedOperations.query,
           variables,
+          operationName: parsedOperations.operationName,
         }
       }
 
@@ -157,15 +182,17 @@ async function getGraphQLInput(request: Request): Promise<GraphQLInput | null> {
       const requestJson: {
         query: string
         variables?: GraphQLVariables
+        operationName?: string | null
         operations?: any /** @todo Annotate this */
       } = await requestClone.json().catch(() => null)
 
       if (requestJson?.query) {
-        const { query, variables } = requestJson
+        const { query, variables, operationName } = requestJson
 
         return {
           query,
           variables,
+          operationName,
         }
       }
       return null
@@ -189,8 +216,8 @@ export async function parseGraphQLRequest(
     return
   }
 
-  const { query, variables } = input
-  const parsedResult = await parseQuery(query)
+  const { query, variables, operationName } = input
+  const parsedResult = await parseQuery(query, operationName)
 
   if (parsedResult instanceof Error) {
     const requestPublicUrl = toPublicUrl(request.url)

package/src/{core/handlers/HttpHandler.test.ts → http/http-handler.test.ts}

@@ -1,9 +1,9 @@
 // @vitest-environment jsdom
 import { createRequestId } from '@mswjs/interceptors'
-import type { HttpRequestResolverExtras } from './HttpHandler'
-import { HttpHandler } from './HttpHandler'
-import { HttpResponse } from '..'
-import type { ResponseResolver } from './RequestHandler'
+import type { HttpRequestResolverExtras } from './http-handler'
+import { HttpHandler } from './http-handler'
+import { HttpResponse } from './index'
+import type { ResponseResolver } from '#core/handlers/request-handler'
 
 const resolver: ResponseResolver<
   HttpRequestResolverExtras<{ userId: string }>
@@ -12,7 +12,7 @@ const resolver: ResponseResolver<
 }
 
 describe('info', () => {
-  it('exposes request handler information', () => {
+  test('exposes request handler information', () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
 
     expect(handler.info.header).toEqual('GET /user/:userId')
@@ -23,7 +23,7 @@ describe('info', () => {
 })
 
 describe('parse', () => {
-  it('parses a URL given a matching request', async () => {
+  test('parses a URL given a matching request', async () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
     const request = new Request(new URL('/user/abc-123', location.href))
 
@@ -38,7 +38,7 @@ describe('parse', () => {
     })
   })
 
-  it('parses a URL and ignores the request method', async () => {
+  test('parses a URL and ignores the request method', async () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
     const request = new Request(new URL('/user/def-456', location.href), {
       method: 'POST',
@@ -55,7 +55,7 @@ describe('parse', () => {
     })
   })
 
-  it('returns negative match result given a non-matching request', async () => {
+  test('returns negative match result given a non-matching request', async () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
     const request = new Request(new URL('/login', location.href))
 
@@ -70,7 +70,7 @@ describe('parse', () => {
 })
 
 describe('predicate', () => {
-  it('returns true given a matching request', async () => {
+  test('returns true given a matching request', async () => {
     const handler = new HttpHandler('POST', '/login', resolver)
     const request = new Request(new URL('/login', location.href), {
       method: 'POST',
@@ -84,7 +84,7 @@ describe('predicate', () => {
     ).resolves.toBe(true)
   })
 
-  it('supports RegExp as the request method', async () => {
+  test('supports RegExp as the request method', async () => {
     const handler = new HttpHandler(/.+/, '/login', resolver)
     const requests = [
       new Request(new URL('/login', location.href)),
@@ -102,7 +102,7 @@ describe('predicate', () => {
     }
   })
 
-  it('returns false given a non-matching request', async () => {
+  test('returns false given a non-matching request', async () => {
     const handler = new HttpHandler('POST', '/login', resolver)
     const request = new Request(new URL('/user/abc-123', location.href))
 
@@ -114,7 +114,7 @@ describe('predicate', () => {
     ).resolves.toBe(false)
   })
 
-  it('supports custom predicate function', async () => {
+  test('supports custom predicate function', async () => {
     const handler = new HttpHandler(
       'GET',
       ({ request }) => {
@@ -146,7 +146,7 @@ describe('predicate', () => {
 })
 
 describe('test', () => {
-  it('returns true given a matching request', async () => {
+  test('returns true given a matching request', async () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
     const firstTest = await handler.test({
       request: new Request(new URL('/user/abc-123', location.href)),
@@ -159,7 +159,7 @@ describe('test', () => {
     expect(secondTest).toBe(true)
   })
 
-  it('returns false given a non-matching request', async () => {
+  test('returns false given a non-matching request', async () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
     const firstTest = await handler.test({
       request: new Request(new URL('/login', location.href)),
@@ -178,7 +178,7 @@ describe('test', () => {
 })
 
 describe('run', () => {
-  it('returns a mocked response given a matching request', async () => {
+  test('returns a mocked response given a matching request', async () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
     const request = new Request(new URL('/user/abc-123', location.href))
     const requestId = createRequestId()
@@ -203,7 +203,7 @@ describe('run', () => {
     })
   })
 
-  it('returns null given a non-matching request', async () => {
+  test('returns null given a non-matching request', async () => {
     const handler = new HttpHandler('POST', '/login', resolver)
     const result = await handler.run({
       request: new Request(new URL('/users', location.href)),
@@ -213,7 +213,7 @@ describe('run', () => {
     expect(result).toBeNull()
   })
 
-  it('returns an empty "params" object given request with no URL parameters', async () => {
+  test('returns an empty "params" object given request with no URL parameters', async () => {
     const handler = new HttpHandler('GET', '/users', resolver)
     const result = await handler.run({
       request: new Request(new URL('/users', location.href)),
@@ -223,7 +223,7 @@ describe('run', () => {
     expect(result?.parsedResult?.match?.params).toEqual({})
   })
 
-  it('exhausts resolver until its generator completes', async () => {
+  test('exhausts resolver until its generator completes', async () => {
     const handler = new HttpHandler('GET', '/users', function* () {
       let count = 0
 
@@ -252,3 +252,92 @@ describe('run', () => {
     await expect(run()).resolves.toBe('complete')
   })
 })
+
+describe('finalize', () => {
+  test('returns the exact response instance if the resolver never accesses finalize', async () => {
+    const response = new HttpResponse(
+      new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode('hello'))
+          controller.close()
+        },
+      }),
+    )
+    const handler = new HttpHandler('GET', '/resource', () => {
+      return response
+    })
+
+    const result = await handler.run({
+      request: new Request(new URL('/resource', location.href)),
+      requestId: createRequestId(),
+    })
+
+    expect(result?.response).toBe(response)
+  })
+
+  test('returns the exact response instance if finalize is accessed but never called', async () => {
+    const response = new HttpResponse(
+      new ReadableStream({
+        start(controller) {
+          controller.close()
+        },
+      }),
+    )
+    const handler = new HttpHandler('GET', '/resource', ({ finalize }) => {
+      expect(finalize).toBeInstanceOf(Function)
+      return response
+    })
+
+    const result = await handler.run({
+      request: new Request(new URL('/resource', location.href)),
+      requestId: createRequestId(),
+    })
+
+    expect(result?.response).toBe(response)
+  })
+
+  test('defers the cleanup until the response stream settles', async () => {
+    const cleanup = vi.fn()
+    const response = new HttpResponse(
+      new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode('hello'))
+          controller.close()
+        },
+      }),
+    )
+    const handler = new HttpHandler('GET', '/resource', ({ finalize }) => {
+      finalize(cleanup)
+      return response
+    })
+
+    const result = await handler.run({
+      request: new Request(new URL('/resource', location.href)),
+      requestId: createRequestId(),
+    })
+
+    // The observed response is a copy of the original response.
+    expect(result?.response).not.toBe(response)
+    expect(cleanup).not.toHaveBeenCalled()
+
+    await expect(result?.response?.text()).resolves.toBe('hello')
+    await vi.waitFor(() => {
+      expect(cleanup).toHaveBeenCalledOnce()
+    })
+  })
+
+  test('runs the cleanup immediately for responses without a body', async () => {
+    const cleanup = vi.fn()
+    const handler = new HttpHandler('GET', '/resource', ({ finalize }) => {
+      finalize(cleanup)
+      return new HttpResponse(null)
+    })
+
+    await handler.run({
+      request: new Request(new URL('/resource', location.href)),
+      requestId: createRequestId(),
+    })
+
+    expect(cleanup).toHaveBeenCalledOnce()
+  })
+})