@depup/msw 2.13.2-depup.0 → 2.15.0-depup.6

package/src/core/graphql.ts

@@ -1,16 +1,16 @@
 import type { OperationTypeNode } from 'graphql'
 import {
-  ResponseResolver,
-  RequestHandlerOptions,
+  type ResponseResolver,
+  type RequestHandlerOptions,
 } from './handlers/RequestHandler'
 import {
   GraphQLHandler,
-  GraphQLVariables,
-  GraphQLOperationType,
-  GraphQLResolverExtras,
-  GraphQLResponseBody,
-  GraphQLQuery,
-  GraphQLPredicate,
+  type GraphQLVariables,
+  type GraphQLOperationType,
+  type GraphQLResolverExtras,
+  type GraphQLResponseBody,
+  type GraphQLQuery,
+  type GraphQLPredicate,
 } from './handlers/GraphQLHandler'
 import type { Path } from './utils/matching/matchRequestUrl'
 

package/src/core/handlers/GraphQLHandler.test.ts

@@ -1,14 +1,13 @@
 // @vitest-environment jsdom
 import { createRequestId, encodeBuffer } from '@mswjs/interceptors'
 import { OperationTypeNode, parse } from 'graphql'
-import {
-  GraphQLHandler,
+import type {
   GraphQLRequestBody,
   GraphQLResolverExtras,
-  isDocumentNode,
 } from './GraphQLHandler'
+import { GraphQLHandler, isDocumentNode } from './GraphQLHandler'
 import { HttpResponse } from '../HttpResponse'
-import { ResponseResolver } from './RequestHandler'
+import type { ResponseResolver } from './RequestHandler'
 
 const resolver: ResponseResolver<GraphQLResolverExtras<{ userId: string }>> = ({
   variables,

package/src/core/handlers/GraphQLHandler.ts

@@ -6,30 +6,34 @@ import {
   type OperationTypeNode,
 } from 'graphql'
 import {
-  DefaultBodyType,
   RequestHandler,
-  RequestHandlerDefaultInfo,
-  RequestHandlerExecutionResult,
-  RequestHandlerOptions,
-  ResponseResolver,
+  type DefaultBodyType,
+  type RequestHandlerDefaultInfo,
+  type RequestHandlerExecutionResult,
+  type RequestHandlerOptions,
+  type ResponseResolver,
 } from './RequestHandler'
 import { getTimestamp } from '../utils/logging/getTimestamp'
 import { getStatusCodeColor } from '../utils/logging/getStatusCodeColor'
 import { serializeRequest } from '../utils/logging/serializeRequest'
 import { serializeResponse } from '../utils/logging/serializeResponse'
-import { Match, matchRequestUrl, Path } from '../utils/matching/matchRequestUrl'
 import {
-  ParsedGraphQLRequest,
-  GraphQLMultipartRequestBody,
+  type Match,
+  matchRequestUrl,
+  type Path,
+} from '../utils/matching/matchRequestUrl'
+import {
+  type ParsedGraphQLRequest,
+  type GraphQLMultipartRequestBody,
   parseGraphQLRequest,
   parseDocumentNode,
-  ParsedGraphQLQuery,
+  type ParsedGraphQLQuery,
 } from '../utils/internal/parseGraphQLRequest'
 import { toPublicUrl } from '../utils/request/toPublicUrl'
 import { devUtils } from '../utils/internal/devUtils'
 import { getAllRequestCookies } from '../utils/request/getRequestCookies'
-import { ResponseResolutionContext } from 'src/iife'
-import { kDefaultContentType, StrictRequest } from '../HttpResponse'
+import { type ResponseResolutionContext } from '../utils/executeHandlers'
+import { kDefaultContentType, type StrictRequest } from '../HttpResponse'
 import { getAllAcceptedMimeTypes } from '../utils/request/getAllAcceptedMimeTypes'
 
 export interface DocumentTypeDecoration<

package/src/core/handlers/HttpHandler.test.ts

@@ -1,8 +1,9 @@
 // @vitest-environment jsdom
 import { createRequestId } from '@mswjs/interceptors'
-import { HttpHandler, HttpRequestResolverExtras } from './HttpHandler'
+import type { HttpRequestResolverExtras } from './HttpHandler'
+import { HttpHandler } from './HttpHandler'
 import { HttpResponse } from '..'
-import { ResponseResolver } from './RequestHandler'
+import type { ResponseResolver } from './RequestHandler'
 
 const resolver: ResponseResolver<
   HttpRequestResolverExtras<{ userId: string }>
@@ -251,3 +252,92 @@ describe('run', () => {
     await expect(run()).resolves.toBe('complete')
   })
 })
+
+describe('finalize', () => {
+  it('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)
+  })
+
+  it('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)
+  })
+
+  it('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()
+    })
+  })
+
+  it('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()
+  })
+})

package/src/core/handlers/HttpHandler.ts

@@ -1,4 +1,4 @@
-import { ResponseResolutionContext } from '../utils/executeHandlers'
+import { type ResponseResolutionContext } from '../utils/executeHandlers'
 import { devUtils } from '../utils/internal/devUtils'
 import { isStringEqual } from '../utils/internal/isStringEqual'
 import { getStatusCodeColor } from '../utils/logging/getStatusCodeColor'
@@ -7,18 +7,18 @@ import { serializeRequest } from '../utils/logging/serializeRequest'
 import { serializeResponse } from '../utils/logging/serializeResponse'
 import {
   matchRequestUrl,
-  Match,
-  Path,
-  PathParams,
+  type Match,
+  type Path,
+  type PathParams,
 } from '../utils/matching/matchRequestUrl'
 import { toPublicUrl } from '../utils/request/toPublicUrl'
 import { getAllRequestCookies } from '../utils/request/getRequestCookies'
 import { cleanUrl } from '../utils/url/cleanUrl'
 import {
   RequestHandler,
-  RequestHandlerDefaultInfo,
-  RequestHandlerOptions,
-  ResponseResolver,
+  type RequestHandlerDefaultInfo,
+  type RequestHandlerOptions,
+  type ResponseResolver,
 } from './RequestHandler'
 
 export type HttpHandlerMethod = string | RegExp

package/src/core/handlers/RequestHandler.ts

@@ -1,17 +1,21 @@
+import { Headers as HeadersPolyfill } from 'headers-polyfill'
 import { getCallFrame } from '../utils/internal/getCallFrame'
 import {
-  AsyncIterable,
-  Iterable,
   isIterable,
+  type AsyncIterable,
+  type Iterable,
 } from '../utils/internal/isIterable'
 import type { ResponseResolutionContext } from '../utils/executeHandlers'
 import type { MaybePromise } from '../typeUtils'
+import type { HttpResponse } from '../HttpResponse'
 import {
-  StrictRequest,
-  HttpResponse,
-  DefaultUnsafeFetchResponse,
+  type StrictRequest,
+  type DefaultUnsafeFetchResponse,
 } from '../HttpResponse'
 import type { GraphQLRequestBody } from './GraphQLHandler'
+import { devUtils } from '../utils/internal/devUtils'
+import { getRawSetCookie } from '../utils/HttpResponse/decorators'
+import { observeResponseBodyStream } from '../utils/internal/observe-response-body-stream'
 
 export type DefaultRequestMultipartBody = Record<
   string,
@@ -28,12 +32,7 @@ export type DefaultBodyType =
   | undefined
 
 export type JsonBodyType =
-  | Record<string, any>
-  | string
-  | number
-  | boolean
-  | null
-  | undefined
+  Record<string, any> | string | number | boolean | null | undefined
 
 export interface RequestHandlerDefaultInfo {
   header: string
@@ -88,8 +87,26 @@ export type ResponseResolverInfo<
 > = {
   request: StrictRequest<RequestBodyType>
   requestId: string
+  /**
+   * Schedule a callback to run after this response resolver completes.
+   * Handy for cleaning up the side effects introduced in the resolver.
+   *
+   * For responses with a `ReadableStream` body (including `sse()` handlers),
+   * the callback runs once the response stream settles: it is read to
+   * completion, errored, or canceled, or the request is aborted.
+   * @example
+   * sse('/', ({ client, finalize }) => {
+   *   const interval = setInterval(() => client.send({ data: 'ping' }))
+   *   finalize(() => clearInterval(interval))
+   * })
+   */
+  finalize: ResponseResolverFinalizeFunction
 } & ResolverExtraInfo
 
+type ResponseResolverFinalizeFunction = (
+  callback: () => MaybePromise<void>,
+) => void
+
 export type ResponseResolver<
   ResolverExtraInfo extends Record<string, unknown> = Record<string, unknown>,
   RequestBodyType extends DefaultBodyType = DefaultBodyType,
@@ -147,7 +164,9 @@ export abstract class RequestHandler<
         MaybeAsyncResponseResolverReturnType<any>
       >
   private resolverIteratorResult?: Response | HttpResponse<any>
+  private resolverIteratorCleanups?: Array<() => MaybePromise<void>>
   private options?: HandlerOptions
+  private scheduledCleanups: Map<string, Array<() => MaybePromise<void>>>
 
   public info: HandlerInfo & RequestHandlerInternalInfo
 
@@ -160,6 +179,7 @@ export abstract class RequestHandler<
   constructor(args: RequestHandlerArgs<HandlerInfo, HandlerOptions>) {
     this.resolver = args.resolver
     this.options = args.options
+    this.scheduledCleanups = new Map()
 
     const callFrame = getCallFrame(new Error())
 
@@ -171,6 +191,37 @@ export abstract class RequestHandler<
     this.isUsed = false
   }
 
+  /**
+   * Reset the runtime state accumulated during response resolution,
+   * such as generator iterator progress. Called when this handler is
+   * removed from the active handlers list so re-adding it later starts
+   * from a clean state.
+   */
+  protected reset(): void {
+    this.scheduledCleanups.clear()
+
+    const iterator = this.resolverIterator
+    this.resolverIterator = undefined
+    this.resolverIteratorResult = undefined
+    this.resolverIteratorCleanups = undefined
+
+    if (typeof iterator?.return === 'function') {
+      void Promise.resolve(iterator.return())
+    }
+  }
+
+  /**
+   * Restore this handler so it can match requests again after being
+   * exhausted (e.g. via `{ once: true }`). Also clears any accumulated
+   * resolution state.
+   */
+  protected restore(): void {
+    if (this.options?.once) {
+      this.reset()
+      this.isUsed = false
+    }
+  }
+
   /**
    * Determine if the intercepted request should be mocked.
    */
@@ -302,24 +353,80 @@ export abstract class RequestHandler<
       parsedResult,
     })
 
+    const listenerController = new AbortController()
+
+    /**
+     * @note Initialize the `finalize` machinery lazily, on the first
+     * access of the `finalize` property by the resolver. If the resolver
+     * never accesses it, the handler behaves as if `finalize` never
+     * existed: no abort listeners, no scheduled cleanups, and no response
+     * body stream observation (see `this.complete()`).
+     */
+    let finalizeFunction: ResponseResolverFinalizeFunction | undefined
+
+    const getFinalize = (): ResponseResolverFinalizeFunction => {
+      if (finalizeFunction == null) {
+        // Run any scheduled cleanups if the request gets aborted
+        // while the resolver is still executing.
+        if (!args.request.signal.aborted) {
+          args.request.signal.addEventListener(
+            'abort',
+            () => this.runScheduledCleanups(args.requestId),
+            {
+              once: true,
+              signal: listenerController.signal,
+            },
+          )
+        }
+
+        finalizeFunction = (callback) => {
+          this.scheduleCleanup(args.requestId, callback)
+
+          /**
+           * @note Run the cleanup immediately if the request has already
+           * been aborted. The "abort" listener above never fires for an
+           * already-aborted signal (and fires at most once), while
+           * long-lived resolvers (streams, generators) may never settle
+           * to run the cleanups on completion.
+           */
+          if (args.request.signal.aborted) {
+            void this.runScheduledCleanups(args.requestId)
+          }
+        }
+      }
+
+      return finalizeFunction
+    }
+
     const mockedResponsePromise = (
       executeResolver({
         ...resolverExtras,
+        get finalize(): ResponseResolverFinalizeFunction {
+          return getFinalize()
+        },
         requestId: args.requestId,
         request: args.request,
       }) as Promise<Response>
-    ).catch((errorOrResponse) => {
-      // Allow throwing a Response instance in a response resolver.
-      if (errorOrResponse instanceof Response) {
-        return errorOrResponse
-      }
+    )
+      .catch((errorOrResponse) => {
+        // Allow throwing a Response instance in a response resolver.
+        if (errorOrResponse instanceof Response) {
+          return errorOrResponse
+        }
 
-      // Otherwise, throw the error as-is.
-      throw errorOrResponse
-    })
+        // Otherwise, throw the error as-is.
+        throw errorOrResponse
+      })
+      .finally(() => {
+        listenerController.abort()
+      })
 
     const mockedResponse = await mockedResponsePromise
 
+    if (mockedResponse) {
+      forwardResponseCookies(mockedResponse)
+    }
+
     const executionResult = this.createExecutionResult({
       // Pass the cloned request to the result so that logging
       // and other consumers could read its body once more.
@@ -337,10 +444,42 @@ export abstract class RequestHandler<
   ): ResponseResolver<ResolverExtras> {
     return async (info): Promise<ResponseResolverReturnType<any>> => {
       if (!this.resolverIterator) {
-        const result = await resolver(info)
+        let result
+
+        try {
+          result = await resolver(info)
+        } catch (error) {
+          // Ensure cleanup if the resolver throws, regardless of the returned type.
+          await this.runScheduledCleanups(info.requestId)
+
+          // Re-throw the error for the "run()" method to handle (e.g. thrown responses).
+          throw error
+        }
 
         if (!isIterable(result)) {
-          return result
+          // Otherwise, run the cleanups if it's a plain response resolver
+          // (deferred until the response stream settles for streamed responses).
+          return this.complete({
+            request: info.request,
+            requestId: info.requestId,
+            response: result,
+          })
+        }
+
+        /**
+         * @note Carry over any previously registered cleanups onto the iterator cleanups.
+         * This is only relevant if "finalize()" is called in a regular resolver that
+         * returns an iterator.
+         * @example
+         * http.get('/', async ({ finalize }) => {
+         *   finalize(cleanup)
+         *   return (async function*() {})()
+         * })
+         */
+        const existingCleanups = this.scheduledCleanups.get(info.requestId)
+        if (existingCleanups != null && existingCleanups.length > 0) {
+          this.resolverIteratorCleanups = existingCleanups
+          this.scheduledCleanups.delete(info.requestId)
         }
 
         this.resolverIterator =
@@ -366,7 +505,11 @@ export abstract class RequestHandler<
 
         // Clone the previously stored response so it can be read
         // when receiving it repeatedly from the "done" generator.
-        return this.resolverIteratorResult?.clone()
+        return this.complete({
+          request: info.request,
+          requestId: info.requestId,
+          response: this.resolverIteratorResult?.clone(),
+        })
       }
 
       return nextResponse
@@ -387,4 +530,168 @@ export abstract class RequestHandler<
       parsedResult: args.parsedResult,
     }
   }
+
+  private scheduleCleanup(
+    requestId: string,
+    callback: () => MaybePromise<void>,
+  ): void {
+    if (this.resolverIterator) {
+      ;(this.resolverIteratorCleanups ||= []).unshift(callback)
+      return
+    }
+
+    const cleanups = this.scheduledCleanups.get(requestId) || []
+    cleanups.unshift(callback)
+    this.scheduledCleanups.set(requestId, cleanups)
+  }
+
+  private async exhaustCleanups(
+    cleanups: Array<() => MaybePromise<void>>,
+  ): Promise<void> {
+    const errors: Array<Error> = []
+
+    for (const cleanup of cleanups) {
+      try {
+        await cleanup()
+      } catch (error) {
+        if (error instanceof Error) {
+          errors.push(error)
+        }
+      }
+    }
+
+    if (errors.length > 0) {
+      devUtils.error(
+        'Failed to execute cleanup for request handler "%s"',
+        this.info.header,
+        new AggregateError(
+          errors,
+          `Failed to execute cleanup for request handler "${this.info.header}"`,
+        ),
+      )
+    }
+  }
+
+  /**
+   * Remove and return the cleanups scheduled for the given request
+   * (or the pending iterator cleanups for generator resolvers).
+   */
+  private takeScheduledCleanups(
+    requestId: string,
+  ): Array<() => MaybePromise<void>> | undefined {
+    if (
+      this.resolverIterator &&
+      this.resolverIteratorCleanups != null &&
+      this.resolverIteratorCleanups.length > 0
+    ) {
+      const cleanups = this.resolverIteratorCleanups
+      this.resolverIteratorCleanups = undefined
+      return cleanups
+    }
+
+    const cleanups = this.scheduledCleanups.get(requestId)
+
+    if (!cleanups || cleanups.length === 0) {
+      return undefined
+    }
+
+    this.scheduledCleanups.delete(requestId)
+    return cleanups
+  }
+
+  private async runScheduledCleanups(requestId: string): Promise<void> {
+    const cleanups = this.takeScheduledCleanups(requestId)
+
+    if (cleanups) {
+      await this.exhaustCleanups(cleanups)
+    }
+  }
+
+  /**
+   * Conclude the response resolution for the given request.
+   * Runs the scheduled cleanups immediately for responses without a
+   * `ReadableStream` body. For streamed responses, returns an observed
+   * copy of the response and defers the cleanups until its body settles
+   * (is read to completion, errored, or canceled) or the request is
+   * aborted, whichever comes first.
+   */
+  private async complete(args: {
+    request: StrictRequest<any>
+    requestId: string
+    response: Response | undefined | void
+  }): Promise<Response | undefined | void> {
+    const cleanups = this.takeScheduledCleanups(args.requestId)
+
+    if (!cleanups) {
+      return args.response
+    }
+
+    const observedResponse = args.response
+      ? observeResponseBodyStream(args.response)
+      : null
+
+    if (!observedResponse) {
+      await this.exhaustCleanups(cleanups)
+      return args.response
+    }
+
+    const listenerController = new AbortController()
+
+    const runCleanupsOnce = (): void => {
+      if (listenerController.signal.aborted) {
+        return
+      }
+
+      listenerController.abort()
+      void this.exhaustCleanups(cleanups)
+    }
+
+    void observedResponse.settled.then(runCleanupsOnce)
+
+    /**
+     * @note Also run the cleanups when the request is aborted.
+     * Stream cancellation does not always propagate to the observed
+     * response (e.g. if an unconsumed clone of the response exists),
+     * while the request abort reliably means the response is unused.
+     */
+    if (args.request.signal.aborted) {
+      runCleanupsOnce()
+    } else {
+      args.request.signal.addEventListener('abort', runCleanupsOnce, {
+        once: true,
+        signal: listenerController.signal,
+      })
+    }
+
+    return observedResponse.response
+  }
+}
+
+/**
+ * Forwards the cookies from the given response to `document.cookie`.
+ */
+export function forwardResponseCookies(response: Response): void {
+  // Cookie forwarding is only relevant in the browser.
+  if (typeof document === 'undefined') {
+    return
+  }
+
+  const responseCookies = getRawSetCookie(response)
+
+  if (!responseCookies) {
+    return
+  }
+
+  // Write the mocked response cookies to the document.
+  // Use `headers-polyfill` to get the Set-Cookie header value correctly.
+  // This is an alternative until TypeScript 5.2
+  // and Node.js v20 become the minimum supported versions
+  // and "Headers.prototype.getSetCookie" can be used directly.
+  const allResponseCookies = HeadersPolyfill.prototype.getSetCookie.call(
+    new Headers([['set-cookie', responseCookies]]),
+  )
+
+  for (const cookieString of allResponseCookies) {
+    document.cookie = cookieString
+  }
 }