msw 2.14.7 → 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,17 @@
-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<
   string,
@@ -31,12 +28,7 @@ export type DefaultBodyType =
   | undefined
 
 export type JsonBodyType =
-  | Record<string, any>
-  | string
-  | number
-  | boolean
-  | null
-  | undefined
+  Record<string, any> | string | number | boolean | null | undefined
 
 export interface RequestHandlerDefaultInfo {
   header: string
@@ -58,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
@@ -94,6 +88,10 @@ export type ResponseResolverInfo<
   /**
    * Schedule a callback to run after this response resolver completes.
    * Handy for cleaning up the side effects introduced in the resolver.
+   *
+   * For responses with a `ReadableStream` body (including `sse()` handlers),
+   * the callback runs once the response stream settles: it is read to
+   * completion, errored, or canceled, or the request is aborted.
    * @example
    * sse('/', ({ client, finalize }) => {
    *   const interval = setInterval(() => client.send({ data: 'ping' }))
@@ -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
@@ -355,20 +355,54 @@ export abstract class RequestHandler<
 
     const listenerController = new AbortController()
 
-    args.request.signal.addEventListener(
-      'abort',
-      () => this.runScheduledCleanups(args.requestId),
-      {
-        once: true,
-        signal: listenerController.signal,
-      },
-    )
+    /**
+     * @note Initialize the `finalize` machinery lazily, on the first
+     * access of the `finalize` property by the resolver. If the resolver
+     * never accesses it, the handler behaves as if `finalize` never
+     * existed: no abort listeners, no scheduled cleanups, and no response
+     * body stream observation (see `this.complete()`).
+     */
+    let finalizeFunction: ResponseResolverFinalizeFunction | undefined
+
+    const getFinalize = (): ResponseResolverFinalizeFunction => {
+      if (finalizeFunction == null) {
+        // Run any scheduled cleanups if the request gets aborted
+        // while the resolver is still executing.
+        if (!args.request.signal.aborted) {
+          args.request.signal.addEventListener(
+            'abort',
+            () => this.runScheduledCleanups(args.requestId),
+            {
+              once: true,
+              signal: listenerController.signal,
+            },
+          )
+        }
+
+        finalizeFunction = (callback) => {
+          this.scheduleCleanup(args.requestId, callback)
+
+          /**
+           * @note Run the cleanup immediately if the request has already
+           * been aborted. The "abort" listener above never fires for an
+           * already-aborted signal (and fires at most once), while
+           * long-lived resolvers (streams, generators) may never settle
+           * to run the cleanups on completion.
+           */
+          if (args.request.signal.aborted) {
+            void this.runScheduledCleanups(args.requestId)
+          }
+        }
+      }
+
+      return finalizeFunction
+    }
 
     const mockedResponsePromise = (
       executeResolver({
         ...resolverExtras,
-        finalize: (callback) => {
-          this.scheduleCleanup(args.requestId, callback)
+        get finalize(): ResponseResolverFinalizeFunction {
+          return getFinalize()
         },
         requestId: args.requestId,
         request: args.request,
@@ -423,9 +457,13 @@ export abstract class RequestHandler<
         }
 
         if (!isIterable(result)) {
-          // Otherwise, run the cleanup immediately if it's a plain response resolver.
-          await this.runScheduledCleanups(info.requestId)
-          return result
+          // Otherwise, run the cleanups if it's a plain response resolver
+          // (deferred until the response stream settles for streamed responses).
+          return this.complete({
+            request: info.request,
+            requestId: info.requestId,
+            response: result,
+          })
         }
 
         /**
@@ -465,11 +503,13 @@ export abstract class RequestHandler<
         // only after it's been completely exhausted.
         this.isUsed = true
 
-        await this.runScheduledCleanups(info.requestId)
-
         // Clone the previously stored response so it can be read
         // when receiving it repeatedly from the "done" generator.
-        return this.resolverIteratorResult?.clone()
+        return this.complete({
+          request: info.request,
+          requestId: info.requestId,
+          response: this.resolverIteratorResult?.clone(),
+        })
       }
 
       return nextResponse
@@ -532,56 +572,111 @@ export abstract class RequestHandler<
     }
   }
 
-  private async runScheduledCleanups(requestId: string): Promise<void> {
+  /**
+   * Remove and return the cleanups scheduled for the given request
+   * (or the pending iterator cleanups for generator resolvers).
+   */
+  private takeScheduledCleanups(
+    requestId: string,
+  ): Array<() => MaybePromise<void>> | undefined {
     if (
       this.resolverIterator &&
       this.resolverIteratorCleanups != null &&
       this.resolverIteratorCleanups.length > 0
     ) {
-      try {
-        await this.exhaustCleanups(this.resolverIteratorCleanups)
-      } finally {
-        this.resolverIteratorCleanups = undefined
-      }
-      return
+      const cleanups = this.resolverIteratorCleanups
+      this.resolverIteratorCleanups = undefined
+      return cleanups
     }
 
     const cleanups = this.scheduledCleanups.get(requestId)
 
-    if (!cleanups || cleanups.length == 0) {
-      return
+    if (!cleanups || cleanups.length === 0) {
+      return undefined
     }
 
-    await this.exhaustCleanups(cleanups)
     this.scheduledCleanups.delete(requestId)
+    return cleanups
+  }
+
+  private async runScheduledCleanups(requestId: string): Promise<void> {
+    const cleanups = this.takeScheduledCleanups(requestId)
+
+    if (cleanups) {
+      await this.exhaustCleanups(cleanups)
+    }
+  }
+
+  /**
+   * Conclude the response resolution for the given request.
+   * Runs the scheduled cleanups immediately for responses without a
+   * `ReadableStream` body. For streamed responses, returns an observed
+   * copy of the response and defers the cleanups until its body settles
+   * (is read to completion, errored, or canceled) or the request is
+   * aborted, whichever comes first.
+   */
+  private async complete(args: {
+    request: StrictRequest<any>
+    requestId: string
+    response: Response | undefined | void
+  }): Promise<Response | undefined | void> {
+    const cleanups = this.takeScheduledCleanups(args.requestId)
+
+    if (!cleanups) {
+      return args.response
+    }
+
+    const observedResponse = args.response
+      ? observeResponseBodyStream(args.response)
+      : null
+
+    if (!observedResponse) {
+      await this.exhaustCleanups(cleanups)
+      return args.response
+    }
+
+    const listenerController = new AbortController()
+
+    const runCleanupsOnce = (): void => {
+      if (listenerController.signal.aborted) {
+        return
+      }
+
+      listenerController.abort()
+      void this.exhaustCleanups(cleanups)
+    }
+
+    void observedResponse.settled.then(runCleanupsOnce)
+
+    /**
+     * @note Also run the cleanups when the request is aborted.
+     * Stream cancellation does not always propagate to the observed
+     * response (e.g. if an unconsumed clone of the response exists),
+     * while the request abort reliably means the response is unused.
+     */
+    if (args.request.signal.aborted) {
+      runCleanupsOnce()
+    } else {
+      args.request.signal.addEventListener('abort', runCleanupsOnce, {
+        once: true,
+        signal: listenerController.signal,
+      })
+    }
+
+    return observedResponse.response
   }
 }
 
 /**
  * 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') {
-    return
-  }
-
-  const responseCookies = getRawSetCookie(response)
-
-  if (!responseCookies) {
+  if (isNodeProcess() || typeof document === 'undefined') {
     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