feat: allow forwarding of requests with ctx.forward

src/context/forward.test.ts

@@ -0,0 +1,10 @@
+/**
+ * @jest-environment jsdom
+ */
+import { forward } from './forward'
+import { response } from '../response'
+
+test('marks a request for forwarding', async () => {
+  const resolvedResponse = await response(forward())
+  expect(resolvedResponse).toHaveProperty('forward', true)
+})

src/context/forward.ts

@@ -0,0 +1,13 @@
+import { ResponseTransformer } from '../response'
+
+/**
+ * Explicitly perform the request as-is
+ * @example
+ * @see {@link https://mswjs.io/docs/api/context/forward `ctx.forward()`}
+ */
+export const forward = (): ResponseTransformer => {
+  return (res) => {
+    res.forward = true
+    return res
+  }
+}

src/context/index.ts

@@ -6,6 +6,7 @@ export { data } from './data'
 export { delay } from './delay'
 export { errors } from './errors'
 export { fetch } from './fetch'
+export { forward } from './forward'
 export { json } from './json'
 export { text } from './text'
 export { xml } from './xml'

src/handlers/RestHandler.ts

@@ -8,6 +8,7 @@ import {
   status,
   text,
   xml,
+  forward,
 } from '../context'
 import { SerializedResponse } from '../setupWorker/glossary'
 import { ResponseResolutionContext } from '../utils/getResponse'
@@ -61,6 +62,7 @@ export type RestContext = {
   xml: typeof xml
   delay: typeof delay
   fetch: typeof fetch
+  forward: typeof forward
 }
 
 export const restContext: RestContext = {
@@ -73,6 +75,7 @@ export const restContext: RestContext = {
   xml,
   delay,
   fetch,
+  forward,
 }
 
 export type RequestParams = {

src/response.ts

@@ -12,6 +12,7 @@ export interface MockedResponse<BodyType = any> {
   headers: Headers
   once: boolean
   delay?: number
+  forward?: boolean
 }
 
 export type ResponseTransformer<

src/utils/handleRequest.test.ts

@@ -136,6 +136,37 @@ test('returns undefined and warns on a request handler that returns no response'
   expect(warning).toMatch(/\d+:\d+/)
 })
 
+test('returns undefined for a request using ctx.forward', async () => {
+  const request = createMockedRequest({
+    url: new URL('http://localhost/user'),
+  })
+  const handlers: RequestHandler[] = [
+    rest.get('/user', () => {
+      return response(context.forward())
+    }),
+  ]
+
+  const result = await handleRequest(
+    request,
+    handlers,
+    options,
+    emitter,
+    callbacks,
+  )
+
+  expect(result).toBeUndefined()
+  expect(getEmittedEvents()).toEqual([
+    ['request:start', request],
+    ['request:end', request],
+  ])
+  expect(options.onUnhandledRequest).not.toHaveBeenCalled()
+  expect(callbacks.onBypassResponse).toHaveBeenNthCalledWith(1, request)
+  expect(callbacks.onMockedResponse).not.toHaveBeenCalled()
+  expect(callbacks.onMockedResponseSent).not.toHaveBeenCalled()
+
+  expect(console.warn).not.toHaveBeenCalled()
+})
+
 test('returns the mocked response for a request with a matching request handler', async () => {
   const request = createMockedRequest({
     url: new URL('http://localhost/user'),

src/utils/handleRequest.ts

@@ -82,6 +82,12 @@ export async function handleRequest<
     return
   }
 
+  if (response?.forward) {
+    emitter.emit('request:end', request)
+    handleRequestOptions?.onBypassResponse?.(request)
+    return
+  }
+
   // When the handled request returned no mocked response, warn the developer,
   // as it may be an oversight on their part. Perform the request as-is.
   if (!response) {