@mswjs/interceptors 0.15.3 → 0.16.0

package/src/interceptors/fetch/index.ts

@@ -1,79 +1,105 @@
 import {
   Headers,
-  headersToObject,
-  objectToHeaders,
   flattenHeadersObject,
+  objectToHeaders,
+  headersToObject,
 } from 'headers-polyfill'
-import {
-  Interceptor,
-  IsomorphicRequest,
+import type {
+  HttpRequestEventMap,
+  InteractiveIsomorphicRequest,
   IsomorphicResponse,
-} from '../../createInterceptor'
+} from '../../glossary'
+import { Interceptor } from '../../Interceptor'
+import { createLazyCallback } from '../../utils/createLazyCallback'
 import { toIsoResponse } from '../../utils/toIsoResponse'
 import { uuidv4 } from '../../utils/uuid'
 
-const debug = require('debug')('fetch')
+export class FetchInterceptor extends Interceptor<HttpRequestEventMap> {
+  static symbol = Symbol('fetch')
 
-export const interceptFetch: Interceptor = (observer, resolver) => {
-  const pureFetch = window.fetch
+  constructor() {
+    super(FetchInterceptor.symbol)
+  }
 
-  debug('replacing "window.fetch"...')
+  protected checkEnvironment() {
+    return (
+      typeof globalThis !== 'undefined' &&
+      typeof globalThis.fetch !== 'undefined'
+    )
+  }
 
-  window.fetch = async (input, init) => {
-    const request = new Request(input, init)
-    const url = typeof input === 'string' ? input : input.url
-    const method = request.method
+  protected setup() {
+    const pureFetch = globalThis.fetch
 
-    debug('[%s] %s', method, url)
+    globalThis.fetch = async (input, init) => {
+      const request = new Request(input, init)
+      const url = typeof input === 'string' ? input : input.url
+      const method = request.method
 
-    const isoRequest: IsomorphicRequest = {
-      id: uuidv4(),
-      url: new URL(url, location.origin),
-      method: method,
-      headers: new Headers(request.headers),
-      credentials: request.credentials,
-      body: await request.clone().text(),
-    }
-    debug('isomorphic request', isoRequest)
-    observer.emit('request', isoRequest)
+      this.log('[%s] %s', method, url)
 
-    debug('awaiting for the mocked response...')
-    const response = await resolver(isoRequest, request)
-    debug('mocked response', response)
+      const isomorphicRequest: InteractiveIsomorphicRequest = {
+        id: uuidv4(),
+        url: new URL(url, location.origin),
+        method: method,
+        headers: new Headers(request.headers),
+        credentials: request.credentials,
+        body: await request.clone().text(),
+        respondWith: createLazyCallback(),
+      }
 
-    if (response) {
-      const isomorphicResponse = toIsoResponse(response)
-      debug('derived isomorphic response', isomorphicResponse)
+      this.log('isomorphic request', isomorphicRequest)
 
-      observer.emit('response', isoRequest, isomorphicResponse)
+      this.log(
+        'emitting the "request" event for %d listener(s)...',
+        this.emitter.listenerCount('request')
+      )
+      this.emitter.emit('request', isomorphicRequest)
 
-      return new Response(response.body, {
-        ...isomorphicResponse,
-        // `Response.headers` cannot be instantiated with the `Headers` polyfill.
-        // Apparently, it halts if the `Headers` class contains unknown properties
-        // (i.e. the internal `Headers.map`).
-        headers: flattenHeadersObject(response.headers || {}),
-      })
-    }
+      this.log('awaiting for the mocked response...')
 
-    debug('no mocked response found, bypassing...')
+      await this.emitter.untilIdle('request')
+      this.log('all request listeners have been resolved!')
 
-    return pureFetch(request).then(async (response) => {
-      const cloneResponse = response.clone()
-      debug('original fetch performed', cloneResponse)
+      const [mockedResponse] = await isomorphicRequest.respondWith.invoked()
+      this.log('event.respondWith called with:', mockedResponse)
 
-      observer.emit(
-        'response',
-        isoRequest,
-        await normalizeFetchResponse(cloneResponse)
-      )
-      return response
-    })
-  }
+      if (mockedResponse) {
+        this.log('received mocked response:', mockedResponse)
+
+        const isomorphicResponse = toIsoResponse(mockedResponse)
+        this.log('derived isomorphic response:', isomorphicResponse)
+
+        this.emitter.emit('response', isomorphicRequest, isomorphicResponse)
+
+        return new Response(mockedResponse.body, {
+          ...isomorphicResponse,
+          // `Response.headers` cannot be instantiated with the `Headers` polyfill.
+          // Apparently, it halts if the `Headers` class contains unknown properties
+          // (i.e. the internal `Headers.map`).
+          headers: flattenHeadersObject(mockedResponse.headers || {}),
+        })
+      }
+
+      this.log('no mocked response received!')
 
-  return () => {
-    debug('restoring modules...')
-    window.fetch = pureFetch
+      return pureFetch(request).then(async (response) => {
+        const cloneResponse = response.clone()
+        this.log('original fetch performed', cloneResponse)
+
+        this.emitter.emit(
+          'response',
+          isomorphicRequest,
+          await normalizeFetchResponse(cloneResponse)
+        )
+        return response
+      })
+    }
+
+    this.subscriptions.push(() => {
+      globalThis.fetch = pureFetch
+      this.log('restored native "globalThis.fetch"!', globalThis.fetch.name)
+    })
   }
 }
 

package/src/presets/browser.ts

@@ -1,8 +1,8 @@
-import { interceptXMLHttpRequest } from '../interceptors/XMLHttpRequest'
-import { interceptFetch } from '../interceptors/fetch'
+import { FetchInterceptor } from '../interceptors/fetch'
+import { XMLHttpRequestInterceptor } from '../interceptors/XMLHttpRequest'
 
 /**
  * The default preset provisions the interception of requests
  * regardless of their type (fetch/XMLHttpRequest).
  */
-export default [interceptXMLHttpRequest, interceptFetch]
+export default [new FetchInterceptor(), new XMLHttpRequestInterceptor()]

package/src/presets/node.ts

@@ -1,8 +1,8 @@
-import { interceptClientRequest } from '../interceptors/ClientRequest'
-import { interceptXMLHttpRequest } from '../interceptors/XMLHttpRequest'
+import { ClientRequestInterceptor } from '../interceptors/ClientRequest'
+import { XMLHttpRequestInterceptor } from '../interceptors/XMLHttpRequest'
 
 /**
  * The default preset provisions the interception of requests
  * regardless of their type (http/https/XMLHttpRequest).
  */
-export default [interceptClientRequest, interceptXMLHttpRequest]
+export default [new ClientRequestInterceptor(), new XMLHttpRequestInterceptor()]

package/src/utils/AsyncEventEmitter.test.ts

@@ -0,0 +1,68 @@
+import { AsyncEventEmitter } from './AsyncEventEmitter'
+import { sleep } from '../../test/helpers'
+
+it('emits and listens to events', () => {
+  const emitter = new AsyncEventEmitter<{ hello(name: string): void }>()
+  const listener = jest.fn()
+  emitter.on('hello', listener)
+  emitter.emit('hello', 'John')
+
+  expect(listener).toHaveBeenCalledTimes(1)
+  expect(listener).toHaveBeenCalledWith('John')
+})
+
+it('resolves "untilIdle" when all the event listeners are done', async () => {
+  const emitter = new AsyncEventEmitter<{ speak(word: string): void }>()
+
+  const results: string[] = []
+  const firstListener = jest.fn(() => results.push('first'))
+  emitter.on('speak', firstListener)
+
+  const secondListener = jest.fn(async () => {
+    await sleep(150)
+    results.push('second')
+  })
+  emitter.on('speak', secondListener)
+
+  emitter.emit('speak', 'hi')
+  await emitter.untilIdle('speak')
+
+  // All listeners must be called.
+  expect(firstListener).toHaveBeenCalledTimes(1)
+  expect(secondListener).toHaveBeenCalledTimes(1)
+
+  // All promise listeners must be awaited.
+  expect(results).toEqual(['first', 'second'])
+})
+
+it('resolves "untilIdle" immediately if there are no pending listeners', async () => {
+  const emitter = new AsyncEventEmitter<{ ping(): void }>()
+  emitter.emit('ping')
+
+  await expect(emitter.untilIdle('ping')).resolves.toBeUndefined()
+})
+
+it('propagates listener exceptions to "untilIdle" promise', async () => {
+  const emitter = new AsyncEventEmitter<{ ping(): void }>()
+
+  const error = new Error('oops')
+  const listener = jest.fn(() => {
+    throw error
+  })
+  emitter.on('ping', listener)
+
+  emitter.emit('ping')
+  await expect(emitter.untilIdle('ping')).rejects.toBe(error)
+})
+
+it('does not emit events once the emitter was deactivated', () => {
+  const emitter = new AsyncEventEmitter<{ ping(): void }>()
+
+  const listener = jest.fn()
+  emitter.on('ping', listener)
+  emitter.deactivate()
+
+  emitter.emit('ping')
+
+  expect(listener).not.toHaveBeenCalled()
+})

package/src/utils/AsyncEventEmitter.ts

@@ -0,0 +1,171 @@
+import { Debugger, debug } from 'debug'
+import { StrictEventEmitter, EventMapType } from 'strict-event-emitter'
+import { nextTick } from './nextTick'
+
+export type QueueItem = Promise<void>
+
+export enum AsyncEventEmitterReadyState {
+  ACTIVE = 'ACTIVE',
+  DEACTIVATED = 'DEACTIVATED',
+}
+
+export class AsyncEventEmitter<
+  EventMap extends EventMapType
+> extends StrictEventEmitter<EventMap> {
+  public readyState: AsyncEventEmitterReadyState
+
+  private log: Debugger
+  protected queue: Map<keyof EventMap, QueueItem[]>
+
+  constructor() {
+    super()
+
+    this.log = debug('async-event-emitter')
+    this.queue = new Map()
+
+    this.readyState = AsyncEventEmitterReadyState.ACTIVE
+  }
+
+  public on<Event extends keyof EventMap>(
+    event: Event,
+    listener: EventMap[Event]
+  ) {
+    const log = this.log.extend('on')
+
+    log('adding "%s" listener...', event)
+
+    if (this.readyState === AsyncEventEmitterReadyState.DEACTIVATED) {
+      log('the emitter is destroyed, skipping!')
+      return this
+    }
+
+    return super.on(event, (async (...args: unknown[]) => {
+      // Event queue is always established when calling ".emit()".
+      const queue = this.openListenerQueue(event)
+
+      log('awaiting the "%s" listener...', event)
+
+      // Whenever a listener is called, create a new Promise
+      // that resolves when that listener function completes its execution.
+      queue.push(
+        new Promise<void>(async (resolve, reject) => {
+          try {
+            // Treat listeners as potentially asynchronous functions
+            // so they could be awaited.
+            await listener(...args)
+            resolve()
+
+            log('"%s" listener has resolved!', event)
+          } catch (error) {
+            log('"%s" listener has rejected!', error)
+            reject(error)
+          }
+        })
+      )
+    }) as EventMap[Event])
+  }
+
+  public emit<Event extends keyof EventMap>(
+    event: Event,
+    ...args: Parameters<EventMap[Event]>
+  ): boolean {
+    const log = this.log.extend('emit')
+
+    log('emitting "%s" event...', event)
+
+    if (this.readyState === AsyncEventEmitterReadyState.DEACTIVATED) {
+      log('the emitter is destroyed, skipping!')
+      return false
+    }
+
+    // Establish the Promise queue for this particular event.
+    this.openListenerQueue(event)
+
+    log('appending a one-time cleanup "%s" listener...', event)
+
+    // Append a one-time clean up listener.
+    this.once(event, (() => {
+      // Clear the Promise queue for this particular event
+      // in the next tick so the Promise in "untilIdle" has
+      // time to properly resolve.
+      nextTick(() => {
+        this.queue.delete(event)
+        log('cleaned up "%s" listeners queue!', event)
+      })
+    }) as EventMap[Event])
+
+    return super.emit(event, ...args)
+  }
+
+  /**
+   * 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.
+   */
+  public async untilIdle<Event extends keyof EventMap>(
+    event: Event
+  ): Promise<void> {
+    const listenersQueue = this.queue.get(event) || []
+    await Promise.all(listenersQueue).finally(() => {
+      // Clear the queue one the promise settles
+      // so that different events don't share the same queue.
+      this.queue.delete(event)
+    })
+  }
+
+  private openListenerQueue<Event extends keyof EventMap>(
+    event: Event
+  ): QueueItem[] {
+    const log = this.log.extend('openListenerQueue')
+
+    log('opening "%s" listeners queue...', event)
+
+    const queue = this.queue.get(event)
+
+    if (!queue) {
+      log('no queue found, creating one...')
+
+      this.queue.set(event, [])
+      return []
+    }
+
+    log('returning an exising queue:', queue)
+    return queue
+  }
+
+  public removeAllListeners<Event extends keyof EventMap>(event?: Event) {
+    const log = this.log.extend('removeAllListeners')
+    log('event:', event)
+
+    if (event) {
+      this.queue.delete(event)
+      log('cleared the "%s" listeners queue!', event, this.queue.get(event))
+    } else {
+      this.queue.clear()
+      log('cleared the listeners queue!', this.queue)
+    }
+
+    return super.removeAllListeners(event)
+  }
+
+  public activate(): void {
+    const log = this.log.extend('activate')
+    this.readyState = AsyncEventEmitterReadyState.ACTIVE
+    log('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.
+   */
+  public deactivate(): void {
+    const log = this.log.extend('deactivate')
+
+    log('removing all listeners...')
+    this.removeAllListeners()
+
+    this.readyState = AsyncEventEmitterReadyState.DEACTIVATED
+    log('set state to:', this.readyState)
+  }
+}

package/src/utils/createLazyCallback.ts

@@ -0,0 +1,49 @@
+export type AnyFunction = (...args: any[]) => any
+
+export type LazyCallbackReturnType<FnType extends AnyFunction> =
+  | Parameters<FnType>
+  | []
+
+export interface LazyCallback<FnType extends AnyFunction> {
+  (...args: Parameters<FnType>): void
+  invoked(): Promise<LazyCallbackReturnType<FnType>>
+}
+
+export interface LazyCallbackOptions {
+  maxCalls?: number
+  maxCallsCallback?(): void
+}
+
+export function createLazyCallback<FnType extends AnyFunction>(
+  options: LazyCallbackOptions = {}
+): LazyCallback<FnType> {
+  let calledTimes = 0
+  let autoResolveTimeout: NodeJS.Timeout
+  let remoteResolve: (args: LazyCallbackReturnType<FnType>) => unknown
+
+  const callPromise = new Promise<LazyCallbackReturnType<FnType>>((resolve) => {
+    remoteResolve = resolve
+  }).finally(() => {
+    clearTimeout(autoResolveTimeout)
+  })
+
+  const fn: LazyCallback<FnType> = function (...args) {
+    if (options.maxCalls && calledTimes >= options.maxCalls) {
+      options.maxCallsCallback?.()
+    }
+
+    remoteResolve(args)
+    calledTimes++
+  }
+
+  fn.invoked = async () => {
+    // Immediately resolve the callback if it hasn't been called already.
+    autoResolveTimeout = setTimeout(() => {
+      remoteResolve([])
+    }, 0)
+
+    return callPromise
+  }
+
+  return fn
+}

package/src/utils/nextTick.ts

@@ -0,0 +1,11 @@
+export function nextTick(callback: () => void) {
+  setTimeout(callback, 0)
+}
+
+export function nextTickAsync(callback: () => void) {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(callback())
+    }, 0)
+  })
+}

package/src/utils/toIsoResponse.ts

@@ -1,5 +1,5 @@
 import { objectToHeaders } from 'headers-polyfill'
-import { IsomorphicResponse, MockedResponse } from '../createInterceptor'
+import { IsomorphicResponse, MockedResponse } from '../glossary'
 
 /**
  * Converts a given mocked response object into an isomorphic response.

package/lib/createInterceptor.d.ts

@@ -1,54 +0,0 @@
-/// <reference types="node" />
-import { IncomingMessage } from 'http';
-import { HeadersObject, Headers } from 'headers-polyfill';
-import { StrictEventEmitter } from 'strict-event-emitter';
-export declare type Interceptor = (observer: Observer, resolver: Resolver) => InterceptorCleanupFn;
-export declare type Observer = StrictEventEmitter<InterceptorEventsMap>;
-/**
- * A side-effect function to restore all the patched modules.
- */
-export declare type InterceptorCleanupFn = () => void;
-export declare type RequestCredentials = 'omit' | 'include' | 'same-origin';
-export interface IsomorphicRequest {
-    id: string;
-    url: URL;
-    method: string;
-    headers: Headers;
-    /**
-     * The value of the request client's "credentials" option
-     * or a compatible alternative (i.e. `withCredentials` for `XMLHttpRequest`).
-     * Always equals to "omit" in Node.js.
-     */
-    credentials: RequestCredentials;
-    body?: string;
-}
-export interface IsomorphicResponse {
-    status: number;
-    statusText: string;
-    headers: Headers;
-    body?: string;
-}
-export interface MockedResponse extends Omit<Partial<IsomorphicResponse>, 'headers'> {
-    headers?: HeadersObject;
-}
-export interface InterceptorEventsMap {
-    request(request: IsomorphicRequest): void;
-    response(request: IsomorphicRequest, response: IsomorphicResponse): void;
-}
-export declare type Resolver = (request: IsomorphicRequest, ref: IncomingMessage | XMLHttpRequest | Request) => MockedResponse | Promise<MockedResponse | void> | void;
-export interface InterceptorOptions {
-    modules: Interceptor[];
-    resolver: Resolver;
-}
-export interface InterceptorApi {
-    /**
-     * Apply necessary module patches to provision the interception of requests.
-     */
-    apply(): void;
-    on<Event extends keyof InterceptorEventsMap>(event: Event, listener: InterceptorEventsMap[Event]): void;
-    /**
-     * Restore all applied module patches and disable the interception.
-     */
-    restore(): void;
-}
-export declare function createInterceptor(options: InterceptorOptions): InterceptorApi;

package/lib/createInterceptor.js

@@ -1,27 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createInterceptor = void 0;
-var strict_event_emitter_1 = require("strict-event-emitter");
-function createInterceptor(options) {
-    var observer = new strict_event_emitter_1.StrictEventEmitter();
-    var cleanupFns = [];
-    return {
-        apply: function () {
-            cleanupFns = options.modules.map(function (interceptor) {
-                return interceptor(observer, options.resolver);
-            });
-        },
-        on: function (event, listener) {
-            observer.addListener(event, listener);
-        },
-        restore: function () {
-            observer.removeAllListeners();
-            if (cleanupFns.length === 0) {
-                throw new Error("Failed to restore patched modules: no patches found. Did you forget to run \".apply()\"?");
-            }
-            cleanupFns.forEach(function (restore) { return restore(); });
-        },
-    };
-}
-exports.createInterceptor = createInterceptor;
-//# sourceMappingURL=createInterceptor.js.map

package/lib/createInterceptor.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"createInterceptor.js","sourceRoot":"","sources":["../src/createInterceptor.ts"],"names":[],"mappings":";;;AAEA,6DAAyD;AAwEzD,SAAgB,iBAAiB,CAAC,OAA2B;IAC3D,IAAM,QAAQ,GAAG,IAAI,yCAAkB,EAAwB,CAAA;IAC/D,IAAI,UAAU,GAA2B,EAAE,CAAA;IAE3C,OAAO;QACL,KAAK;YACH,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAC,WAAW;gBAC3C,OAAO,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;YAChD,CAAC,CAAC,CAAA;QACJ,CAAC;QACD,EAAE,YAAC,KAAK,EAAE,QAAQ;YAChB,QAAQ,CAAC,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;QACvC,CAAC;QACD,OAAO;YACL,QAAQ,CAAC,kBAAkB,EAAE,CAAA;YAE7B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE;gBAC3B,MAAM,IAAI,KAAK,CACb,0FAAwF,CACzF,CAAA;aACF;YAED,UAAU,CAAC,OAAO,CAAC,UAAC,OAAO,IAAK,OAAA,OAAO,EAAE,EAAT,CAAS,CAAC,CAAA;QAC5C,CAAC;KACF,CAAA;AACH,CAAC;AAzBD,8CAyBC"}

package/lib/remote.d.ts

@@ -1,21 +0,0 @@
-/// <reference types="node" />
-import { ChildProcess } from 'child_process';
-import { InterceptorApi, InterceptorOptions, Resolver } from './createInterceptor';
-export declare type CreateRemoteInterceptorOptions = Omit<InterceptorOptions, 'resolver'>;
-export declare type RemoteResolverApi = Pick<InterceptorApi, 'on'>;
-export interface CreateRemoteResolverOptions {
-    process: ChildProcess;
-    resolver: Resolver;
-}
-/**
- * Creates a remote request interceptor that delegates
- * the mocked response resolution to the parent process.
- * The parent process must establish a remote resolver
- * by calling `createRemoteResolver` function.
- */
-export declare function createRemoteInterceptor(options: CreateRemoteInterceptorOptions): InterceptorApi;
-/**
- * Creates a response resolver function attached to the given `ChildProcess`.
- * The child process must establish a remote interceptor by calling `createRemoteInterceptor` function.
- */
-export declare function createRemoteResolver(options: CreateRemoteResolverOptions): RemoteResolverApi;