@mswjs/interceptors 0.22.16 → 0.24.0

package/README.md

@@ -116,15 +116,18 @@ interceptor.apply()
 
 // Listen to any "http.ClientRequest" being dispatched,
 // and log its method and full URL.
-interceptor.on('request', (request, requestId) => {
+interceptor.on('request', ({ request, requestId }) => {
   console.log(request.method, request.url)
 })
 
 // Listen to any responses sent to "http.ClientRequest".
 // Note that this listener is read-only and cannot affect responses.
-interceptor.on('response', (response, request) => {
-  console.log('response to %s %s was:', request.method, request.url, response)
-})
+interceptor.on(
+  'response',
+  ({ response, isMockedResponse, request, requestId }) => {
+    console.log('response to %s %s was:', request.method, request.url, response)
+  }
+)
 ```
 
 All HTTP request interceptors implement the same events:
@@ -203,7 +206,7 @@ All HTTP request interceptors emit a "request" event. In the listener to this ev
 > There are many ways to describe a request in Node.js but this library coerces different request definitions to a single specification-compliant `Request` instance to make the handling consistent.
 
 ```js
-interceptor.on('reqest', (request, requestId) => {
+interceptor.on('request', ({ request, requestId }) => {
   console.log(request.method, request.url)
 })
 ```
@@ -211,7 +214,7 @@ interceptor.on('reqest', (request, requestId) => {
 Since the exposed `request` instance implements the Fetch API specification, you can operate with it just as you do with the regular browser request. For example, this is how you would read the request body as JSON:
 
 ```js
-interceptor.on('request', async (request, requestId) => {
+interceptor.on('request', async ({ request, requestId }) => {
   const json = await request.clone().json()
 })
 ```
@@ -223,7 +226,7 @@ interceptor.on('request', async (request, requestId) => {
 Request representations are readonly. You can, however, mutate the intercepted request's headers in the "request" listener:
 
 ```js
-interceptor.on('request', (request) => {
+interceptor.on('request', ({ request }) => {
   request.headers.set('X-My-Header', 'true')
 })
 ```
@@ -237,7 +240,7 @@ Although this library can be used purely for request introspection purposes, you
 Use the `request.respondWith()` method to respond to a request with a mocked response:
 
 ```js
-interceptor.on('request', (request, requestId) => {
+interceptor.on('request', ({ request, requestId }) => {
   request.respondWith(
     new Response(
       JSON.stringify({
@@ -267,12 +270,27 @@ Requests must be responded to within the same tick as the request listener. This
 ```js
 // Respond to all requests with a 500 response
 // delayed by 500ms.
-interceptor.on('request', async (request, requestId) => {
+interceptor.on('request', async ({ request, requestId }) => {
   await sleep(500)
   request.respondWith(new Response(null, { status: 500 }))
 })
 ```
 
+## Observing responses
+
+You can use the "response" event to transparently observe any incoming responses in your Node.js process.
+
+```js
+interceptor.on(
+  'response',
+  ({ response, isMockedResponse, request, requestId }) => {
+    // react to the incoming response...
+  }
+)
+```
+
+> Note that the `isMockedResponse` property will only be set to `true` if you resolved this request in the "request" event listener using the `request.respondWith()` method and providing a mocked `Response` instance.
+
 ## API
 
 ### `Interceptor`
@@ -312,7 +330,7 @@ const interceptor = new BatchInterceptor({
 
 interceptor.apply()
 
-interceptor.on('request', (request, requestId) => {
+interceptor.on('request', ({ request, requestId }) => {
   // Inspect the intercepted "request".
   // Optionally, return a mocked response.
 })
@@ -360,7 +378,7 @@ const resolver = new RemoteHttpResolver({
   process: appProcess,
 })
 
-resolver.on('request', (request, requestId) => {
+resolver.on('request', ({ request, requestId }) => {
   // Optionally, return a mocked response
   // for a request that occurred in the "appProcess".
 })

package/lib/browser/{Interceptor-c8fc448a.d.ts → Interceptor-0a020bc4.d.ts}

@@ -16,8 +16,20 @@ type InteractiveRequest = globalThis.Request & {
 declare const IS_PATCHED_MODULE: unique symbol;
 type RequestCredentials = 'omit' | 'include' | 'same-origin';
 type HttpRequestEventMap = {
-    request: [request: InteractiveRequest, requestId: string];
-    response: [response: Response, request: Request, requestId: string];
+    request: [
+        args: {
+            request: InteractiveRequest;
+            requestId: string;
+        }
+    ];
+    response: [
+        args: {
+            response: Response;
+            isMockedResponse: boolean;
+            request: Request;
+            requestId: string;
+        }
+    ];
 };
 
 interface QueueItem<Args extends Array<unknown>> {

package/lib/browser/{chunk-OQKDMHBL.js → chunk-2TENISKM.js}

@@ -5,12 +5,12 @@ var _chunkPCFJD76Xjs = require('./chunk-PCFJD76X.js');
 
 
 
-var _chunk7VJMJSIJjs = require('./chunk-7VJMJSIJ.js');
+var _chunk4CFMDU7Zjs = require('./chunk-4CFMDU7Z.js');
 
 // src/interceptors/fetch/index.ts
 var _outvariant = require('outvariant');
 var _until = require('@open-draft/until');
-var _FetchInterceptor = class extends _chunk7VJMJSIJjs.Interceptor {
+var _FetchInterceptor = class extends _chunk4CFMDU7Zjs.Interceptor {
   constructor() {
     super(_FetchInterceptor.symbol);
   }
@@ -20,7 +20,7 @@ var _FetchInterceptor = class extends _chunk7VJMJSIJjs.Interceptor {
   setup() {
     const pureFetch = globalThis.fetch;
     _outvariant.invariant.call(void 0, 
-      !pureFetch[_chunk7VJMJSIJjs.IS_PATCHED_MODULE],
+      !pureFetch[_chunk4CFMDU7Zjs.IS_PATCHED_MODULE],
       'Failed to patch the "fetch" module: already patched.'
     );
     globalThis.fetch = async (input, init) => {
@@ -33,12 +33,15 @@ var _FetchInterceptor = class extends _chunk7VJMJSIJjs.Interceptor {
         'emitting the "request" event for %d listener(s)...',
         this.emitter.listenerCount("request")
       );
-      this.emitter.emit("request", interactiveRequest, requestId);
+      this.emitter.emit("request", {
+        request: interactiveRequest,
+        requestId
+      });
       this.logger.info("awaiting for the mocked response...");
       const resolverResult = await _until.until.call(void 0, async () => {
         await this.emitter.untilIdle(
           "request",
-          ({ args: [, pendingRequestId] }) => {
+          ({ args: [{ requestId: pendingRequestId }] }) => {
             return pendingRequestId === requestId;
           }
         );
@@ -56,13 +59,13 @@ var _FetchInterceptor = class extends _chunk7VJMJSIJjs.Interceptor {
       const mockedResponse = resolverResult.data;
       if (mockedResponse && !((_a = request.signal) == null ? void 0 : _a.aborted)) {
         this.logger.info("received mocked response:", mockedResponse);
-        const responseCloine = mockedResponse.clone();
-        this.emitter.emit(
-          "response",
-          responseCloine,
-          interactiveRequest,
+        const responseClone = mockedResponse.clone();
+        this.emitter.emit("response", {
+          response: responseClone,
+          isMockedResponse: true,
+          request: interactiveRequest,
           requestId
-        );
+        });
         const response = new Response(mockedResponse.body, mockedResponse);
         Object.defineProperty(response, "url", {
           writable: false,
@@ -76,22 +79,22 @@ var _FetchInterceptor = class extends _chunk7VJMJSIJjs.Interceptor {
       return pureFetch(request).then((response) => {
         const responseClone = response.clone();
         this.logger.info("original fetch performed", responseClone);
-        this.emitter.emit(
-          "response",
-          responseClone,
-          interactiveRequest,
+        this.emitter.emit("response", {
+          response: responseClone,
+          isMockedResponse: false,
+          request: interactiveRequest,
           requestId
-        );
+        });
         return response;
       });
     };
-    Object.defineProperty(globalThis.fetch, _chunk7VJMJSIJjs.IS_PATCHED_MODULE, {
+    Object.defineProperty(globalThis.fetch, _chunk4CFMDU7Zjs.IS_PATCHED_MODULE, {
       enumerable: true,
       configurable: true,
       value: true
     });
     this.subscriptions.push(() => {
-      Object.defineProperty(globalThis.fetch, _chunk7VJMJSIJjs.IS_PATCHED_MODULE, {
+      Object.defineProperty(globalThis.fetch, _chunk4CFMDU7Zjs.IS_PATCHED_MODULE, {
         value: void 0
       });
       globalThis.fetch = pureFetch;

package/lib/{node/chunk-IHW3ERPT.js → browser/chunk-3LFH2WCF.js}

@@ -1,12 +1,4 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});
-
-var _chunkMPFSBY4Sjs = require('./chunk-MPFSBY4S.js');
-
-// src/shims/webEncoding.ts
-var TextEncoder = typeof globalThis.TextEncoder === "undefined" ? _chunkMPFSBY4Sjs.__require.call(void 0, "util").TextEncoder : globalThis.TextEncoder;
-var TextDecoder = typeof globalThis.TextDecoder === "undefined" ? _chunkMPFSBY4Sjs.__require.call(void 0, "util").TextDecoder : globalThis.TextDecoder;
-
-// src/utils/bufferUtils.ts
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/utils/bufferUtils.ts
 var encoder = new TextEncoder();
 function encodeBuffer(text) {
   return encoder.encode(text);

package/lib/{node/chunk-MPFSBY4S.js → browser/chunk-4CFMDU7Z.js}

@@ -1,10 +1,5 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined")
-    return require.apply(this, arguments);
-  throw new Error('Dynamic require of "' + x + '" is not supported');
-});
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/glossary.ts
+var IS_PATCHED_MODULE = Symbol("isPatchedModule");
 
 // src/Interceptor.ts
 var _logger = require('@open-draft/logger');
@@ -71,6 +66,11 @@ var AsyncEventEmitter = class extends _stricteventemitter.Emitter {
     });
     return super.emit(eventName, ...data);
   }
+  /**
+   * Returns a promise that resolves when all the listeners for the given event
+   * has been called. Awaits asynchronous listeners.
+   * If the event has no listeners, resolves immediately.
+   */
   async untilIdle(eventName, filter = () => true) {
     const listenersQueue = this.queue.get(eventName) || [];
     await Promise.all(
@@ -112,6 +112,11 @@ var AsyncEventEmitter = class extends _stricteventemitter.Emitter {
     this.readyState = "ACTIVE" /* ACTIVE */;
     logger.info("set state to:", this.readyState);
   }
+  /**
+   * Deactivate this event emitter.
+   * Deactivated emitter can no longer emit and listen to events
+   * and needs to be activated again in order to do so.
+   */
   deactivate() {
     const logger = this.logger.extend("deactivate");
     logger.info("removing all listeners...");
@@ -126,7 +131,10 @@ var AsyncEventEmitter = class extends _stricteventemitter.Emitter {
 
 // src/Interceptor.ts
 function getGlobalSymbol(symbol) {
-  return globalThis[symbol] || void 0;
+  return (
+    // @ts-ignore https://github.com/Microsoft/TypeScript/issues/24587
+    globalThis[symbol] || void 0
+  );
 }
 function setGlobalSymbol(symbol, value) {
   globalThis[symbol] = value;
@@ -152,9 +160,17 @@ var Interceptor = class {
     this.emitter.setMaxListeners(0);
     this.logger.info("constructing the interceptor...");
   }
+  /**
+   * Determine if this interceptor can be applied
+   * in the current environment.
+   */
   checkEnvironment() {
     return true;
   }
+  /**
+   * Apply this interceptor to the current process.
+   * Returns an already running interceptor instance if it's present.
+   */
   apply() {
     const logger = this.logger.extend("apply");
     logger.info("applying the interceptor...");
@@ -189,8 +205,16 @@ var Interceptor = class {
     this.setInstance();
     this.readyState = "APPLIED" /* APPLIED */;
   }
+  /**
+   * Setup the module augments and stubs necessary for this interceptor.
+   * This method is not run if there's a running interceptor instance
+   * to prevent instantiating an interceptor multiple times.
+   */
   setup() {
   }
+  /**
+   * Listen to the interceptor's public events.
+   */
   on(eventName, listener) {
     const logger = this.logger.extend("on");
     if (this.readyState === "DISPOSING" /* DISPOSING */ || this.readyState === "DISPOSED" /* DISPOSED */) {
@@ -200,6 +224,9 @@ var Interceptor = class {
     logger.info('adding "%s" event listener:', eventName, listener.name);
     this.emitter.on(eventName, listener);
   }
+  /**
+   * Disposes of any side-effects this interceptor has introduced.
+   */
   dispose() {
     const logger = this.logger.extend("dispose");
     if (this.readyState === "DISPOSED" /* DISPOSED */) {
@@ -248,4 +275,4 @@ var Interceptor = class {
 
 
 
-exports.__require = __require; exports.getGlobalSymbol = getGlobalSymbol; exports.deleteGlobalSymbol = deleteGlobalSymbol; exports.InterceptorReadyState = InterceptorReadyState; exports.Interceptor = Interceptor;
+exports.IS_PATCHED_MODULE = IS_PATCHED_MODULE; exports.getGlobalSymbol = getGlobalSymbol; exports.deleteGlobalSymbol = deleteGlobalSymbol; exports.InterceptorReadyState = InterceptorReadyState; exports.Interceptor = Interceptor;

package/lib/{node/chunk-LTX5IGCQ.mjs → browser/chunk-7II4SWKS.mjs}

@@ -1,11 +1,3 @@
-import {
-  __require
-} from "./chunk-Y5QA6OEZ.mjs";
-
-// src/shims/webEncoding.ts
-var TextEncoder = typeof globalThis.TextEncoder === "undefined" ? __require("util").TextEncoder : globalThis.TextEncoder;
-var TextDecoder = typeof globalThis.TextDecoder === "undefined" ? __require("util").TextDecoder : globalThis.TextDecoder;
-
 // src/utils/bufferUtils.ts
 var encoder = new TextEncoder();
 function encodeBuffer(text) {

package/lib/browser/{chunk-CCRODCJY.mjs → chunk-B74BGPYH.mjs}

@@ -2,7 +2,7 @@ import {
   decodeBuffer,
   encodeBuffer,
   toArrayBuffer
-} from "./chunk-MQA5WAD4.mjs";
+} from "./chunk-7II4SWKS.mjs";
 import {
   toInteractiveRequest,
   uuidv4
@@ -10,7 +10,7 @@ import {
 import {
   IS_PATCHED_MODULE,
   Interceptor
-} from "./chunk-MW6NCDWE.mjs";
+} from "./chunk-GXJLJMOT.mjs";
 
 // src/interceptors/XMLHttpRequest/index.ts
 import { invariant as invariant2 } from "outvariant";
@@ -19,7 +19,8 @@ import { invariant as invariant2 } from "outvariant";
 import { until } from "@open-draft/until";
 
 // src/interceptors/XMLHttpRequest/XMLHttpRequestController.ts
-import { headersToString } from "headers-polyfill";
+import { invariant } from "outvariant";
+import { isNodeProcess } from "is-node-process";
 
 // src/interceptors/XMLHttpRequest/utils/concatArrayBuffer.ts
 function concatArrayBuffer(left, right) {
@@ -201,17 +202,32 @@ function parseJson(data) {
 }
 
 // src/interceptors/XMLHttpRequest/utils/createResponse.ts
-import { stringToHeaders } from "headers-polyfill";
-function createResponse(request, responseBody) {
-  return new Response(responseBody, {
+function createResponse(request, body) {
+  return new Response(body, {
     status: request.status,
     statusText: request.statusText,
-    headers: stringToHeaders(request.getAllResponseHeaders())
+    headers: createHeadersFromXMLHttpReqestHeaders(
+      request.getAllResponseHeaders()
+    )
   });
 }
+function createHeadersFromXMLHttpReqestHeaders(headersString) {
+  const headers = new Headers();
+  const lines = headersString.split(/[\r\n]+/);
+  for (const line of lines) {
+    if (line.trim() === "") {
+      continue;
+    }
+    const [name, ...parts] = line.split(": ");
+    const value = parts.join(": ");
+    headers.append(name, value);
+  }
+  return headers;
+}
 
 // src/interceptors/XMLHttpRequest/XMLHttpRequestController.ts
-import { invariant } from "outvariant";
+var IS_MOCKED_RESPONSE = Symbol("isMockedResponse");
+var IS_NODE = isNodeProcess();
 var XMLHttpRequestController = class {
   constructor(initialRequest, logger) {
     this.initialRequest = initialRequest;
@@ -219,6 +235,7 @@ var XMLHttpRequestController = class {
     this.method = "GET";
     this.url = null;
     this.events = /* @__PURE__ */ new Map();
+    this.requestId = uuidv4();
     this.requestHeaders = new Headers();
     this.responseBuffer = new Uint8Array();
     this.request = createProxy(initialRequest, {
@@ -241,7 +258,6 @@ var XMLHttpRequestController = class {
         switch (methodName) {
           case "open": {
             const [method, url] = args;
-            this.requestId = uuidv4();
             if (typeof url === "undefined") {
               this.method = "GET";
               this.url = toAbsoluteUrl(method);
@@ -274,25 +290,35 @@ var XMLHttpRequestController = class {
               if (typeof this.onResponse !== "undefined") {
                 const fetchResponse = createResponse(
                   this.request,
+                  /**
+                   * The `response` property is the right way to read
+                   * the ambiguous response body, as the request's "responseType" may differ.
+                   * @see https://xhr.spec.whatwg.org/#the-response-attribute
+                   */
                   this.request.response
                 );
-                this.onResponse.call(
-                  this,
-                  fetchResponse,
-                  fetchRequest,
-                  this.requestId
-                );
+                this.onResponse.call(this, {
+                  response: fetchResponse,
+                  isMockedResponse: IS_MOCKED_RESPONSE in this.request,
+                  request: fetchRequest,
+                  requestId: this.requestId
+                });
               }
             });
             const fetchRequest = this.toFetchApiRequest();
-            const onceRequestSettled = ((_a = this.onRequest) == null ? void 0 : _a.call(this, fetchRequest, this.requestId)) || Promise.resolve();
+            const onceRequestSettled = ((_a = this.onRequest) == null ? void 0 : _a.call(this, {
+              request: fetchRequest,
+              requestId: this.requestId
+            })) || Promise.resolve();
             onceRequestSettled.finally(() => {
               if (this.request.readyState < this.request.LOADING) {
                 this.logger.info(
                   "request callback settled but request has not been handled (readystate %d), performing as-is...",
                   this.request.readyState
                 );
-                this.request.setRequestHeader("X-Request-Id", this.requestId);
+                if (IS_NODE) {
+                  this.request.setRequestHeader("X-Request-Id", this.requestId);
+                }
                 return invoke();
               }
             });
@@ -311,12 +337,17 @@ var XMLHttpRequestController = class {
     this.events.set(eventName, nextEvents);
     this.logger.info('registered event "%s"', eventName, listener.name);
   }
+  /**
+   * Responds to the current request with the given
+   * Fetch API `Response` instance.
+   */
   respondWith(response) {
     this.logger.info(
       "responding with a mocked response: %d %s",
       response.status,
       response.statusText
     );
+    define(this.request, IS_MOCKED_RESPONSE, true);
     define(this.request, "status", response.status);
     define(this.request, "statusText", response.statusText);
     define(this.request, "responseURL", this.url.href);
@@ -345,7 +376,10 @@ var XMLHttpRequestController = class {
             this.logger.info("headers not received yet, returning empty string");
             return "";
           }
-          const allHeaders = headersToString(response.headers);
+          const headersList = Array.from(response.headers.entries());
+          const allHeaders = headersList.map(([headerName, headerValue]) => {
+            return `${headerName}: ${headerValue}`;
+          }).join("\r\n");
           this.logger.info("resolved all response headers to", allHeaders);
           return allHeaders;
         }
@@ -368,7 +402,12 @@ var XMLHttpRequestController = class {
         get: () => this.responseXML
       }
     });
-    const totalResponseBodyLength = response.headers.has("Content-Length") ? Number(response.headers.get("Content-Length")) : void 0;
+    const totalResponseBodyLength = response.headers.has("Content-Length") ? Number(response.headers.get("Content-Length")) : (
+      /**
+       * @todo Infer the response body length from the response body.
+       */
+      void 0
+    );
     this.logger.info("calculated response body length", totalResponseBodyLength);
     this.trigger("loadstart", {
       loaded: 0,
@@ -499,6 +538,9 @@ var XMLHttpRequestController = class {
     this.trigger("error");
     this.trigger("loadend");
   }
+  /**
+   * Transitions this request's `readyState` to the given one.
+   */
   setReadyState(nextReadyState) {
     this.logger.info(
       "setReadyState: %d -> %d",
@@ -516,6 +558,9 @@ var XMLHttpRequestController = class {
       this.trigger("readystatechange");
     }
   }
+  /**
+   * Triggers given event on the `XMLHttpRequest` instance.
+   */
   trigger(eventName, options) {
     const callback = this.request[`on${eventName}`];
     const event = createEvent(this.request, eventName, options);
@@ -535,11 +580,17 @@ var XMLHttpRequestController = class {
       }
     }
   }
+  /**
+   * Converts this `XMLHttpRequest` instance into a Fetch API `Request` instance.
+   */
   toFetchApiRequest() {
     this.logger.info("converting request to a Fetch API Request...");
     const fetchRequest = new Request(this.url.href, {
       method: this.method,
       headers: this.requestHeaders,
+      /**
+       * @see https://xhr.spec.whatwg.org/#cross-origin-credentials
+       */
       credentials: this.request.withCredentials ? "include" : "same-origin",
       body: ["GET", "HEAD"].includes(this.method) ? null : this.requestBody
     });
@@ -573,6 +624,7 @@ function toAbsoluteUrl(url) {
 }
 function define(target, property, value) {
   Reflect.defineProperty(target, property, {
+    // Ensure writable properties to allow redefining readonly properties.
     writable: true,
     enumerable: true,
     value
@@ -602,18 +654,21 @@ function createXMLHttpRequestProxy({
         originalRequest,
         logger
       );
-      requestController.onRequest = async function(request, requestId) {
+      requestController.onRequest = async function({ request, requestId }) {
         const interactiveRequest = toInteractiveRequest(request);
         this.logger.info(
           'emitting the "request" event for %s listener(s)...',
           emitter.listenerCount("request")
         );
-        emitter.emit("request", interactiveRequest, requestId);
+        emitter.emit("request", {
+          request: interactiveRequest,
+          requestId
+        });
         this.logger.info("awaiting mocked response...");
         const resolverResult = await until(async () => {
           await emitter.untilIdle(
             "request",
-            ({ args: [, pendingRequestId] }) => {
+            ({ args: [{ requestId: pendingRequestId }] }) => {
               return pendingRequestId === requestId;
             }
           );
@@ -643,12 +698,22 @@ function createXMLHttpRequestProxy({
           "no mocked response received, performing request as-is..."
         );
       };
-      requestController.onResponse = async function(response, request, requestId) {
+      requestController.onResponse = async function({
+        response,
+        isMockedResponse,
+        request,
+        requestId
+      }) {
         this.logger.info(
           'emitting the "response" event for %s listener(s)...',
           emitter.listenerCount("response")
         );
-        emitter.emit("response", response, request, requestId);
+        emitter.emit("response", {
+          response,
+          isMockedResponse,
+          request,
+          requestId
+        });
       };
       return requestController.request;
     }