@mswjs/interceptors 0.41.9 → 0.42.0

package/src/{createRequestId.test.ts → create-request-id.test.ts}

@@ -1,5 +1,4 @@
-import { it, expect } from 'vitest'
-import { createRequestId } from './createRequestId'
+import { createRequestId } from './create-request-id'
 import { REQUEST_ID_REGEXP } from '../test/helpers'
 
 it('returns a request ID', () => {

package/src/disposable.ts

@@ -0,0 +1,13 @@
+export type DisposableSubscription = () => void
+
+export class Disposable {
+  protected subscriptions: Array<DisposableSubscription> = []
+
+  public dispose() {
+    let subscription: DisposableSubscription | undefined
+
+    while ((subscription = this.subscriptions.pop())) {
+      subscription()
+    }
+  }
+}

package/src/events/http.ts

@@ -0,0 +1,92 @@
+import { TypedEvent } from 'rettime'
+import type { RequestController } from '../request-controller'
+
+export interface HttpRequestEventData {
+  request: Request
+  requestId: string
+  initiator: unknown
+  controller: RequestController
+}
+
+export class HttpRequestEvent<
+  DataType extends HttpRequestEventData = HttpRequestEventData,
+> extends TypedEvent<DataType, void, 'request'> {
+  public request: Request
+  public requestId: string
+  public initiator: unknown
+  public controller: RequestController
+
+  constructor(data: DataType) {
+    super(...(['request', {}] as any))
+
+    this.request = data.request
+    this.requestId = data.requestId
+    this.initiator = data.initiator
+    this.controller = data.controller
+  }
+}
+
+export type HttpResponseType = 'mock' | 'original'
+
+interface HttpResponseEventData {
+  response: Response
+  responseType: HttpResponseType
+  request: Request
+  requestId: string
+  initiator: unknown
+}
+
+export class HttpResponseEvent<
+  DataType extends HttpResponseEventData = HttpResponseEventData,
+> extends TypedEvent<DataType, void, 'response'> {
+  public response: Response
+  public responseType: HttpResponseType
+  public request: Request
+  public requestId: string
+  public initiator: unknown
+
+  constructor(data: DataType) {
+    super(...(['response', {}] as any))
+
+    this.response = data.response
+    this.responseType = data.responseType
+    this.request = data.request
+    this.requestId = data.requestId
+    this.initiator = data.initiator
+  }
+}
+
+interface UnhandledHttpExceptionEventData {
+  error: unknown
+  request: Request
+  requestId: string
+  initiator: unknown
+  controller: RequestController
+}
+
+export class UnhandledHttpException<
+  DataType extends UnhandledHttpExceptionEventData =
+    UnhandledHttpExceptionEventData,
+> extends TypedEvent<DataType, void, 'unhandledException'> {
+  public error: unknown
+  public request: Request
+  public requestId: string
+  public initiator: unknown
+  public controller: RequestController
+
+  constructor(data: DataType) {
+    super(...(['unhandledException', {}] as any))
+
+    this.error = data.error
+    this.request = data.request
+    this.requestId = data.requestId
+    this.initiator = data.initiator
+    this.controller = data.controller
+  }
+}
+
+export type HttpRequestEventMap = {
+  request: HttpRequestEvent
+  response: HttpResponseEvent
+  unhandledException: UnhandledHttpException
+}

package/src/events/websocket.ts

@@ -0,0 +1,47 @@
+import { TypedEvent } from 'rettime'
+import type {
+  WebSocketClientConnection,
+  WebSocketServerConnection,
+} from '../interceptors/WebSocket'
+
+/**
+ * The connection information.
+ */
+interface WebSocketConnectionInfo {
+  /**
+   * The protocols supported by the WebSocket client.
+   */
+  protocols: string | Array<string> | undefined
+}
+
+interface WebSocketConnectionEventData {
+  /**
+   * The incoming WebSocket client connection.
+   */
+  client: WebSocketClientConnection
+  /**
+   * The original WebSocket server connection.
+   */
+  server: WebSocketServerConnection
+  info: WebSocketConnectionInfo
+}
+
+export class WebSocketConnectionEvent<
+  DataType extends WebSocketConnectionEventData = WebSocketConnectionEventData,
+> extends TypedEvent<DataType, void, 'connection'> {
+  public client: WebSocketClientConnection
+  public server: WebSocketServerConnection
+  public info: WebSocketConnectionInfo
+
+  constructor(data: DataType) {
+    super(...(['connection', {}] as any))
+
+    this.client = data.client
+    this.server = data.server
+    this.info = data.info
+  }
+}
+
+export type WebSocketEventMap = {
+  connection: WebSocketConnectionEvent
+}

package/src/glossary.ts

@@ -1,4 +1,4 @@
-import type { RequestController } from './RequestController'
+import type { RequestController } from './request-controller'
 
 /**
  * @note Export `RequestController` as a type only.
@@ -7,29 +7,3 @@ import type { RequestController } from './RequestController'
 export type { RequestController }
 
 export type RequestCredentials = 'omit' | 'include' | 'same-origin'
-
-export type HttpRequestEventMap = {
-  request: [
-    args: {
-      request: Request
-      requestId: string
-      controller: RequestController
-    },
-  ]
-  response: [
-    args: {
-      response: Response
-      isMockedResponse: boolean
-      request: Request
-      requestId: string
-    },
-  ]
-  unhandledException: [
-    args: {
-      error: unknown
-      request: Request
-      requestId: string
-      controller: RequestController
-    },
-  ]
-}

package/src/index.ts

@@ -1,15 +1,23 @@
-export * from './glossary'
-export * from './Interceptor'
-export * from './BatchInterceptor'
+export { Interceptor } from './interceptor'
+export { BatchInterceptor } from './batch-interceptor'
+export { InterceptorError } from './interceptor-error'
 export {
   RequestController,
   type RequestControllerSource,
-} from './RequestController'
+} from './request-controller'
+export type {
+  HttpRequestEventMap,
+  HttpRequestEvent,
+  HttpResponseEvent,
+} from './events/http'
+export type {
+  WebSocketEventMap,
+  WebSocketConnectionEvent,
+} from './events/websocket'
 
 /* Utils */
-export { createRequestId } from './createRequestId'
-export { getCleanUrl } from './utils/getCleanUrl'
-export { encodeBuffer, decodeBuffer } from './utils/bufferUtils'
-export { FetchRequest, FetchResponse } from './utils/fetchUtils'
-export { getRawRequest } from './getRawRequest'
-export { resolveWebSocketUrl } from './utils/resolveWebSocketUrl'
+export { createRequestId } from './create-request-id'
+export { getCleanUrl } from './utils/get-clean-url'
+export { encodeBuffer, decodeBuffer } from './utils/buffer-utils'
+export { FetchRequest, FetchResponse } from './utils/fetch-utils'
+export { resolveWebSocketUrl } from './utils/resolve-web-socket-url'

package/src/interceptor.test.ts

@@ -0,0 +1,279 @@
+import { TypedEvent } from 'rettime'
+import { Interceptor, InterceptorReadyState } from './interceptor'
+
+it('nesting interceptors', async () => {
+  const socketSetup = vi.fn()
+  const protocolSetup = vi.fn()
+
+  class SocketInterceptor extends Interceptor<{
+    data: TypedEvent<string | number>
+  }> {
+    static symbol = Symbol.for('socket-interceptor')
+
+    protected predicate(): boolean {
+      return true
+    }
+
+    protected setup(): void {
+      socketSetup()
+
+      queueMicrotask(() => {
+        this.emitter.emit(new TypedEvent('data', { data: 1 }))
+        this.emitter.emit(new TypedEvent('data', { data: 'hello' }))
+        this.emitter.emit(new TypedEvent('data', { data: 2 }))
+      })
+    }
+  }
+
+  class ProtocolInterceptor extends Interceptor<{
+    request: TypedEvent<string | number>
+  }> {
+    static symbol = Symbol.for('protocol-interceptor')
+
+    protected predicate(): boolean {
+      return true
+    }
+
+    protected setup(): void {
+      protocolSetup()
+
+      const socket = Interceptor.singleton(SocketInterceptor)
+      socket.apply(this)
+      this.subscriptions.push(() => {
+        socket.dispose(this)
+      })
+
+      const controller = new AbortController()
+      this.subscriptions.push(() => controller.abort())
+
+      socket.on(
+        'data',
+        ({ data }) => {
+          this.emitter.emit(new TypedEvent('request', { data }))
+        },
+        { signal: controller.signal }
+      )
+    }
+  }
+
+  class NumberInterceptor extends Interceptor<{
+    number: TypedEvent<number>
+  }> {
+    static symbol = Symbol.for('number-interceptor')
+
+    protected predicate(): boolean {
+      return true
+    }
+
+    protected setup(): void {
+      const protocol = Interceptor.singleton(ProtocolInterceptor)
+      protocol.apply(this)
+      this.subscriptions.push(() => {
+        protocol.dispose(this)
+      })
+
+      const controller = new AbortController()
+      this.subscriptions.push(() => controller.abort())
+
+      protocol.on(
+        'request',
+        ({ data }) => {
+          if (typeof data === 'number') {
+            this.emitter.emit(new TypedEvent('number', { data }))
+          }
+        },
+        { signal: controller.signal }
+      )
+    }
+  }
+
+  class StringInterceptor extends Interceptor<{
+    string: TypedEvent<string>
+  }> {
+    static symbol = Symbol.for('string-interceptor')
+
+    protected predicate(): boolean {
+      return true
+    }
+
+    protected setup(): void {
+      const protocol = Interceptor.singleton(ProtocolInterceptor)
+      protocol.apply(this)
+      this.subscriptions.push(() => {
+        protocol.dispose(this)
+      })
+
+      const controller = new AbortController()
+      this.subscriptions.push(() => controller.abort())
+
+      protocol.on(
+        'request',
+        ({ data }) => {
+          if (typeof data === 'string') {
+            this.emitter.emit(new TypedEvent('string', { data }))
+          }
+        },
+        { signal: controller.signal }
+      )
+    }
+  }
+
+  const numberListener = vi.fn()
+  const numberInterceptor = new NumberInterceptor()
+  numberInterceptor.on('number', ({ data }) => numberListener(data))
+  numberInterceptor.apply()
+
+  const stringListener = vi.fn()
+  const stringInterceptor = new StringInterceptor()
+  stringInterceptor.on('string', ({ data }) => stringListener(data))
+  stringInterceptor.apply()
+
+  expect(socketSetup).toHaveBeenCalledOnce()
+  expect(protocolSetup).toHaveBeenCalledOnce()
+
+  await expect.poll(() => numberListener).toHaveBeenCalledTimes(2)
+
+  const protocolInterceptor = Interceptor.singleton(ProtocolInterceptor)
+
+  numberInterceptor.dispose()
+  expect(protocolInterceptor.readyState).toBe(InterceptorReadyState.ACTIVE)
+
+  stringInterceptor.dispose()
+  expect(protocolInterceptor.readyState).toBe(InterceptorReadyState.DISPOSED)
+
+  expect(numberListener).toHaveBeenNthCalledWith(1, 1)
+  expect(numberListener).toHaveBeenNthCalledWith(2, 2)
+  expect(stringListener).toHaveBeenCalledExactlyOnceWith('hello')
+})
+
+it('treats an interceptor as a singleton via "Interceptor.singleton()"', () => {
+  const setup = vi.fn()
+  const dispose = vi.fn()
+
+  class MyInterceptor extends Interceptor<{ test: TypedEvent }> {
+    protected predicate(): boolean {
+      return true
+    }
+
+    protected setup(): void {
+      setup()
+    }
+
+    public dispose(): void {
+      super.dispose()
+      dispose()
+    }
+  }
+
+  const interceptor = Interceptor.singleton(MyInterceptor)
+  expect(setup).not.toHaveBeenCalled()
+
+  interceptor.apply()
+  expect(setup).toHaveBeenCalledOnce()
+
+  {
+    const interceptor = Interceptor.singleton(MyInterceptor)
+    expect(setup).toHaveBeenCalledOnce()
+
+    interceptor.dispose()
+    expect(dispose).toHaveBeenCalledOnce()
+  }
+
+  interceptor.dispose()
+  expect(dispose).toHaveBeenCalledTimes(2)
+})
+
+it('keeps an interceptor active until all owners dispose', () => {
+  const setup = vi.fn()
+  const teardown = vi.fn()
+
+  class MyInterceptor extends Interceptor<{}> {
+    protected predicate(): boolean {
+      return true
+    }
+
+    protected setup(): void {
+      setup()
+      this.subscriptions.push(teardown)
+    }
+  }
+
+  const interceptor = new MyInterceptor()
+  const primaryOwner = {}
+  const secondaryOwner = {}
+
+  interceptor.apply(primaryOwner)
+  interceptor.apply(primaryOwner)
+  interceptor.apply(secondaryOwner)
+
+  expect(setup).toHaveBeenCalledOnce()
+
+  interceptor.dispose(primaryOwner)
+
+  expect(interceptor.readyState).toBe(InterceptorReadyState.ACTIVE)
+  expect(teardown).not.toHaveBeenCalled()
+
+  interceptor.dispose(secondaryOwner)
+
+  expect(interceptor.readyState).toBe(InterceptorReadyState.DISPOSED)
+  expect(teardown).toHaveBeenCalledOnce()
+})
+
+it('treats repeated public application as one ownership lease', () => {
+  class MyInterceptor extends Interceptor<{}> {
+    protected predicate(): boolean {
+      return true
+    }
+
+    protected setup(): void {}
+  }
+
+  const interceptor = new MyInterceptor()
+
+  interceptor.apply()
+  interceptor.apply()
+  interceptor.dispose()
+
+  expect(interceptor.readyState).toBe(InterceptorReadyState.DISPOSED)
+})
+
+it('removes all listeners when the interceptor is disposed', () => {
+  class MyInterceptor extends Interceptor<{ test: TypedEvent }> {
+    protected predicate(): boolean {
+      return true
+    }
+
+    protected setup(): void {}
+  }
+
+  const interceptor = new MyInterceptor()
+  interceptor.apply()
+
+  const listener = vi.fn()
+  interceptor.on('test', listener)
+
+  interceptor.dispose()
+
+  interceptor['emitter'].emit(new TypedEvent('test'))
+  expect(listener).not.toHaveBeenCalled()
+})
+
+it('applies the interceptor after disposal', () => {
+  class MyInterceptor extends Interceptor<{}> {
+    protected predicate(): boolean {
+      return true
+    }
+
+    protected setup(): void {}
+  }
+  const interceptor = new MyInterceptor()
+
+  interceptor.apply()
+  expect(interceptor.readyState).toBe(InterceptorReadyState.ACTIVE)
+
+  interceptor.dispose()
+  expect(interceptor.readyState).toBe(InterceptorReadyState.DISPOSED)
+
+  interceptor.apply()
+  expect(interceptor.readyState).toBe(InterceptorReadyState.ACTIVE)
+})

package/src/interceptor.ts

@@ -0,0 +1,139 @@
+import { Emitter, type DefaultEventMap } from 'rettime'
+import { Disposable } from './disposable'
+import { createLogger, type Logger } from './utils/logger'
+
+export enum InterceptorReadyState {
+  INACTIVE = 'INACTIVE',
+  ACTIVE = 'ACTIVE',
+  DISPOSED = 'DISPOSED',
+}
+
+declare global {
+  var __MSW_INTERCEPTORS_REGISTRY: Map<symbol, Interceptor<any>> | undefined
+}
+
+const interceptorsRegistry = (globalThis.__MSW_INTERCEPTORS_REGISTRY ??=
+  new Map<symbol, Interceptor<any>>())
+
+export abstract class Interceptor<
+  Events extends DefaultEventMap,
+> extends Disposable {
+  declare ['constructor']: typeof Interceptor
+
+  protected emitter: Emitter<Events>
+  protected readonly logger: Logger
+
+  public readyState: InterceptorReadyState
+
+  static readonly symbol: symbol
+
+  #owners: Set<object>
+
+  static singleton<T extends Interceptor<any>>(
+    InterceptorClass: (new () => T) & { symbol: symbol }
+  ): T {
+    const symbol = InterceptorClass.symbol
+    const existing = interceptorsRegistry.get(symbol)
+
+    if (existing instanceof InterceptorClass) {
+      return existing
+    }
+
+    const newInstance = new InterceptorClass()
+    interceptorsRegistry.set(symbol, newInstance)
+    return newInstance
+  }
+
+  constructor() {
+    super()
+
+    this.#owners = new Set()
+    this.readyState = InterceptorReadyState.INACTIVE
+    this.emitter = new Emitter()
+    this.logger = createLogger(this.#getLoggerNamespace())
+  }
+
+  protected abstract predicate(): boolean
+  protected abstract setup(): void
+
+  public apply(owner: object = this): void {
+    if (this.#owners.has(owner)) {
+      return
+    }
+
+    if (
+      this.readyState !== InterceptorReadyState.ACTIVE &&
+      !this.predicate()
+    ) {
+      return
+    }
+
+    this.#owners.add(owner)
+
+    if (this.readyState === InterceptorReadyState.ACTIVE) {
+      return
+    }
+
+    try {
+      this.setup()
+      this.readyState = InterceptorReadyState.ACTIVE
+      this.logger.info('apply')
+    } catch (error) {
+      this.dispose(owner)
+      throw error
+    }
+  }
+
+  public dispose(owner: object = this): void {
+    if (!this.#owners.delete(owner)) {
+      return
+    }
+
+    if (this.#owners.size > 0) {
+      return
+    }
+
+    super.dispose()
+    this.emitter.removeAllListeners()
+    this.readyState = InterceptorReadyState.DISPOSED
+    this.logger.info('disable')
+  }
+
+  public on: Emitter<Events>['on'] = (type, listener, options) => {
+    return this.emitter.on(type, listener, options)
+  }
+
+  public once: Emitter<Events>['once'] = (type, listener, options) => {
+    return this.emitter.once(type, listener, options)
+  }
+
+  public listeners: Emitter<Events>['listeners'] = (type) => {
+    return this.emitter.listeners(type)
+  }
+
+  public listenerCount: Emitter<Events>['listenerCount'] = (type) => {
+    return this.emitter.listenerCount(type)
+  }
+
+  public removeListener: Emitter<Events>['removeListener'] = (
+    type,
+    listener
+  ) => {
+    return this.emitter.removeListener(type, listener)
+  }
+
+  public removeAllListeners: Emitter<Events>['removeAllListeners'] = (type) => {
+    this.logger.info('removeAllListeners %o', { eventType: type ?? '*' })
+    return this.emitter.removeAllListeners(type)
+  }
+
+  #getLoggerNamespace(): string {
+    const symbolDescription = this.constructor.symbol?.description
+
+    if (symbolDescription) {
+      return symbolDescription.replace(/-interceptor$/, '')
+    }
+
+    return this.constructor.name.replace(/Interceptor$/, '')
+  }
+}