@depup/mswjs__interceptors 0.41.3-depup.0

package/src/RequestController.test.ts

@@ -0,0 +1,104 @@
+import { vi, it, expect } from 'vitest'
+import {
+  RequestController,
+  type RequestControllerSource,
+} from './RequestController'
+import { InterceptorError } from './InterceptorError'
+
+const defaultSource = {
+  passthrough() {},
+  respondWith() {},
+  errorWith() {},
+} satisfies RequestControllerSource
+
+it('has a pending state upon construction', () => {
+  const controller = new RequestController(
+    new Request('http://localhost'),
+    defaultSource
+  )
+
+  expect(controller.handled).toBeInstanceOf(Promise)
+  expect(controller.readyState).toBe(RequestController.PENDING)
+})
+
+it('handles a request when calling ".respondWith()" with a mocked response', async () => {
+  const respondWith = vi.fn<RequestControllerSource['respondWith']>()
+  const controller = new RequestController(new Request('http://localhost'), {
+    ...defaultSource,
+    respondWith,
+  })
+
+  await controller.respondWith(new Response('hello world'))
+
+  expect(controller.readyState).toBe(RequestController.RESPONSE)
+  await expect(controller.handled).resolves.toBeUndefined()
+
+  expect(respondWith).toHaveBeenCalledOnce()
+  const [response] = respondWith.mock.calls[0]
+
+  expect(response).toBeInstanceOf(Response)
+  expect(response.status).toBe(200)
+  await expect(response.text()).resolves.toBe('hello world')
+})
+
+it('handles the request when calling ".errorWith()" with an error', async () => {
+  const errorWith = vi.fn<RequestControllerSource['errorWith']>()
+  const controller = new RequestController(new Request('http://localhost'), {
+    ...defaultSource,
+    errorWith,
+  })
+
+  const error = new Error('Oops!')
+  await controller.errorWith(error)
+
+  expect(controller.readyState).toBe(RequestController.ERROR)
+  await expect(controller.handled).resolves.toBeUndefined()
+
+  expect(errorWith).toHaveBeenCalledOnce()
+  expect(errorWith).toHaveBeenCalledWith(error)
+})
+
+it('handles the request when calling ".errorWith()" with an arbitrary object', async () => {
+  const errorWith = vi.fn<RequestControllerSource['errorWith']>()
+  const controller = new RequestController(new Request('http://localhost'), {
+    ...defaultSource,
+    errorWith,
+  })
+
+  const error = { message: 'Oops!' }
+  await controller.errorWith(error)
+
+  expect(controller.readyState).toBe(RequestController.ERROR)
+  await expect(controller.handled).resolves.toBeUndefined()
+
+  expect(errorWith).toHaveBeenCalledOnce()
+  expect(errorWith).toHaveBeenCalledWith(error)
+})
+
+it('throws when calling "respondWith" multiple times', async () => {
+  const controller = new RequestController(
+    new Request('http://localhost'),
+    defaultSource
+  )
+  controller.respondWith(new Response('hello world'))
+
+  expect(() => controller.respondWith(new Response('second response'))).toThrow(
+    new InterceptorError(
+      'Failed to respond to the "GET http://localhost/" request with "200 OK": the request has already been handled (2)'
+    )
+  )
+})
+
+it('throws when calling "errorWith" multiple times', async () => {
+  const controller = new RequestController(
+    new Request('http://localhost'),
+    defaultSource
+  )
+  controller.errorWith(new Error('Oops!'))
+
+  expect(() => controller.errorWith(new Error('second error'))).toThrow(
+    new InterceptorError(
+      'Failed to error the "GET http://localhost/" request with "Error: second error": the request has already been handled (3)'
+    )
+  )
+})

package/src/RequestController.ts

@@ -0,0 +1,109 @@
+import { DeferredPromise } from '@open-draft/deferred-promise'
+import { invariant } from 'outvariant'
+import { InterceptorError } from './InterceptorError'
+
+export interface RequestControllerSource {
+  passthrough(): void
+  respondWith(response: Response): void
+  errorWith(reason?: unknown): void
+}
+
+export class RequestController {
+  static PENDING = 0 as const
+  static PASSTHROUGH = 1 as const
+  static RESPONSE = 2 as const
+  static ERROR = 3 as const
+
+  public readyState: number
+
+  /**
+   * A Promise that resolves when this controller handles a request.
+   * See `controller.readyState` for more information on the handling result.
+   */
+  public handled: Promise<void>
+
+  constructor(
+    protected readonly request: Request,
+    protected readonly source: RequestControllerSource
+  ) {
+    this.readyState = RequestController.PENDING
+    this.handled = new DeferredPromise<void>()
+  }
+
+  get #handled() {
+    return this.handled as DeferredPromise<void>
+  }
+
+  /**
+   * Perform this request as-is.
+   */
+  public async passthrough(): Promise<void> {
+    invariant.as(
+      InterceptorError,
+      this.readyState === RequestController.PENDING,
+      'Failed to passthrough the "%s %s" request: the request has already been handled',
+      this.request.method,
+      this.request.url
+    )
+
+    this.readyState = RequestController.PASSTHROUGH
+    await this.source.passthrough()
+    this.#handled.resolve()
+  }
+
+  /**
+   * Respond to this request with the given `Response` instance.
+   *
+   * @example
+   * controller.respondWith(new Response())
+   * controller.respondWith(Response.json({ id }))
+   * controller.respondWith(Response.error())
+   */
+  public respondWith(response: Response): void {
+    invariant.as(
+      InterceptorError,
+      this.readyState === RequestController.PENDING,
+      'Failed to respond to the "%s %s" request with "%d %s": the request has already been handled (%d)',
+      this.request.method,
+      this.request.url,
+      response.status,
+      response.statusText || 'OK',
+      this.readyState
+    )
+
+    this.readyState = RequestController.RESPONSE
+    this.#handled.resolve()
+
+    /**
+     * @note Although `source.respondWith()` is potentially asynchronous,
+     * do NOT await it for backward-compatibility. Awaiting it will short-circuit
+     * the request listener invocation as soon as a listener responds to a request.
+     * Ideally, that's what we want, but that's not what we promise the user.
+     */
+    this.source.respondWith(response)
+  }
+
+  /**
+   * Error this request with the given reason.
+   *
+   * @example
+   * controller.errorWith()
+   * controller.errorWith(new Error('Oops!'))
+   * controller.errorWith({ message: 'Oops!'})
+   */
+  public errorWith(reason?: unknown): void {
+    invariant.as(
+      InterceptorError,
+      this.readyState === RequestController.PENDING,
+      'Failed to error the "%s %s" request with "%s": the request has already been handled (%d)',
+      this.request.method,
+      this.request.url,
+      reason?.toString(),
+      this.readyState
+    )
+
+    this.readyState = RequestController.ERROR
+    this.source.errorWith(reason)
+    this.#handled.resolve()
+  }
+}

package/src/createRequestId.test.ts

@@ -0,0 +1,7 @@
+import { it, expect } from 'vitest'
+import { createRequestId } from './createRequestId'
+import { REQUEST_ID_REGEXP } from '../test/helpers'
+
+it('returns a request ID', () => {
+  expect(createRequestId()).toMatch(REQUEST_ID_REGEXP)
+})

package/src/createRequestId.ts

@@ -0,0 +1,9 @@
+/**
+ * Generate a random ID string to represent a request.
+ * @example
+ * createRequestId()
+ * // "f774b6c9c600f"
+ */
+export function createRequestId(): string {
+  return Math.random().toString(16).slice(2)
+}

package/src/getRawRequest.ts

@@ -0,0 +1,21 @@
+const kRawRequest = Symbol('kRawRequest')
+
+/**
+ * Returns a raw request instance associated with this request.
+ *
+ * @example
+ * interceptor.on('request', ({ request }) => {
+ *   const rawRequest = getRawRequest(request)
+ *
+ *   if (rawRequest instanceof http.ClientRequest) {
+ *     console.log(rawRequest.rawHeaders)
+ *   }
+ * })
+ */
+export function getRawRequest(request: Request): unknown | undefined {
+  return Reflect.get(request, kRawRequest)
+}
+
+export function setRawRequest(request: Request, rawRequest: unknown): void {
+  Reflect.set(request, kRawRequest, rawRequest)
+}

package/src/glossary.ts

@@ -0,0 +1,37 @@
+import type { RequestController } from './RequestController'
+
+export const IS_PATCHED_MODULE: unique symbol = Symbol('isPatchedModule')
+
+/**
+ * @note Export `RequestController` as a type only.
+ * It's never meant to be created in the userland.
+ */
+export type { RequestController }
+
+export type RequestCredentials = 'omit' | 'include' | 'same-origin'
+
+export type HttpRequestEventMap = {
+  request: [
+    args: {
+      request: Request
+      requestId: string
+      controller: RequestController
+    }
+  ]
+  response: [
+    args: {
+      response: Response
+      isMockedResponse: boolean
+      request: Request
+      requestId: string
+    }
+  ]
+  unhandledException: [
+    args: {
+      error: unknown
+      request: Request
+      requestId: string
+      controller: RequestController
+    }
+  ]
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from './glossary'
+export * from './Interceptor'
+export * from './BatchInterceptor'
+export {
+  RequestController,
+  type RequestControllerSource,
+} from './RequestController'
+
+/* Utils */
+export { createRequestId } from './createRequestId'
+export { getCleanUrl } from './utils/getCleanUrl'
+export { encodeBuffer, decodeBuffer } from './utils/bufferUtils'
+export { FetchResponse } from './utils/fetchUtils'
+export { getRawRequest } from './getRawRequest'
+export { resolveWebSocketUrl } from './utils/resolveWebSocketUrl'