msw 2.0.11 → 2.0.13

package/src/core/SetupApi.ts

@@ -0,0 +1,95 @@
+import { invariant } from 'outvariant'
+import { EventMap, Emitter } from 'strict-event-emitter'
+import {
+  RequestHandler,
+  RequestHandlerDefaultInfo,
+} from './handlers/RequestHandler'
+import { LifeCycleEventEmitter } from './sharedOptions'
+import { devUtils } from './utils/internal/devUtils'
+import { pipeEvents } from './utils/internal/pipeEvents'
+import { toReadonlyArray } from './utils/internal/toReadonlyArray'
+import { Disposable } from './utils/internal/Disposable'
+
+/**
+ * Generic class for the mock API setup.
+ */
+export abstract class SetupApi<EventsMap extends EventMap> extends Disposable {
+  protected initialHandlers: ReadonlyArray<RequestHandler>
+  protected currentHandlers: Array<RequestHandler>
+  protected readonly emitter: Emitter<EventsMap>
+  protected readonly publicEmitter: Emitter<EventsMap>
+
+  public readonly events: LifeCycleEventEmitter<EventsMap>
+
+  constructor(...initialHandlers: Array<RequestHandler>) {
+    super()
+
+    invariant(
+      this.validateHandlers(initialHandlers),
+      devUtils.formatMessage(
+        `Failed to apply given request handlers: invalid input. Did you forget to spread the request handlers Array?`,
+      ),
+    )
+
+    this.initialHandlers = toReadonlyArray(initialHandlers)
+    this.currentHandlers = [...initialHandlers]
+
+    this.emitter = new Emitter<EventsMap>()
+    this.publicEmitter = new Emitter<EventsMap>()
+    pipeEvents(this.emitter, this.publicEmitter)
+
+    this.events = this.createLifeCycleEvents()
+
+    this.subscriptions.push(() => {
+      this.emitter.removeAllListeners()
+      this.publicEmitter.removeAllListeners()
+    })
+  }
+
+  private validateHandlers(handlers: ReadonlyArray<RequestHandler>): boolean {
+    // Guard against incorrect call signature of the setup API.
+    return handlers.every((handler) => !Array.isArray(handler))
+  }
+
+  public use(...runtimeHandlers: Array<RequestHandler>): void {
+    invariant(
+      this.validateHandlers(runtimeHandlers),
+      devUtils.formatMessage(
+        `Failed to call "use()" with the given request handlers: invalid input. Did you forget to spread the array of request handlers?`,
+      ),
+    )
+
+    this.currentHandlers.unshift(...runtimeHandlers)
+  }
+
+  public restoreHandlers(): void {
+    this.currentHandlers.forEach((handler) => {
+      handler.isUsed = false
+    })
+  }
+
+  public resetHandlers(...nextHandlers: Array<RequestHandler>): void {
+    this.currentHandlers =
+      nextHandlers.length > 0 ? [...nextHandlers] : [...this.initialHandlers]
+  }
+
+  public listHandlers(): ReadonlyArray<
+    RequestHandler<RequestHandlerDefaultInfo, any, any>
+  > {
+    return toReadonlyArray(this.currentHandlers)
+  }
+
+  private createLifeCycleEvents(): LifeCycleEventEmitter<EventsMap> {
+    return {
+      on: (...args: any[]) => {
+        return (this.publicEmitter.on as any)(...args)
+      },
+      removeListener: (...args: any[]) => {
+        return (this.publicEmitter.removeListener as any)(...args)
+      },
+      removeAllListeners: (...args: any[]) => {
+        return this.publicEmitter.removeAllListeners(...args)
+      },
+    }
+  }
+}

package/src/core/bypass.test.ts

@@ -0,0 +1,47 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { bypass } from './bypass'
+
+it('returns bypassed request given a request url string', async () => {
+  const request = bypass('https://api.example.com/resource')
+
+  // Relative URLs are rebased against the current location.
+  expect(request.method).toBe('GET')
+  expect(request.url).toBe('https://api.example.com/resource')
+  expect(Object.fromEntries(request.headers.entries())).toEqual({
+    'x-msw-intention': 'bypass',
+  })
+})
+
+it('returns bypassed request given a request url', async () => {
+  const request = bypass(new URL('/resource', 'https://api.example.com'))
+
+  expect(request.url).toBe('https://api.example.com/resource')
+  expect(Object.fromEntries(request.headers)).toEqual({
+    'x-msw-intention': 'bypass',
+  })
+})
+
+it('returns bypassed request given request instance', async () => {
+  const original = new Request('http://localhost/resource', {
+    method: 'POST',
+    headers: {
+      'X-My-Header': 'value',
+    },
+    body: 'hello world',
+  })
+  const request = bypass(original)
+
+  expect(request.method).toBe('POST')
+  expect(request.url).toBe('http://localhost/resource')
+
+  const bypassedRequestBody = await request.text()
+  expect(original.bodyUsed).toBe(false)
+
+  expect(bypassedRequestBody).toEqual(await original.text())
+  expect(Object.fromEntries(request.headers.entries())).toEqual({
+    ...Object.fromEntries(original.headers.entries()),
+    'x-msw-intention': 'bypass',
+  })
+})

package/src/core/bypass.ts

@@ -0,0 +1,36 @@
+import { invariant } from 'outvariant'
+
+export type BypassRequestInput = string | URL | Request
+
+/**
+ * Creates a `Request` instance that will always be ignored by MSW.
+ *
+ * @example
+ * import { bypass } from 'msw'
+ *
+ * fetch(bypass('/resource'))
+ * fetch(bypass(new URL('/resource', 'https://example.com)))
+ * fetch(bypass(new Request('https://example.com/resource')))
+ *
+ * @see {@link https://mswjs.io/docs/api/bypass `bypass()` API reference}
+ */
+export function bypass(input: BypassRequestInput, init?: RequestInit): Request {
+  const request = input instanceof Request ? input : new Request(input, init)
+
+  invariant(
+    !request.bodyUsed,
+    'Failed to create a bypassed request to "%s %s": given request instance already has its body read. Make sure to clone the intercepted request if you wish to read its body before bypassing it.',
+    request.method,
+    request.url,
+  )
+
+  const requestClone = request.clone()
+
+  // Set the internal header that would instruct MSW
+  // to bypass this request from any further request matching.
+  // Unlike "passthrough()", bypass is meant for performing
+  // additional requests within pending request resolution.
+  requestClone.headers.set('x-msw-intention', 'bypass')
+
+  return requestClone
+}

package/src/core/delay.ts

@@ -0,0 +1,70 @@
+import { isNodeProcess } from 'is-node-process'
+
+export const SET_TIMEOUT_MAX_ALLOWED_INT = 2147483647
+export const MIN_SERVER_RESPONSE_TIME = 100
+export const MAX_SERVER_RESPONSE_TIME = 400
+export const NODE_SERVER_RESPONSE_TIME = 5
+
+function getRealisticResponseTime(): number {
+  if (isNodeProcess()) {
+    return NODE_SERVER_RESPONSE_TIME
+  }
+
+  return Math.floor(
+    Math.random() * (MAX_SERVER_RESPONSE_TIME - MIN_SERVER_RESPONSE_TIME) +
+      MIN_SERVER_RESPONSE_TIME,
+  )
+}
+
+export type DelayMode = 'real' | 'infinite'
+
+/**
+ * Delays the response by the given duration (ms).
+ *
+ * @example
+ * await delay() // emulate realistic server response time
+ * await delay(1200) // delay response by 1200ms
+ * await delay('infinite') // delay response infinitely
+ *
+ * @see {@link https://mswjs.io/docs/api/delay `delay()` API reference}
+ */
+export async function delay(
+  durationOrMode?: DelayMode | number,
+): Promise<void> {
+  let delayTime: number
+
+  if (typeof durationOrMode === 'string') {
+    switch (durationOrMode) {
+      case 'infinite': {
+        // Using `Infinity` as a delay value executes the response timeout immediately.
+        // Instead, use the maximum allowed integer for `setTimeout`.
+        delayTime = SET_TIMEOUT_MAX_ALLOWED_INT
+        break
+      }
+      case 'real': {
+        delayTime = getRealisticResponseTime()
+        break
+      }
+      default: {
+        throw new Error(
+          `Failed to delay a response: unknown delay mode "${durationOrMode}". Please make sure you provide one of the supported modes ("real", "infinite") or a number.`,
+        )
+      }
+    }
+  } else if (typeof durationOrMode === 'undefined') {
+    // Use random realistic server response time when no explicit delay duration was provided.
+    delayTime = getRealisticResponseTime()
+  } else {
+    // Guard against passing values like `Infinity` or `Number.MAX_VALUE`
+    // as the response delay duration. They don't produce the result you may expect.
+    if (durationOrMode > SET_TIMEOUT_MAX_ALLOWED_INT) {
+      throw new Error(
+        `Failed to delay a response: provided delay duration (${durationOrMode}) exceeds the maximum allowed duration for "setTimeout" (${SET_TIMEOUT_MAX_ALLOWED_INT}). This will cause the response to be returned immediately. Please use a number within the allowed range to delay the response by exact duration, or consider the "infinite" delay mode to delay the response indefinitely.`,
+      )
+    }
+
+    delayTime = durationOrMode
+  }
+
+  return new Promise((resolve) => setTimeout(resolve, delayTime))
+}

package/src/core/graphql.test.ts

@@ -0,0 +1,11 @@
+import { graphql } from './graphql'
+
+test('exports supported GraphQL operation types', () => {
+  expect(graphql).toBeDefined()
+  expect(Object.keys(graphql)).toEqual([
+    'query',
+    'mutation',
+    'operation',
+    'link',
+  ])
+})

package/src/core/graphql.ts

@@ -0,0 +1,138 @@
+import type { DocumentNode, OperationTypeNode } from 'graphql'
+import {
+  ResponseResolver,
+  RequestHandlerOptions,
+} from './handlers/RequestHandler'
+import {
+  GraphQLHandler,
+  GraphQLVariables,
+  ExpectedOperationTypeNode,
+  GraphQLHandlerNameSelector,
+  GraphQLResolverExtras,
+  GraphQLResponseBody,
+} from './handlers/GraphQLHandler'
+import type { Path } from './utils/matching/matchRequestUrl'
+
+export interface TypedDocumentNode<
+  Result = { [key: string]: any },
+  Variables = { [key: string]: any },
+> extends DocumentNode {
+  __apiType?: (variables: Variables) => Result
+  __resultType?: Result
+  __variablesType?: Variables
+}
+
+function createScopedGraphQLHandler(
+  operationType: ExpectedOperationTypeNode,
+  url: Path,
+) {
+  return <
+    Query extends Record<string, any>,
+    Variables extends GraphQLVariables = GraphQLVariables,
+  >(
+    operationName:
+      | GraphQLHandlerNameSelector
+      | DocumentNode
+      | TypedDocumentNode<Query, Variables>,
+    resolver: ResponseResolver<
+      GraphQLResolverExtras<Variables>,
+      null,
+      GraphQLResponseBody<Query>
+    >,
+    options: RequestHandlerOptions = {},
+  ) => {
+    return new GraphQLHandler(
+      operationType,
+      operationName,
+      url,
+      resolver,
+      options,
+    )
+  }
+}
+
+function createGraphQLOperationHandler(url: Path) {
+  return <
+    Query extends Record<string, any>,
+    Variables extends GraphQLVariables = GraphQLVariables,
+  >(
+    resolver: ResponseResolver<
+      GraphQLResolverExtras<Variables>,
+      null,
+      GraphQLResponseBody<Query>
+    >,
+  ) => {
+    return new GraphQLHandler('all', new RegExp('.*'), url, resolver)
+  }
+}
+
+const standardGraphQLHandlers = {
+  /**
+   * Intercepts a GraphQL query by a given name.
+   *
+   * @example
+   * graphql.query('GetUser', () => {
+   *   return HttpResponse.json({ data: { user: { name: 'John' } } })
+   * })
+   *
+   * @see {@link https://mswjs.io/docs/api/graphql#graphqlqueryqueryname-resolver `graphql.query()` API reference}
+   */
+  query: createScopedGraphQLHandler('query' as OperationTypeNode, '*'),
+
+  /**
+   * Intercepts a GraphQL mutation by its name.
+   *
+   * @example
+   * graphql.mutation('SavePost', () => {
+   *   return HttpResponse.json({ data: { post: { id: 'abc-123 } } })
+   * })
+   *
+   * @see {@link https://mswjs.io/docs/api/graphql#graphqlmutationmutationname-resolver `graphql.query()` API reference}
+   *
+   */
+  mutation: createScopedGraphQLHandler('mutation' as OperationTypeNode, '*'),
+
+  /**
+   * Intercepts any GraphQL operation, regardless of its type or name.
+   *
+   * @example
+   * graphql.operation(() => {
+   *   return HttpResponse.json({ data: { name: 'John' } })
+   * })
+   *
+   * @see {@link https://mswjs.io/docs/api/graphql#graphloperationresolver `graphql.operation()` API reference}
+   */
+  operation: createGraphQLOperationHandler('*'),
+}
+
+function createGraphQLLink(url: Path): typeof standardGraphQLHandlers {
+  return {
+    operation: createGraphQLOperationHandler(url),
+    query: createScopedGraphQLHandler('query' as OperationTypeNode, url),
+    mutation: createScopedGraphQLHandler('mutation' as OperationTypeNode, url),
+  }
+}
+
+/**
+ * A namespace to intercept and mock GraphQL operations
+ *
+ * @example
+ * graphql.query('GetUser', resolver)
+ * graphql.mutation('DeletePost', resolver)
+ *
+ * @see {@link https://mswjs.io/docs/api/graphql `graphql` API reference}
+ */
+export const graphql = {
+  ...standardGraphQLHandlers,
+
+  /**
+   * 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: createGraphQLLink,
+}