msw 2.0.12 → 2.0.13

package/src/core/handlers/RequestHandler.ts

@@ -0,0 +1,338 @@
+import { invariant } from 'outvariant'
+import { getCallFrame } from '../utils/internal/getCallFrame'
+import { isIterable } from '../utils/internal/isIterable'
+import type { ResponseResolutionContext } from '../utils/getResponse'
+import type { MaybePromise } from '../typeUtils'
+import { StrictRequest, StrictResponse } from '..//HttpResponse'
+
+export type DefaultRequestMultipartBody = Record<
+  string,
+  string | File | Array<string | File>
+>
+
+export type DefaultBodyType =
+  | Record<string, any>
+  | DefaultRequestMultipartBody
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+
+export type JsonBodyType =
+  | Record<string, any>
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+
+export interface RequestHandlerDefaultInfo {
+  header: string
+}
+
+export interface RequestHandlerInternalInfo {
+  callFrame?: string
+}
+
+export type ResponseResolverReturnType<
+  BodyType extends DefaultBodyType = undefined,
+> =
+  | ([BodyType] extends [undefined] ? Response : StrictResponse<BodyType>)
+  | undefined
+  | void
+
+export type MaybeAsyncResponseResolverReturnType<
+  BodyType extends DefaultBodyType,
+> = MaybePromise<ResponseResolverReturnType<BodyType>>
+
+export type AsyncResponseResolverReturnType<BodyType extends DefaultBodyType> =
+  | MaybeAsyncResponseResolverReturnType<BodyType>
+  | Generator<
+      MaybeAsyncResponseResolverReturnType<BodyType>,
+      MaybeAsyncResponseResolverReturnType<BodyType>,
+      MaybeAsyncResponseResolverReturnType<BodyType>
+    >
+
+export type ResponseResolverInfo<
+  ResolverExtraInfo extends Record<string, unknown>,
+  RequestBodyType extends DefaultBodyType = DefaultBodyType,
+> = {
+  request: StrictRequest<RequestBodyType>
+} & ResolverExtraInfo
+
+export type ResponseResolver<
+  ResolverExtraInfo extends Record<string, unknown> = Record<string, unknown>,
+  RequestBodyType extends DefaultBodyType = DefaultBodyType,
+  ResponseBodyType extends DefaultBodyType = undefined,
+> = (
+  info: ResponseResolverInfo<ResolverExtraInfo, RequestBodyType>,
+) => AsyncResponseResolverReturnType<ResponseBodyType>
+
+export interface RequestHandlerArgs<
+  HandlerInfo,
+  HandlerOptions extends RequestHandlerOptions,
+> {
+  info: HandlerInfo
+  resolver: ResponseResolver<any>
+  options?: HandlerOptions
+}
+
+export interface RequestHandlerOptions {
+  once?: boolean
+}
+
+export interface RequestHandlerExecutionResult<
+  ParsedResult extends Record<string, unknown> | undefined,
+> {
+  handler: RequestHandler
+  parsedResult?: ParsedResult
+  request: Request
+  response?: Response
+}
+
+export abstract class RequestHandler<
+  HandlerInfo extends RequestHandlerDefaultInfo = RequestHandlerDefaultInfo,
+  ParsedResult extends Record<string, any> | undefined = any,
+  ResolverExtras extends Record<string, unknown> = any,
+  HandlerOptions extends RequestHandlerOptions = RequestHandlerOptions,
+> {
+  static cache = new WeakMap<
+    StrictRequest<DefaultBodyType>,
+    StrictRequest<DefaultBodyType>
+  >()
+
+  public info: HandlerInfo & RequestHandlerInternalInfo
+  /**
+   * Indicates whether this request handler has been used
+   * (its resolver has successfully executed).
+   */
+  public isUsed: boolean
+
+  protected resolver: ResponseResolver<ResolverExtras, any, any>
+  private resolverGenerator?: Generator<
+    MaybeAsyncResponseResolverReturnType<any>,
+    MaybeAsyncResponseResolverReturnType<any>,
+    MaybeAsyncResponseResolverReturnType<any>
+  >
+  private resolverGeneratorResult?: Response | StrictResponse<any>
+  private options?: HandlerOptions
+
+  constructor(args: RequestHandlerArgs<HandlerInfo, HandlerOptions>) {
+    this.resolver = args.resolver
+    this.options = args.options
+
+    const callFrame = getCallFrame(new Error())
+
+    this.info = {
+      ...args.info,
+      callFrame,
+    }
+
+    this.isUsed = false
+  }
+
+  /**
+   * Determine if the intercepted request should be mocked.
+   */
+  abstract predicate(args: {
+    request: Request
+    parsedResult: ParsedResult
+    resolutionContext?: ResponseResolutionContext
+  }): boolean
+
+  /**
+   * Print out the successfully handled request.
+   */
+  abstract log(args: {
+    request: Request
+    response: Response
+    parsedResult: ParsedResult
+  }): void
+
+  /**
+   * Parse the intercepted request to extract additional information from it.
+   * Parsed result is then exposed to other methods of this request handler.
+   */
+  async parse(_args: {
+    request: Request
+    resolutionContext?: ResponseResolutionContext
+  }): Promise<ParsedResult> {
+    return {} as ParsedResult
+  }
+
+  /**
+   * Test if this handler matches the given request.
+   *
+   * This method is not used internally but is exposed
+   * as a convenience method for consumers writing custom
+   * handlers.
+   */
+  public async test(args: {
+    request: Request
+    resolutionContext?: ResponseResolutionContext
+  }): Promise<boolean> {
+    const parsedResult = await this.parse({
+      request: args.request,
+      resolutionContext: args.resolutionContext,
+    })
+
+    return this.predicate({
+      request: args.request,
+      parsedResult,
+      resolutionContext: args.resolutionContext,
+    })
+  }
+
+  protected extendResolverArgs(_args: {
+    request: Request
+    parsedResult: ParsedResult
+  }): ResolverExtras {
+    return {} as ResolverExtras
+  }
+
+  // Clone the request instance before it's passed to the handler phases
+  // and the response resolver so we can always read it for logging.
+  // We only clone it once per request to avoid unnecessary overhead.
+  private cloneRequestOrGetFromCache(
+    request: StrictRequest<DefaultBodyType>,
+  ): StrictRequest<DefaultBodyType> {
+    const existingClone = RequestHandler.cache.get(request)
+
+    if (typeof existingClone !== 'undefined') {
+      return existingClone
+    }
+
+    const clonedRequest = request.clone()
+    RequestHandler.cache.set(request, clonedRequest)
+
+    return clonedRequest
+  }
+
+  /**
+   * Execute this request handler and produce a mocked response
+   * using the given resolver function.
+   */
+  public async run(args: {
+    request: StrictRequest<any>
+    resolutionContext?: ResponseResolutionContext
+  }): Promise<RequestHandlerExecutionResult<ParsedResult> | null> {
+    if (this.isUsed && this.options?.once) {
+      return null
+    }
+
+    // Clone the request.
+    // If this is the first time MSW handles this request, a fresh clone
+    // will be created and cached. Upon further handling of the same request,
+    // the request clone from the cache will be reused to prevent abundant
+    // "abort" listeners and save up resources on cloning.
+    const requestClone = this.cloneRequestOrGetFromCache(args.request)
+
+    const parsedResult = await this.parse({
+      request: args.request,
+      resolutionContext: args.resolutionContext,
+    })
+    const shouldInterceptRequest = this.predicate({
+      request: args.request,
+      parsedResult,
+      resolutionContext: args.resolutionContext,
+    })
+
+    if (!shouldInterceptRequest) {
+      return null
+    }
+
+    // Re-check isUsed, in case another request hit this handler while we were
+    // asynchronously parsing the request.
+    if (this.isUsed && this.options?.once) {
+      return null
+    }
+
+    this.isUsed = true
+
+    // Create a response extraction wrapper around the resolver
+    // since it can be both an async function and a generator.
+    const executeResolver = this.wrapResolver(this.resolver)
+
+    const resolverExtras = this.extendResolverArgs({
+      request: args.request,
+      parsedResult,
+    })
+    const mockedResponse = (await executeResolver({
+      ...resolverExtras,
+      request: args.request,
+    })) as Response
+
+    const executionResult = this.createExecutionResult({
+      // Pass the cloned request to the result so that logging
+      // and other consumers could read its body once more.
+      request: requestClone,
+      response: mockedResponse,
+      parsedResult,
+    })
+
+    return executionResult
+  }
+
+  private wrapResolver(
+    resolver: ResponseResolver<ResolverExtras>,
+  ): ResponseResolver<ResolverExtras> {
+    return async (info): Promise<ResponseResolverReturnType<any>> => {
+      const result = this.resolverGenerator || (await resolver(info))
+
+      if (isIterable<AsyncResponseResolverReturnType<any>>(result)) {
+        // Immediately mark this handler as unused.
+        // Only when the generator is done, the handler will be
+        // considered used.
+        this.isUsed = false
+
+        const { value, done } = result[Symbol.iterator]().next()
+        const nextResponse = await value
+
+        if (done) {
+          this.isUsed = true
+        }
+
+        // If the generator is done and there is no next value,
+        // return the previous generator's value.
+        if (!nextResponse && done) {
+          invariant(
+            this.resolverGeneratorResult,
+            'Failed to returned a previously stored generator response: the value is not a valid Response.',
+          )
+
+          // Clone the previously stored response from the generator
+          // so that it could be read again.
+          return this.resolverGeneratorResult.clone() as StrictResponse<any>
+        }
+
+        if (!this.resolverGenerator) {
+          this.resolverGenerator = result
+        }
+
+        if (nextResponse) {
+          // Also clone the response before storing it
+          // so it could be read again.
+          this.resolverGeneratorResult = nextResponse?.clone()
+        }
+
+        return nextResponse
+      }
+
+      return result
+    }
+  }
+
+  private createExecutionResult(args: {
+    request: Request
+    parsedResult: ParsedResult
+    response?: Response
+  }): RequestHandlerExecutionResult<ParsedResult> {
+    return {
+      handler: this,
+      request: args.request,
+      response: args.response,
+      parsedResult: args.parsedResult,
+    }
+  }
+}

package/src/core/http.test.ts

@@ -0,0 +1,15 @@
+import { http } from './http'
+
+test('exports all REST API methods', () => {
+  expect(http).toBeDefined()
+  expect(Object.keys(http)).toEqual([
+    'all',
+    'head',
+    'get',
+    'post',
+    'put',
+    'delete',
+    'patch',
+    'options',
+  ])
+})

package/src/core/http.ts

@@ -0,0 +1,51 @@
+import {
+  DefaultBodyType,
+  RequestHandlerOptions,
+  ResponseResolver,
+} from './handlers/RequestHandler'
+import {
+  HttpMethods,
+  HttpHandler,
+  HttpRequestResolverExtras,
+} from './handlers/HttpHandler'
+import type { Path, PathParams } from './utils/matching/matchRequestUrl'
+
+function createHttpHandler<Method extends HttpMethods | RegExp>(
+  method: Method,
+) {
+  return <
+    Params extends PathParams<keyof Params> = PathParams,
+    RequestBodyType extends DefaultBodyType = DefaultBodyType,
+    ResponseBodyType extends DefaultBodyType = undefined,
+  >(
+    path: Path,
+    resolver: ResponseResolver<
+      HttpRequestResolverExtras<Params>,
+      RequestBodyType,
+      ResponseBodyType
+    >,
+    options: RequestHandlerOptions = {},
+  ) => {
+    return new HttpHandler(method, path, resolver, options)
+  }
+}
+
+/**
+ * A namespace to intercept and mock HTTP requests.
+ *
+ * @example
+ * http.get('/user', resolver)
+ * http.post('/post/:id', resolver)
+ *
+ * @see {@link https://mswjs.io/docs/api/http `http` API reference}
+ */
+export const http = {
+  all: createHttpHandler(/.+/),
+  head: createHttpHandler(HttpMethods.HEAD),
+  get: createHttpHandler(HttpMethods.GET),
+  post: createHttpHandler(HttpMethods.POST),
+  put: createHttpHandler(HttpMethods.PUT),
+  delete: createHttpHandler(HttpMethods.DELETE),
+  patch: createHttpHandler(HttpMethods.PATCH),
+  options: createHttpHandler(HttpMethods.OPTIONS),
+}

package/src/core/index.ts

@@ -0,0 +1,56 @@
+import { checkGlobals } from './utils/internal/checkGlobals'
+
+export { SetupApi } from './SetupApi'
+
+/* Request handlers */
+export { RequestHandler } from './handlers/RequestHandler'
+export { http } from './http'
+export { HttpHandler, HttpMethods } from './handlers/HttpHandler'
+export { graphql } from './graphql'
+export { GraphQLHandler } from './handlers/GraphQLHandler'
+
+/* Utils */
+export { matchRequestUrl } from './utils/matching/matchRequestUrl'
+export * from './utils/handleRequest'
+export { cleanUrl } from './utils/url/cleanUrl'
+
+/**
+ * Type definitions.
+ */
+
+export type { SharedOptions, LifeCycleEventsMap } from './sharedOptions'
+
+export type {
+  ResponseResolver,
+  ResponseResolverReturnType,
+  AsyncResponseResolverReturnType,
+  RequestHandlerOptions,
+  DefaultBodyType,
+  DefaultRequestMultipartBody,
+  JsonBodyType,
+} from './handlers/RequestHandler'
+
+export type {
+  RequestQuery,
+  HttpRequestParsedResult,
+} from './handlers/HttpHandler'
+
+export type {
+  GraphQLVariables,
+  GraphQLRequestBody,
+  GraphQLJsonRequestBody,
+} from './handlers/GraphQLHandler'
+
+export type { Path, PathParams, Match } from './utils/matching/matchRequestUrl'
+export type { ParsedGraphQLRequest } from './utils/internal/parseGraphQLRequest'
+
+export * from './HttpResponse'
+export * from './delay'
+export { bypass } from './bypass'
+export { passthrough } from './passthrough'
+
+// Validate environmental globals before executing any code.
+// This ensures that the library gives user-friendly errors
+// when ran in the environments that require additional polyfills
+// from the end user.
+checkGlobals()

package/src/core/passthrough.test.ts

@@ -0,0 +1,13 @@
+/**
+ * @vitest-environment node
+ */
+import { passthrough } from './passthrough'
+
+it('creates a 302 response with the intention header', () => {
+  const response = passthrough()
+
+  expect(response).toBeInstanceOf(Response)
+  expect(response.status).toBe(302)
+  expect(response.statusText).toBe('Passthrough')
+  expect(response.headers.get('x-msw-intention')).toBe('passthrough')
+})

package/src/core/passthrough.ts

@@ -0,0 +1,23 @@
+/**
+ * Performs the intercepted request as-is.
+ *
+ * This stops request handler lookup so no other handlers
+ * can affect this request past this point.
+ * Unlike `bypass()`, this will not trigger an additional request.
+ *
+ * @example
+ * http.get('/resource', () => {
+ *   return passthrough()
+ * })
+ *
+ * @see {@link https://mswjs.io/docs/api/passthrough `passthrough()` API reference}
+ */
+export function passthrough(): Response {
+  return new Response(null, {
+    status: 302,
+    statusText: 'Passthrough',
+    headers: {
+      'x-msw-intention': 'passthrough',
+    },
+  })
+}

package/src/core/sharedOptions.ts

@@ -0,0 +1,66 @@
+import type { Emitter } from 'strict-event-emitter'
+import type { UnhandledRequestStrategy } from './utils/request/onUnhandledRequest'
+
+export interface SharedOptions {
+  /**
+   * Specifies how to react to a request that has no corresponding
+   * request handler. Warns on unhandled requests by default.
+   *
+   * @example worker.start({ onUnhandledRequest: 'bypass' })
+   * @example worker.start({ onUnhandledRequest: 'warn' })
+   * @example server.listen({ onUnhandledRequest: 'error' })
+   */
+  onUnhandledRequest?: UnhandledRequestStrategy
+}
+
+export type LifeCycleEventsMap = {
+  'request:start': [
+    args: {
+      request: Request
+      requestId: string
+    },
+  ]
+  'request:match': [
+    args: {
+      request: Request
+      requestId: string
+    },
+  ]
+  'request:unhandled': [
+    args: {
+      request: Request
+      requestId: string
+    },
+  ]
+  'request:end': [
+    args: {
+      request: Request
+      requestId: string
+    },
+  ]
+  'response:mocked': [
+    args: {
+      response: Response
+      request: Request
+      requestId: string
+    },
+  ]
+  'response:bypass': [
+    args: {
+      response: Response
+      request: Request
+      requestId: string
+    },
+  ]
+  unhandledException: [
+    args: {
+      error: Error
+      request: Request
+      requestId: string
+    },
+  ]
+}
+
+export type LifeCycleEventEmitter<
+  EventsMap extends Record<string | symbol, any>,
+> = Pick<Emitter<EventsMap>, 'on' | 'removeListener' | 'removeAllListeners'>

package/src/core/typeUtils.ts

@@ -0,0 +1,20 @@
+type Fn = (...arg: any[]) => any
+
+export type MaybePromise<T> = T | Promise<T>
+
+export type RequiredDeep<
+  Type,
+  U extends Record<string, unknown> | Fn | undefined = undefined,
+> = Type extends Fn
+  ? Type
+  : /**
+   * @note The "Fn" type satisfies the predicate below.
+   * It must always come first, before the Record check.
+   */
+  Type extends Record<string, any>
+  ? {
+      [Key in keyof Type]-?: NonNullable<Type[Key]> extends NonNullable<U>
+        ? NonNullable<Type[Key]>
+        : RequiredDeep<NonNullable<Type[Key]>, U>
+    }
+  : Type

package/src/core/utils/HttpResponse/decorators.ts

@@ -0,0 +1,56 @@
+import statuses from '@bundled-es-modules/statuses'
+import type { HttpResponseInit } from '../../HttpResponse'
+
+const { message } = statuses
+
+export interface HttpResponseDecoratedInit extends HttpResponseInit {
+  status: number
+  statusText: string
+  headers: Headers
+}
+
+export function normalizeResponseInit(
+  init: HttpResponseInit = {},
+): HttpResponseDecoratedInit {
+  const status = init?.status || 200
+  const statusText = init?.statusText || message[status] || ''
+  const headers = new Headers(init?.headers)
+
+  return {
+    ...init,
+    headers,
+    status,
+    statusText,
+  }
+}
+
+export function decorateResponse(
+  response: Response,
+  init: HttpResponseDecoratedInit,
+): Response {
+  // Allow to mock the response type.
+  if (init.type) {
+    Object.defineProperty(response, 'type', {
+      value: init.type,
+      enumerable: true,
+      writable: false,
+    })
+  }
+
+  // Cookie forwarding is only relevant in the browser.
+  if (typeof document !== 'undefined') {
+    // Write the mocked response cookies to the document.
+    // Note that Fetch API Headers will concatenate multiple "Set-Cookie"
+    // headers into a single comma-separated string, just as it does
+    // with any other multi-value headers.
+    const responseCookies = init.headers.get('Set-Cookie')?.split(',') || []
+
+    for (const cookieString of responseCookies) {
+      // No need to parse the cookie headers because it's defined
+      // as the valid cookie string to begin with.
+      document.cookie = cookieString
+    }
+  }
+
+  return response
+}

package/src/core/utils/getResponse.ts

@@ -0,0 +1,55 @@
+import {
+  RequestHandler,
+  RequestHandlerExecutionResult,
+} from '../handlers/RequestHandler'
+
+export interface ResponseLookupResult {
+  handler: RequestHandler
+  parsedResult?: any
+  response?: Response
+}
+
+export interface ResponseResolutionContext {
+  baseUrl?: string
+}
+
+/**
+ * Returns a mocked response for a given request using following request handlers.
+ */
+export const getResponse = async <Handler extends Array<RequestHandler>>(
+  request: Request,
+  handlers: Handler,
+  resolutionContext?: ResponseResolutionContext,
+): Promise<ResponseLookupResult | null> => {
+  let matchingHandler: RequestHandler | null = null
+  let result: RequestHandlerExecutionResult<any> | null = null
+
+  for (const handler of handlers) {
+    result = await handler.run({ request, resolutionContext })
+
+    // If the handler produces some result for this request,
+    // it automatically becomes matching.
+    if (result !== null) {
+      matchingHandler = handler
+    }
+
+    // Stop the lookup if this handler returns a mocked response.
+    // If it doesn't, it will still be considered the last matching
+    // handler until any of them returns a response. This way we can
+    // distinguish between fallthrough handlers without responses
+    // and the lack of a matching handler.
+    if (result?.response) {
+      break
+    }
+  }
+
+  if (matchingHandler) {
+    return {
+      handler: matchingHandler,
+      parsedResult: result?.parsedResult,
+      response: result?.response,
+    }
+  }
+
+  return null
+}