msw 2.15.0 → 3.0.0

package/src/core/handlers/handler.ts

@@ -0,0 +1,42 @@
+import type { MaybePromise } from '../type-utils'
+
+export type HandlerKind = 'request' | 'websocket'
+
+/**
+ * The base class for all the handlers.
+ */
+export abstract class Handler {
+  /**
+   * The kind of the network frame this handler handles.
+   */
+  abstract readonly kind: HandlerKind
+
+  /**
+   * Reset the runtime state this handler accumulated while handling
+   * the network (e.g. generator resolver progress).
+   *
+   * @note This method is invoked automatically when the handlers are
+   * reset (e.g. `server.resetHandlers()`).
+   */
+  public reset(): void {}
+
+  /**
+   * Restore this handler so it can handle the network again after
+   * being exhausted (e.g. via `{ once: true }`).
+   *
+   * @note This method is invoked automatically when the handlers are
+   * restored (e.g. `server.restoreHandlers()`).
+   */
+  public restore(): void {}
+
+  /**
+   * Release the resources held by this handler.
+   *
+   * @note This method is invoked automatically when the network is
+   * disabled (e.g. `server.close()`). Override it in the handlers that
+   * hold onto anything beyond a single frame, like timers, connections,
+   * or event listeners. Returning a promise makes the network await
+   * this handler's disposal before it tears itself down.
+   */
+  public dispose(): MaybePromise<void> {}
+}

package/src/core/handlers/{RequestHandler.ts → request-handler.ts}

@@ -1,20 +1,16 @@
-import { Headers as HeadersPolyfill } from 'headers-polyfill'
-import { getCallFrame } from '../utils/internal/getCallFrame'
-import {
-  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 {
-  type StrictRequest,
-  type DefaultUnsafeFetchResponse,
-} from '../HttpResponse'
-import type { GraphQLRequestBody } from './GraphQLHandler'
-import { devUtils } from '../utils/internal/devUtils'
-import { getRawSetCookie } from '../utils/HttpResponse/decorators'
+import { isNodeProcess } from 'is-node-process'
+import { Handler } from './handler'
+import { getCallFrame } from '../utils/internal/get-call-frame'
+import { isIterable } from '../utils/internal/is-iterable'
+import type { ResponseResolutionContext } from '../utils/execute-handlers'
+import type { MaybePromise } from '../type-utils'
+import type {
+  HttpResponse,
+  StrictRequest,
+  DefaultUnsafeFetchResponse,
+} from '#http/http-response'
+import { devUtils } from '../utils/internal/dev-utils'
+import { getRawSetCookie } from '../utils/response-decorators'
 import { observeResponseBodyStream } from '../utils/internal/observe-response-body-stream'
 
 export type DefaultRequestMultipartBody = Record<
@@ -54,8 +50,10 @@ export type ResponseResolverReturnType<
          * For esome reason, making the default HttpResponse<T> | DefaultUnsafeFetchResponse
          * union breaks the body type inference for HTTP requests.
          * @see https://github.com/mswjs/msw/issues/2130
+         * @note Don't import the actual GraphQL types not to introduce a dependency
+         * from /core to /graphql.
          */
-        ResponseBodyType extends GraphQLRequestBody<any>
+        ResponseBodyType extends Record<string, any> | undefined
         ? HttpResponse<ResponseBodyType> | DefaultUnsafeFetchResponse
         : HttpResponse<ResponseBodyType>)
   | undefined
@@ -103,7 +101,7 @@ export type ResponseResolverInfo<
   finalize: ResponseResolverFinalizeFunction
 } & ResolverExtraInfo
 
-type ResponseResolverFinalizeFunction = (
+export type ResponseResolverFinalizeFunction = (
   callback: () => MaybePromise<void>,
 ) => void
 
@@ -143,13 +141,13 @@ export abstract class RequestHandler<
   ParsedResult extends Record<string, any> | undefined = any,
   ResolverExtras extends Record<string, unknown> = any,
   HandlerOptions extends RequestHandlerOptions = RequestHandlerOptions,
-> {
+> extends Handler {
   static cache = new WeakMap<
     StrictRequest<DefaultBodyType>,
     StrictRequest<DefaultBodyType>
   >()
 
-  public readonly kind = 'request' as const
+  public readonly kind = 'request'
 
   protected resolver: ResponseResolver<ResolverExtras, any, any>
   private resolverIterator?:
@@ -177,6 +175,8 @@ export abstract class RequestHandler<
   public isUsed: boolean
 
   constructor(args: RequestHandlerArgs<HandlerInfo, HandlerOptions>) {
+    super()
+
     this.resolver = args.resolver
     this.options = args.options
     this.scheduledCleanups = new Map()
@@ -197,7 +197,7 @@ export abstract class RequestHandler<
    * removed from the active handlers list so re-adding it later starts
    * from a clean state.
    */
-  protected reset(): void {
+  public reset(): void {
     this.scheduledCleanups.clear()
 
     const iterator = this.resolverIterator
@@ -215,7 +215,7 @@ export abstract class RequestHandler<
    * exhausted (e.g. via `{ once: true }`). Also clears any accumulated
    * resolution state.
    */
-  protected restore(): void {
+  public restore(): void {
     if (this.options?.once) {
       this.reset()
       this.isUsed = false
@@ -670,28 +670,13 @@ export abstract class RequestHandler<
 /**
  * Forwards the cookies from the given response to `document.cookie`.
  */
-export function forwardResponseCookies(response: Response): void {
+function forwardResponseCookies(response: Response): void {
   // Cookie forwarding is only relevant in the browser.
-  if (typeof document === 'undefined') {
+  if (isNodeProcess() || 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) {
+  for (const cookieString of getRawSetCookie(response)) {
     document.cookie = cookieString
   }
 }

package/src/core/index.ts

@@ -1,22 +1,23 @@
-import { checkGlobals } from './utils/internal/checkGlobals'
-
-export { SetupApi } from './experimental/setup-api'
-
 /* HTTP 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'
+export { RequestHandler } from './handlers/request-handler'
+export { http } from '#http/http'
+export { HttpHandler, HttpMethods } from '#http/http-handler'
 
 /* WebSocket handler */
-export { ws, type WebSocketLink } from './ws'
+export {
+  ws,
+  type WebSocketLink,
+  type WebSocketLinkOptions,
+  type WebSocketData,
+  type WebSocketEventListener,
+} from '#ws/ws'
 export {
   WebSocketHandler,
+  WebSocketConnectionEvent,
+  type WebSocketHandlerOptions,
   type WebSocketHandlerEventMap,
   type WebSocketHandlerConnection,
-} from './handlers/WebSocketHandler'
-
+} from '#ws/websocket-handler'
 /* Server-Sent Events */
 export {
   sse,
@@ -24,18 +25,16 @@ export {
   type ServerSentEventResolver,
   type ServerSentEventResolverExtras,
   type ServerSentEventMessage,
-} from './sse'
+} from '#sse/sse'
 
 /* Utils */
-export { matchRequestUrl } from './utils/matching/matchRequestUrl'
-export { handleRequest, type HandleRequestOptions } from './utils/handleRequest'
-export {
-  onUnhandledRequest,
-  type UnhandledRequestStrategy,
-  type UnhandledRequestCallback,
-} from './utils/request/onUnhandledRequest'
-export { getResponse } from './getResponse'
-export { cleanUrl } from './utils/url/cleanUrl'
+export { matchRequestUrl } from './utils/matching/match-request-url'
+export { getResponse } from '#utils/get-response'
+export { getCleanUrlString } from '#utils/get-clean-url-string'
+export type {
+  UnhandledFrameHandle,
+  UnhandledFrameStrategy,
+} from './experimental/on-unhandled-frame'
 
 /**
  * Type definitions.
@@ -43,7 +42,7 @@ export { cleanUrl } from './utils/url/cleanUrl'
 
 export type { AnyHandler } from './experimental/handlers-controller'
 
-export type { SharedOptions, LifeCycleEventsMap } from './sharedOptions'
+export type { SharedOptions } from './shared-options'
 
 export type {
   ResponseResolver,
@@ -54,7 +53,7 @@ export type {
   DefaultRequestMultipartBody,
   JsonBodyType,
   ResponseResolverInfo,
-} from './handlers/RequestHandler'
+} from './handlers/request-handler'
 
 export type {
   RequestQuery,
@@ -63,44 +62,22 @@ export type {
   HttpRequestResolverExtras,
   HttpHandlerMethod,
   HttpCustomPredicate,
-} from './handlers/HttpHandler'
-export type { HttpRequestHandler, HttpResponseResolver } from './http'
+} from '#http/http-handler'
+export type { HttpRequestHandler, HttpResponseResolver } from '#http/http'
 
 export type {
-  GraphQLQuery,
-  GraphQLVariables,
-  GraphQLRequestBody,
-  GraphQLResponseBody,
-  GraphQLJsonRequestBody,
-  GraphQLOperationType,
-  GraphQLCustomPredicate,
-} from './handlers/GraphQLHandler'
-export type {
-  GraphQLRequestHandler,
-  GraphQLOperationHandler,
-  GraphQLResponseResolver,
-  GraphQLLinkHandlers,
-} from './graphql'
-
-export type { WebSocketData, WebSocketEventListener } from './ws'
-
-export type { Path, PathParams, Match } from './utils/matching/matchRequestUrl'
-export type { ParsedGraphQLRequest } from './utils/internal/parseGraphQLRequest'
-export type { ResponseResolutionContext } from './utils/executeHandlers'
+  Path,
+  PathParams,
+  Match,
+} from './utils/matching/match-request-url'
+export type { ResponseResolutionContext } from './utils/execute-handlers'
 
 export {
   HttpResponse,
   type HttpResponseInit,
   type StrictRequest,
-  type StrictResponse,
-} from './HttpResponse'
-export { delay, type DelayMode } from './delay'
-export { bypass } from './bypass'
-export { passthrough } from './passthrough'
-export { isCommonAssetRequest } from './isCommonAssetRequest'
-
-// 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()
+} from '#http/http-response'
+export { delay, type DelayMode } from '#utils/delay'
+export { bypass } from '#utils/bypass'
+export { passthrough, isPassthroughResponse } from '#utils/passthrough'
+export { isCommonAssetRequest } from '#utils/is-common-asset-request'

package/src/core/shared-options.ts

@@ -0,0 +1,21 @@
+import type { Emitter, DefaultEventMap } from 'rettime'
+import type { UnhandledFrameHandle } from './experimental/on-unhandled-frame'
+
+export interface SharedOptions {
+  /**
+   * Specifies how to react to a network frame (e.g. a request or
+   * a WebSocket connection) that has no corresponding handler.
+   * Warns on unhandled frames by default.
+   *
+   * @example worker.start({ onUnhandledFrame: 'bypass' })
+   * @example worker.start({ onUnhandledFrame: 'warn' })
+   * @example server.listen({ onUnhandledFrame: 'error' })
+   * @example server.listen({ onUnhandledFrame({ frame, defaults }) { defaults.warn() } })
+   */
+  onUnhandledFrame?: UnhandledFrameHandle
+}
+
+export type LifeCycleEventEmitter<EventMap extends DefaultEventMap> = Pick<
+  Emitter<EventMap>,
+  'on' | 'removeListener' | 'removeAllListeners'
+>

package/src/core/type-utils.ts

@@ -0,0 +1,18 @@
+export type MaybePromise<T> = T | Promise<T>
+
+/**
+ * Blocks inference from the annotated position, like the built-in `NoInfer`,
+ * but resolves to a plain type once instantiated. The built-in `NoInfer` stays
+ * an opaque wrapper, which makes TypeScript report response body mismatches on
+ * the whole object literal instead of the offending property.
+ */
+export type TransparentNoInfer<T> = [T][T extends any ? 0 : never]
+
+/**
+ * Turns a union of types into an intersection of its members.
+ */
+export type UnionToIntersection<Union> = (
+  Union extends unknown ? (member: Union) => void : never
+) extends (member: infer Intersection) => void
+  ? Intersection
+  : never

package/src/core/utils/{cookieStore.ts → cookie-store.ts}

@@ -7,7 +7,7 @@ import {
   type SerializedCookie,
   type MemoryCookieStoreIndex,
 } from 'tough-cookie'
-import { jsonParse } from './internal/jsonParse'
+import { jsonParse } from './internal/json-parse'
 
 class CookieStore {
   #storageKey = '__msw-cookie-store__'
@@ -15,12 +15,10 @@ class CookieStore {
   #memoryStore: MemoryCookieStore
 
   constructor() {
-    if (!isNodeProcess()) {
-      invariant(
-        typeof localStorage !== 'undefined',
-        'Failed to create a CookieStore: `localStorage` is not available in this environment. This is likely an issue with your environment, which has been detected as browser (or browser-like) environment and must implement global browser APIs correctly.',
-      )
-    }
+    invariant(
+      typeof localStorage !== 'undefined',
+      'Failed to create a CookieStore: `localStorage` is not available in this environment. This is likely an issue with your environment, which has been detected as browser (or browser-like) environment and must implement global browser APIs correctly.',
+    )
 
     this.#memoryStore = new MemoryCookieStore()
     this.#memoryStore.idx = this.getCookieStoreIndex()
@@ -88,8 +86,15 @@ class CookieStore {
       }
     }
 
-    localStorage.setItem(this.#storageKey, JSON.stringify(data))
+    try {
+      localStorage.setItem(this.#storageKey, JSON.stringify(data))
+    } catch {
+      // Persisting cookies is best-effort. If the storage quota is exceeded,
+      // keep the cookies in memory so the request handling continues.
+      return
+    }
   }
 }
 
-export const cookieStore = new CookieStore()
+// Node.js has no implicit cookie jar. Leave cookie management to the client.
+export const cookieStore = isNodeProcess() ? null : new CookieStore()

package/src/core/utils/{executeHandlers.ts → execute-handlers.ts}

@@ -1,5 +1,5 @@
-import type { RequestHandler } from '../handlers/RequestHandler'
-import { type RequestHandlerExecutionResult } from '../handlers/RequestHandler'
+import type { RequestHandler } from '../handlers/request-handler'
+import type { RequestHandlerExecutionResult } from '../handlers/request-handler'
 
 export interface HandlersExecutionResult {
   handler: RequestHandler

package/src/core/utils/http-status-messages.ts

@@ -0,0 +1,69 @@
+/**
+ * Reason phrases of the known HTTP status codes.
+ * @see https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
+ */
+export const httpStatusMessages: Record<number, string> = {
+  100: 'Continue',
+  101: 'Switching Protocols',
+  102: 'Processing',
+  103: 'Early Hints',
+  200: 'OK',
+  201: 'Created',
+  202: 'Accepted',
+  203: 'Non-Authoritative Information',
+  204: 'No Content',
+  205: 'Reset Content',
+  206: 'Partial Content',
+  207: 'Multi-Status',
+  208: 'Already Reported',
+  226: 'IM Used',
+  300: 'Multiple Choices',
+  301: 'Moved Permanently',
+  302: 'Found',
+  303: 'See Other',
+  304: 'Not Modified',
+  305: 'Use Proxy',
+  307: 'Temporary Redirect',
+  308: 'Permanent Redirect',
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  402: 'Payment Required',
+  403: 'Forbidden',
+  404: 'Not Found',
+  405: 'Method Not Allowed',
+  406: 'Not Acceptable',
+  407: 'Proxy Authentication Required',
+  408: 'Request Timeout',
+  409: 'Conflict',
+  410: 'Gone',
+  411: 'Length Required',
+  412: 'Precondition Failed',
+  413: 'Payload Too Large',
+  414: 'URI Too Long',
+  415: 'Unsupported Media Type',
+  416: 'Range Not Satisfiable',
+  417: 'Expectation Failed',
+  418: "I'm a Teapot",
+  421: 'Misdirected Request',
+  422: 'Unprocessable Entity',
+  423: 'Locked',
+  424: 'Failed Dependency',
+  425: 'Too Early',
+  426: 'Upgrade Required',
+  428: 'Precondition Required',
+  429: 'Too Many Requests',
+  431: 'Request Header Fields Too Large',
+  451: 'Unavailable For Legal Reasons',
+  500: 'Internal Server Error',
+  501: 'Not Implemented',
+  502: 'Bad Gateway',
+  503: 'Service Unavailable',
+  504: 'Gateway Timeout',
+  505: 'HTTP Version Not Supported',
+  506: 'Variant Also Negotiates',
+  507: 'Insufficient Storage',
+  508: 'Loop Detected',
+  509: 'Bandwidth Limit Exceeded',
+  510: 'Not Extended',
+  511: 'Network Authentication Required',
+}

package/src/core/utils/internal/{attachSiblingHandlers.ts → attach-sibling-handlers.ts}

@@ -2,6 +2,7 @@ import { invariant } from 'outvariant'
 import type { AnyHandler } from '../../experimental/handlers-controller'
 
 const kSiblingHandlers = Symbol('kSiblingHandlers')
+const kIsSiblingHandler = Symbol('kIsSiblingHandler')
 
 export function attachSiblingHandlers<T extends AnyHandler>(
   owner: T,
@@ -20,9 +21,28 @@ export function attachSiblingHandlers<T extends AnyHandler>(
     configurable: false,
   })
 
+  // Mark the siblings so introspection (e.g. `.listHandlers()`) can tell
+  // explicitly registered handlers from their implementation details.
+  // Shared siblings can be attached to multiple owners, so skip the
+  // already-marked ones.
+  for (const sibling of siblings) {
+    if (!isSiblingHandler(sibling)) {
+      Object.defineProperty(sibling, kIsSiblingHandler, {
+        value: true,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+      })
+    }
+  }
+
   return owner
 }
 
 export function getSiblingHandlers(owner: AnyHandler): Array<AnyHandler> {
   return Reflect.get(owner, kSiblingHandlers) || []
 }
+
+export function isSiblingHandler(handler: AnyHandler): boolean {
+  return Reflect.get(handler, kIsSiblingHandler) === true
+}

package/src/core/utils/internal/{devUtils.test.ts → dev-utils.test.ts}

@@ -1,7 +1,7 @@
-import { InternalError } from './devUtils'
+import { InternalError } from './dev-utils'
 
 describe(InternalError, () => {
-  it('creates an InternalError instance', () => {
+  test('creates an InternalError instance', () => {
     const error = new InternalError('Message')
 
     expect(error.name).toBe('InternalError')
@@ -10,7 +10,7 @@ describe(InternalError, () => {
     expect(error.stack).toMatch(/\w+/)
   })
 
-  it('passes the identity check', () => {
+  test('passes the identity check', () => {
     const error = new InternalError('Message')
     expect(error instanceof InternalError).toBe(true)
     expect(error instanceof Error).toBe(true)

package/src/core/utils/internal/{Disposable.ts → disposable.ts}

@@ -1,4 +1,4 @@
-import { devUtils } from './devUtils'
+import { devUtils } from './dev-utils'
 
 export type DisposableSubscription = () => void
 

package/src/core/utils/internal/{getCallFrame.test.ts → get-call-frame.test.ts}

@@ -1,7 +1,7 @@
 /**
  * @vitest-environment jsdom
  */
-import { getCallFrame } from './getCallFrame'
+import { getCallFrame } from './get-call-frame'
 
 class ErrorWithStack extends Error {
   constructor(stack: string[] | undefined | null) {

package/src/core/utils/internal/{getCallFrame.ts → get-call-frame.ts}

@@ -2,7 +2,7 @@
 const SOURCE_FRAME = /[/\\]msw[/\\]src[/\\](.+)/
 
 const BUILD_FRAME =
-  /(node_modules)?[/\\]lib[/\\](core|browser|node|native|iife)[/\\]|^[^/\\]*$/
+  /(node_modules)?[/\\]lib[/\\](core|browser|node|iife)[/\\]|^[^/\\]*$/
 
 /**
  * Return the stack trace frame of a function's invocation.

package/src/core/utils/internal/{hasRefCounted.test.ts → has-ref-counted.test.ts}

@@ -1,6 +1,6 @@
-import { hasRefCounted } from './hasRefCounted'
+import { hasRefCounted } from './has-ref-counted'
 
-it('returns true for objects with ref and unref methods', () => {
+test('returns true for objects with ref and unref methods', () => {
   expect(
     hasRefCounted({
       ref() {},
@@ -9,13 +9,13 @@ it('returns true for objects with ref and unref methods', () => {
   ).toBe(true)
 })
 
-it('returns false for a non-refcounted object', () => {
+test('returns false for a non-refcounted object', () => {
   expect(hasRefCounted({})).toBe(false)
   expect(hasRefCounted({ ref() {} })).toBe(false)
   expect(hasRefCounted({ unref() {} })).toBe(false)
 })
 
-it('returns false for non-object values', () => {
+test('returns false for non-object values', () => {
   expect(
     hasRefCounted(
       // @ts-expect-error Runtime value.

package/src/core/utils/internal/{hasRefCounted.ts → has-ref-counted.ts}

@@ -1,4 +1,4 @@
-import { isObject } from './isObject'
+import { isObject } from './is-object'
 
 export function hasRefCounted<T extends object>(
   value: T,

package/src/core/utils/internal/{isIterable.test.ts → is-iterable.test.ts}

@@ -1,4 +1,4 @@
-import { isIterable } from './isIterable'
+import { isIterable } from './is-iterable'
 
 test('returns true given an iterator', () => {
   expect(

package/src/core/utils/internal/is-iterable.ts

@@ -0,0 +1,16 @@
+/**
+ * Determines if the given function is an iterator.
+ */
+export function isIterable<IteratorType>(
+  fn: any,
+): fn is
+  | Iterable<IteratorType, IteratorType, IteratorType>
+  | AsyncIterable<IteratorType, IteratorType, IteratorType> {
+  if (!fn) {
+    return false
+  }
+
+  return (
+    Reflect.has(fn, Symbol.iterator) || Reflect.has(fn, Symbol.asyncIterator)
+  )
+}

package/src/core/utils/internal/{isObject.test.ts → is-object.test.ts}

@@ -1,4 +1,4 @@
-import { isObject } from './isObject'
+import { isObject } from './is-object'
 
 test('returns true given an object', () => {
   expect(isObject({})).toBe(true)