msw 2.13.3 → 2.13.4

package/src/browser/sources/service-worker-source.ts

@@ -1,5 +1,5 @@
 import { invariant } from 'outvariant'
-import { Emitter } from 'rettime'
+import type { Emitter } from 'rettime'
 import { DeferredPromise } from '@open-draft/deferred-promise'
 import { FetchResponse } from '@mswjs/interceptors'
 import { NetworkSource } from '#core/experimental/sources/network-source'
@@ -16,10 +16,12 @@ import {
   supportsServiceWorker,
 } from '../utils/supports'
 import { getWorkerInstance } from '../utils/get-worker-instance'
-import { WorkerChannel, WorkerChannelEventMap } from '../utils/workerChannel'
-import { FindWorker } from '../glossary'
+import type { WorkerChannelEventMap } from '../utils/workerChannel'
+import { WorkerChannel } from '../utils/workerChannel'
+import type { FindWorker } from '../glossary'
 import { deserializeRequest } from '../utils/deserializeRequest'
 import { validateWorkerScope } from '../utils/validate-worker-scope'
+import { shouldInvalidateWorker } from '../utils/should-invalidate-worker'
 
 export interface ServiceWorkerSourceOptions {
   quiet?: boolean
@@ -30,13 +32,13 @@ export interface ServiceWorkerSourceOptions {
   findWorker?: FindWorker
 }
 
-type WorkerChannelRequestEvent = Emitter.EventType<
+type WorkerChannelRequestEvent = Emitter.Event<
   WorkerChannel,
   'REQUEST',
   WorkerChannelEventMap
 >
 
-type WorkerChannelResponseEvent = Emitter.EventType<
+type WorkerChannelResponseEvent = Emitter.Event<
   WorkerChannel,
   'RESPONSE',
   WorkerChannelEventMap
@@ -46,8 +48,31 @@ type WorkerChannelClient =
   WorkerChannelEventMap['MOCKING_ENABLED']['data']['client']
 
 export class ServiceWorkerSource extends NetworkSource<ServiceWorkerHttpNetworkFrame> {
+  static #current?: ServiceWorkerSource
+
+  /**
+   * Create a new Service Worker source or reuse an existing one.
+   * These sources act as a singleton and only get recreated if the options change.
+   */
+  public static async from(
+    options: ServiceWorkerSourceOptions,
+  ): Promise<ServiceWorkerSource> {
+    if (ServiceWorkerSource.#current == null) {
+      ServiceWorkerSource.#current = new ServiceWorkerSource(options)
+    } else if (
+      shouldInvalidateWorker(ServiceWorkerSource.#current.#options, options)
+    ) {
+      await ServiceWorkerSource.#current.terminate()
+      ServiceWorkerSource.#current = new ServiceWorkerSource(options)
+    }
+
+    return ServiceWorkerSource.#current
+  }
+
+  #options: ServiceWorkerSourceOptions
   #frames: Map<string, ServiceWorkerHttpNetworkFrame>
   #channel: WorkerChannel
+  #listenerController?: AbortController
   #clientPromise?: Promise<WorkerChannelClient>
   #keepAliveInterval?: number
   #stoppedAt?: number
@@ -56,7 +81,7 @@ export class ServiceWorkerSource extends NetworkSource<ServiceWorkerHttpNetworkF
     [ServiceWorker, ServiceWorkerRegistration]
   >
 
-  constructor(private readonly options: ServiceWorkerSourceOptions) {
+  constructor(options: ServiceWorkerSourceOptions) {
     super()
 
     invariant(
@@ -64,17 +89,25 @@ export class ServiceWorkerSource extends NetworkSource<ServiceWorkerHttpNetworkF
       'Failed to use Service Worker as the network source: the Service Worker API is not supported in this environment',
     )
 
+    this.#options = options
     this.#frames = new Map()
     this.workerPromise = new DeferredPromise()
     this.#channel = new WorkerChannel({
-      worker: this.workerPromise.then(([worker]) => worker),
+      getWorker: () => this.workerPromise.then(([worker]) => worker),
     })
   }
 
   public async enable(): Promise<ServiceWorkerRegistration> {
-    this.#stoppedAt = undefined
-
-    if (this.workerPromise.state !== 'pending') {
+    /**
+     * @note The source is considered already running if the worker has been
+     * resolved AND `stop()` has not been called since. `workerPromise` is NOT
+     * reset on `disable()` so that the channel's `getWorker()` can keep
+     * resolving to the registered SW for post-stop passthrough replies.
+     */
+    if (
+      this.workerPromise.state === 'fulfilled' &&
+      typeof this.#stoppedAt == 'undefined'
+    ) {
       devUtils.warn(
         'Found a redundant "worker.start()" call. Note that starting the worker while mocking is already enabled will have no effect. Consider removing this "worker.start()" call.',
       )
@@ -82,7 +115,11 @@ export class ServiceWorkerSource extends NetworkSource<ServiceWorkerHttpNetworkF
       return this.workerPromise.then(([, registration]) => registration)
     }
 
+    this.#stoppedAt = undefined
     this.#channel.removeAllListeners()
+    this.#frames.clear()
+
+    this.#listenerController = new AbortController()
     const [worker, registration] = await this.#startWorker()
 
     if (worker.state !== 'activated') {
@@ -97,7 +134,9 @@ export class ServiceWorkerSource extends NetworkSource<ServiceWorkerHttpNetworkF
             activationPromise.resolve()
           }
         },
-        { signal: controller.signal },
+        {
+          signal: controller.signal,
+        },
       )
 
       await activationPromise
@@ -113,7 +152,7 @@ export class ServiceWorkerSource extends NetworkSource<ServiceWorkerHttpNetworkF
     })
     await clientConfirmationPromise
 
-    if (!this.options.quiet) {
+    if (!this.#options.quiet) {
       this.#printStartMessage()
     }
 
@@ -137,29 +176,70 @@ export class ServiceWorkerSource extends NetworkSource<ServiceWorkerHttpNetworkF
     }
 
     this.#stoppedAt = Date.now()
-    this.#frames.clear()
-    this.workerPromise = new DeferredPromise()
 
-    if (!this.options.quiet) {
+    this.#listenerController?.abort()
+    this.#listenerController = undefined
+
+    /**
+     * @note Tell the Service Worker to drop this client from its active set
+     * so it stops forwarding REQUEST events here. `stoppedAt` still guards
+     * any requests the SW already forwarded before this message arrived.
+     */
+    this.#channel.postMessage('CLIENT_CLOSED')
+
+    /**
+     * @note Do NOT reset `workerPromise` here. The channel must continue to
+     * resolve the currently registered SW so that any in-flight requests the
+     * worker forwards after `stop()` can be answered with `PASSTHROUGH` by
+     * `#handleRequest`. `#startWorker` swaps in a fresh deferred on re-enable.
+     */
+
+    if (!this.#options.quiet) {
       this.#printStopMessage()
     }
   }
 
+  /**
+   * Terminal teardown. Unregisters the Service Worker, tears down the channel,
+   * and clears timers. Called when the singleton is being replaced with one
+   * that has different options. The instance is not usable afterwards.
+   */
+  public async terminate(): Promise<void> {
+    if (this.#keepAliveInterval != null) {
+      clearInterval(this.#keepAliveInterval)
+      this.#keepAliveInterval = undefined
+    }
+
+    this.#frames.clear()
+    this.#channel.terminate()
+    this.#listenerController?.abort()
+    this.#listenerController = undefined
+
+    if (this.workerPromise.state === 'fulfilled') {
+      const [, registration] = await this.workerPromise
+      await registration.unregister()
+    }
+
+    if (ServiceWorkerSource.#current === this) {
+      ServiceWorkerSource.#current = undefined
+    }
+  }
+
   async #startWorker() {
     if (this.#keepAliveInterval) {
       clearInterval(this.#keepAliveInterval)
     }
 
-    const workerUrl = this.options.serviceWorker.url
+    const workerUrl = this.#options.serviceWorker.url
 
     const [worker, registration] = await getWorkerInstance(
       workerUrl,
-      this.options.serviceWorker.options,
-      this.options.findWorker || this.#defaultFindWorker,
+      this.#options.serviceWorker.options,
+      this.#options.findWorker || this.#defaultFindWorker,
     )
 
     if (worker == null) {
-      const missingWorkerMessage = this.options?.findWorker
+      const missingWorkerMessage = this.#options?.findWorker
         ? devUtils.formatMessage(
             `Failed to locate the Service Worker registration using a custom "findWorker" predicate.
 
@@ -181,20 +261,37 @@ Please consider using a custom "serviceWorker.url" option to point to the actual
       throw new Error(missingWorkerMessage)
     }
 
-    this.workerPromise.resolve([worker, registration])
+    if (this.workerPromise.state === 'pending') {
+      this.workerPromise.resolve([worker, registration])
+    } else {
+      /**
+       * @note Re-enable after `stop()`: the previous `workerPromise` is already
+       * fulfilled and cannot be resolved again. Swap in a pre-resolved one so
+       * `getWorker()` sees the new worker instance immediately.
+       */
+      this.workerPromise = new DeferredPromise((resolve) => {
+        resolve([worker, registration])
+      })
+    }
 
     this.#channel.on('REQUEST', this.#handleRequest.bind(this))
     this.#channel.on('RESPONSE', this.#handleResponse.bind(this))
 
-    window.addEventListener('beforeunload', () => {
-      if (worker.state !== 'redundant') {
-        this.#channel.postMessage('CLIENT_CLOSED')
-      }
+    window.addEventListener(
+      'beforeunload',
+      () => {
+        if (worker.state !== 'redundant') {
+          this.#channel.postMessage('CLIENT_CLOSED')
+        }
 
-      clearInterval(this.#keepAliveInterval)
+        clearInterval(this.#keepAliveInterval)
 
-      window.postMessage({ type: 'msw/worker:stop' })
-    })
+        window.postMessage({ type: 'msw/worker:stop' })
+      },
+      {
+        signal: this.#listenerController?.signal,
+      },
+    )
 
     await this.#checkWorkerIntegrity().catch((error) => {
       devUtils.error(
@@ -207,7 +304,7 @@ Please consider using a custom "serviceWorker.url" option to point to the actual
       this.#channel.postMessage('KEEPALIVE_REQUEST')
     }, 5000)
 
-    if (!this.options.quiet) {
+    if (!this.#options.quiet) {
       validateWorkerScope(registration)
     }
 

package/src/browser/utils/deserializeRequest.ts

@@ -1,5 +1,4 @@
 import { pruneGetRequestBody } from './pruneGetRequestBody'
-import type { ServiceWorkerIncomingRequest } from '../glossary'
 
 /**
  * Converts a given request received from the Service Worker

package/src/browser/utils/should-invalidate-worker.test.ts

@@ -0,0 +1,122 @@
+import { type ServiceWorkerSourceOptions } from '../sources/service-worker-source'
+import { shouldInvalidateWorker } from './should-invalidate-worker'
+
+function createOptions(
+  overrides: Partial<ServiceWorkerSourceOptions> = {},
+): ServiceWorkerSourceOptions {
+  return {
+    serviceWorker: {
+      url: '/mockServiceWorker.js',
+      options: { scope: '/' },
+    },
+    ...overrides,
+  }
+}
+
+it('returns true when the worker url differs', () => {
+  expect(
+    shouldInvalidateWorker(
+      createOptions({
+        serviceWorker: { url: '/a.js', options: { scope: '/' } },
+      }),
+      createOptions({
+        serviceWorker: { url: '/b.js', options: { scope: '/' } },
+      }),
+    ),
+  ).toBe(true)
+})
+
+it('returns true when the registration options differ', () => {
+  expect(
+    shouldInvalidateWorker(
+      createOptions({
+        serviceWorker: { url: '/sw.js', options: { scope: '/' } },
+      }),
+      createOptions({
+        serviceWorker: { url: '/sw.js', options: { scope: '/app' } },
+      }),
+    ),
+  ).toBe(true)
+})
+
+it('returns true when only one side has registration options', () => {
+  expect(
+    shouldInvalidateWorker(
+      createOptions({ serviceWorker: { url: '/sw.js' } }),
+      createOptions({
+        serviceWorker: { url: '/sw.js', options: { scope: '/' } },
+      }),
+    ),
+  ).toBe(true)
+})
+
+it('returns true when findWorker differs by reference', () => {
+  expect(
+    shouldInvalidateWorker(
+      createOptions({ findWorker: () => true }),
+      createOptions({ findWorker: () => true }),
+    ),
+  ).toBe(true)
+})
+
+it('returns true when findWorker is added on one side', () => {
+  expect(
+    shouldInvalidateWorker(
+      createOptions(),
+      createOptions({ findWorker: () => true }),
+    ),
+  ).toBe(true)
+})
+
+it('returns false for the same options reference', () => {
+  const options = createOptions()
+  expect(shouldInvalidateWorker(options, options)).toBe(false)
+})
+
+it('returns false for deeply equal options', () => {
+  expect(
+    shouldInvalidateWorker(
+      createOptions({
+        serviceWorker: { url: '/sw.js', options: { scope: '/' } },
+      }),
+      createOptions({
+        serviceWorker: { url: '/sw.js', options: { scope: '/' } },
+      }),
+    ),
+  ).toBe(false)
+})
+
+it('returns false for the same worker url without options', () => {
+  expect(
+    shouldInvalidateWorker(
+      createOptions({ serviceWorker: { url: '/sw.js' } }),
+      createOptions({ serviceWorker: { url: '/sw.js' } }),
+    ),
+  ).toBe(false)
+})
+
+it('returns false when findWorker is the same reference', () => {
+  const findWorker = () => true
+  expect(
+    shouldInvalidateWorker(
+      createOptions({ findWorker }),
+      createOptions({ findWorker }),
+    ),
+  ).toBe(false)
+})
+
+it('returns false regardless of the "quiet" option', () => {
+  expect(
+    shouldInvalidateWorker(
+      createOptions({ quiet: true }),
+      createOptions({ quiet: true }),
+    ),
+  ).toBe(false)
+
+  expect(
+    shouldInvalidateWorker(
+      createOptions({ quiet: false }),
+      createOptions({ quiet: true }),
+    ),
+  ).toBe(false)
+})

package/src/browser/utils/should-invalidate-worker.ts

@@ -0,0 +1,13 @@
+import { type ServiceWorkerSourceOptions } from '../sources/service-worker-source'
+
+export function shouldInvalidateWorker(
+  prevOptions: ServiceWorkerSourceOptions,
+  nextOptions: ServiceWorkerSourceOptions,
+): boolean {
+  return (
+    prevOptions.findWorker !== nextOptions.findWorker ||
+    prevOptions.serviceWorker.url !== nextOptions.serviceWorker.url ||
+    JSON.stringify(prevOptions.serviceWorker.options) !==
+      JSON.stringify(nextOptions.serviceWorker.options)
+  )
+}

package/src/browser/utils/workerChannel.ts

@@ -4,10 +4,6 @@ import { isObject } from '#core/utils/internal/isObject'
 import type { StringifiedResponse } from '../glossary'
 import { supportsServiceWorker } from '../utils/supports'
 
-export interface WorkerChannelOptions {
-  worker: Promise<ServiceWorker>
-}
-
 export type WorkerChannelEventMap = {
   REQUEST: WorkerEvent<IncomingWorkerRequest>
   RESPONSE: WorkerEvent<IncomingWorkerResponse>
@@ -121,25 +117,42 @@ type OutgoingWorkerEvents =
   | 'KEEPALIVE_REQUEST'
   | 'CLIENT_CLOSED'
 
-export class WorkerChannel extends Emitter<WorkerChannelEventMap> {
-  constructor(protected readonly options: WorkerChannelOptions) {
-    super()
+export interface WorkerChannelOptions {
+  getWorker: () => Promise<ServiceWorker>
+}
 
-    if (!SUPPORTS_SERVICE_WORKER) {
-      return
-    }
+export class WorkerChannel extends Emitter<WorkerChannelEventMap> {
+  #getWorker: WorkerChannelOptions['getWorker']
+  #controller: AbortController
 
-    navigator.serviceWorker.addEventListener('message', async (event) => {
-      const worker = await this.options.worker
+  constructor(options: WorkerChannelOptions) {
+    super()
 
-      if (event.source != null && event.source !== worker) {
-        return
-      }
+    invariant(
+      SUPPORTS_SERVICE_WORKER,
+      'Failed to open a WorkerChannel: Service Worker is not supported in this environment.',
+    )
 
-      if (event.data && isObject(event.data) && 'type' in event.data) {
-        this.emit(new WorkerEvent<any, any, any>(event))
-      }
-    })
+    this.#getWorker = options.getWorker
+    this.#controller = new AbortController()
+
+    navigator.serviceWorker.addEventListener(
+      'message',
+      async (event) => {
+        const worker = await this.#getWorker()
+
+        if (event.source != null && event.source !== worker) {
+          return
+        }
+
+        if (event.data && isObject(event.data) && 'type' in event.data) {
+          this.emit(new WorkerEvent<any, any, any>(event))
+        }
+      },
+      {
+        signal: this.#controller.signal,
+      },
+    )
   }
 
   /**
@@ -149,11 +162,20 @@ export class WorkerChannel extends Emitter<WorkerChannelEventMap> {
   public postMessage(type: OutgoingWorkerEvents): void {
     invariant(
       SUPPORTS_SERVICE_WORKER,
-      'Failed to post message on a WorkerChannel: the Service Worker API is unavailable in this context. This is likely an issue with MSW. Please report it on GitHub: https://github.com/mswjs/msw/issues',
+      'Failed to post message on a WorkerChannel: the Service Worker API is unavailable in this environment. This is likely an issue with MSW. Please report it on GitHub: https://github.com/mswjs/msw/issues',
     )
 
-    this.options.worker.then((worker) => {
+    this.#getWorker().then((worker) => {
       worker.postMessage(type)
     })
   }
+
+  /**
+   * Terminal teardown. Removes the `navigator.serviceWorker` message listener
+   * and all emitter subscriptions. The channel is not usable afterwards.
+   */
+  public terminate(): void {
+    this.#controller.abort()
+    this.removeAllListeners()
+  }
 }

package/src/core/experimental/define-network.ts

@@ -1,15 +1,15 @@
 import { invariant } from 'outvariant'
 import { Emitter, type DefaultEventMap } from 'rettime'
 import {
-  type NetworkSource,
+  NetworkSource,
   type ExtractSourceEvents,
 } from './sources/network-source'
 import { type NetworkFrameResolutionContext } from './frames/network-frame'
 import { type UnhandledFrameHandle } from './on-unhandled-frame'
 import {
-  AnyHandler,
   HandlersController,
   InMemoryHandlersController,
+  type AnyHandler,
 } from './handlers-controller'
 import { toReadonlyArray } from '../utils/internal/toReadonlyArray'
 
@@ -161,6 +161,14 @@ export function defineNetwork<Sources extends Array<NetworkSource<any>>>(
       readyState = NetworkReadyState.ENABLED
 
       const result = resolvedOptions.sources.map((source) => {
+        /**
+         * @note Preemptively disable the network source before enabling.
+         * This intentionally calls only the prototype method that clears the
+         * event listeners and nothing else. This prevents the "frame" listeners
+         * from accumulating across enable/disable in case the source is a singleton.
+         */
+        NetworkSource.prototype.disable.call(source)
+
         source.on('frame', async ({ frame }) => {
           frame.events.on('*', (event) => events.emit(event), {
             signal: listenersController.signal,

package/src/core/experimental/frames/http-frame.test.ts

@@ -2,7 +2,8 @@ import { http } from '../../http'
 import { graphql } from '../../graphql'
 import { ws } from '../../ws'
 import { bypass } from '../../bypass'
-import { HttpNetworkFrame, HttpNetworkFrameEventMap } from './http-frame'
+import type { HttpNetworkFrameEventMap } from './http-frame'
+import { HttpNetworkFrame } from './http-frame'
 import { InMemoryHandlersController } from '#core/experimental/handlers-controller'
 
 beforeAll(() => {

package/src/core/experimental/frames/http-frame.ts

@@ -1,7 +1,10 @@
 import { TypedEvent } from 'rettime'
 import { until } from 'until-async'
 import { createRequestId } from '@mswjs/interceptors'
-import { NetworkFrame, NetworkFrameResolutionContext } from './network-frame'
+import {
+  NetworkFrame,
+  type NetworkFrameResolutionContext,
+} from './network-frame'
 import { toPublicUrl } from '../../utils/request/toPublicUrl'
 import { executeHandlers } from '../../utils/executeHandlers'
 import { storeResponseCookies } from '../../utils/request/storeResponseCookies'
@@ -11,7 +14,8 @@ import {
   executeUnhandledFrameHandle,
   type UnhandledFrameHandle,
 } from '../on-unhandled-frame'
-import { HandlersController, AnyHandler } from '../handlers-controller'
+import type { HandlersController } from '../handlers-controller'
+import { type AnyHandler } from '../handlers-controller'
 import { type RequestHandler } from '../../handlers/RequestHandler'
 
 interface HttpNetworkFrameOptions {

package/src/core/experimental/frames/websocket-frame.test.ts

@@ -1,10 +1,8 @@
 import { http } from '../../http'
 import { graphql } from '../../graphql'
 import { ws } from '../../ws'
-import {
-  WebSocketNetworkFrame,
-  WebSocketNetworkFrameEventMap,
-} from './websocket-frame'
+import type { WebSocketNetworkFrameEventMap } from './websocket-frame'
+import { WebSocketNetworkFrame } from './websocket-frame'
 import { createTestWebSocketConnection } from '../../../../test/support/ws-test-utils'
 import { InMemoryHandlersController } from '#core/experimental/handlers-controller'
 

package/src/core/experimental/frames/websocket-frame.ts

@@ -11,10 +11,11 @@ import {
 } from './network-frame'
 import {
   executeUnhandledFrameHandle,
-  UnhandledFrameHandle,
+  type UnhandledFrameHandle,
 } from '../on-unhandled-frame'
 import { devUtils } from '../../utils/internal/devUtils'
-import { HandlersController, AnyHandler } from '../handlers-controller'
+import type { HandlersController } from '../handlers-controller'
+import { type AnyHandler } from '../handlers-controller'
 
 export interface WebSocketNetworkFrameOptions {
   connection: WebSocketConnectionData

package/src/core/experimental/handlers-controller.ts

@@ -31,7 +31,7 @@ export abstract class HandlersController {
     invariant(
       this.#validateHandlers(initialHandlers),
       devUtils.formatMessage(
-        '[MSW] Failed to apply given request handlers: invalid input. Did you forget to spread the request handlers Array?',
+        'Failed to apply given request handlers: invalid input. Did you forget to spread the request handlers Array?',
       ),
     )
 

package/src/core/experimental/index.ts

@@ -1,4 +1,4 @@
-export { defineNetwork, DefineNetworkOptions } from './define-network'
+export { defineNetwork, type DefineNetworkOptions } from './define-network'
 
 /* Network sources */
 export { NetworkSource } from './sources/network-source'

package/src/core/experimental/on-unhandled-frame.test.ts

@@ -5,10 +5,8 @@ import type {
 } from '@mswjs/interceptors/WebSocket'
 import { HttpNetworkFrame } from './frames/http-frame'
 import { WebSocketNetworkFrame } from './frames/websocket-frame'
-import {
-  executeUnhandledFrameHandle,
-  UnhandledFrameCallback,
-} from './on-unhandled-frame'
+import type { UnhandledFrameCallback } from './on-unhandled-frame'
+import { executeUnhandledFrameHandle } from './on-unhandled-frame'
 
 beforeAll(() => {
   vi.spyOn(console, 'warn').mockImplementation(() => void 0)

package/src/core/experimental/setup-api.ts

@@ -1,9 +1,9 @@
 import { type DefaultEventMap, Emitter } from 'rettime'
-import { LifeCycleEventEmitter } from '../sharedOptions'
+import { type LifeCycleEventEmitter } from '../sharedOptions'
+import type { HandlersController } from './handlers-controller'
 import {
-  AnyHandler,
-  HandlersController,
   InMemoryHandlersController,
+  type AnyHandler,
 } from './handlers-controller'
 import { Disposable } from '../utils/internal/Disposable'
 import { toReadonlyArray } from '../utils/internal/toReadonlyArray'

package/src/core/experimental/sources/interceptor-source.ts

@@ -1,9 +1,5 @@
-import {
-  BatchInterceptor,
-  Interceptor,
-  RequestController,
-  type HttpRequestEventMap,
-} from '@mswjs/interceptors'
+import type { Interceptor, RequestController } from '@mswjs/interceptors'
+import { BatchInterceptor, type HttpRequestEventMap } from '@mswjs/interceptors'
 import type {
   WebSocketConnectionData,
   WebSocketEventMap,