msw 2.12.13 → 2.13.0

package/src/browser/{setupWorker/start/utils/getWorkerInstance.ts → utils/get-worker-instance.ts}

@@ -1,8 +1,8 @@
 import { until } from 'until-async'
-import { devUtils } from '~/core/utils/internal/devUtils'
-import { getAbsoluteWorkerUrl } from '../../../utils/getAbsoluteWorkerUrl'
-import { getWorkerByRegistration } from './getWorkerByRegistration'
-import { ServiceWorkerInstanceTuple, FindWorker } from '../../glossary'
+import { devUtils } from '#core/utils/internal/devUtils'
+import { getAbsoluteWorkerUrl } from './getAbsoluteWorkerUrl'
+import { getWorkerByRegistration } from './get-worker-by-registration'
+import type { ServiceWorkerInstanceTuple, FindWorker } from '../glossary'
 
 /**
  * Returns an active Service Worker instance.

package/src/browser/utils/pruneGetRequestBody.test.ts

@@ -1,6 +1,4 @@
-/**
- * @vitest-environment jsdom
- */
+// @vitest-environment jsdom
 import { TextEncoder } from 'util'
 import { pruneGetRequestBody } from './pruneGetRequestBody'
 

package/src/browser/utils/pruneGetRequestBody.ts

@@ -1,4 +1,4 @@
-import type { ServiceWorkerIncomingRequest } from '../setupWorker/glossary'
+import type { ServiceWorkerIncomingRequest } from '../glossary'
 
 type Input = Pick<ServiceWorkerIncomingRequest, 'method' | 'body'>
 

package/src/browser/utils/validate-worker-scope.ts

@@ -0,0 +1,19 @@
+import { devUtils } from '#core/utils/internal/devUtils'
+
+/**
+ * Print a warning if the given Service Worker registration has a scope
+ * outside of the current page's location. That is to help with debugging
+ * issues caused by the incorrectly registered Service Worker.
+ */
+export function validateWorkerScope(
+  registration: ServiceWorkerRegistration,
+): void {
+  if (!location.href.startsWith(registration.scope)) {
+    devUtils.warn(
+      `Cannot intercept requests on this page because it's outside of the worker's scope ("${registration.scope}"). If you wish to mock API requests on this page, you must resolve this scope issue.
+
+- (Recommended) Register the worker at the root level ("/") of your application.
+- Set the "Service-Worker-Allowed" response header to allow out-of-scope workers.`,
+    )
+  }
+}

package/src/browser/utils/workerChannel.ts

@@ -1,7 +1,7 @@
 import { invariant } from 'outvariant'
 import { Emitter, TypedEvent } from 'rettime'
-import { isObject } from '~/core/utils/internal/isObject'
-import type { StringifiedResponse } from '../setupWorker/glossary'
+import { isObject } from '#core/utils/internal/isObject'
+import type { StringifiedResponse } from '../glossary'
 import { supportsServiceWorker } from '../utils/supports'
 
 export interface WorkerChannelOptions {

package/src/core/experimental/compat.ts

@@ -0,0 +1,50 @@
+/**
+ * Collection of helpers for bridging the compatibility between the old and the new APIs.
+ */
+import { invariant } from 'outvariant'
+import { type UnhandledRequestStrategy } from '../utils/request/onUnhandledRequest'
+import {
+  executeUnhandledFrameHandle,
+  type UnhandledFrameCallback,
+} from './on-unhandled-frame'
+import { HttpNetworkFrame } from './frames/http-frame'
+import { WebSocketNetworkFrame } from './frames/websocket-frame'
+
+export function fromLegacyOnUnhandledRequest(
+  getLegacyValue: () => UnhandledRequestStrategy | undefined,
+): UnhandledFrameCallback {
+  return ({ frame, defaults }) => {
+    const legacyOnUnhandledRequestStrategy = getLegacyValue()
+
+    if (legacyOnUnhandledRequestStrategy == null) {
+      return
+    }
+
+    if (typeof legacyOnUnhandledRequestStrategy === 'function') {
+      const request =
+        frame instanceof HttpNetworkFrame
+          ? frame.data.request
+          : frame instanceof WebSocketNetworkFrame
+            ? new Request(frame.data.connection.client.url, {
+                headers: {
+                  connection: 'upgrade',
+                  upgrade: 'websocket',
+                },
+              })
+            : null
+
+      invariant(
+        request != null,
+        'Failed to coerce a network frame to a legacy `onUnhandledRequest` strategy: unknown frame protocol "%s"',
+        frame.protocol,
+      )
+
+      return legacyOnUnhandledRequestStrategy(request, {
+        warning: defaults.warn,
+        error: defaults.error,
+      })
+    }
+
+    return executeUnhandledFrameHandle(frame, legacyOnUnhandledRequestStrategy)
+  }
+}

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

@@ -0,0 +1,124 @@
+import { NetworkSource } from './sources/network-source'
+import { defineNetwork } from './define-network'
+
+describe('enable()', () => {
+  it('throws if called on already enabled network', () => {
+    class SyncNetworkSource extends NetworkSource {
+      enable = () => {}
+    }
+    const network = defineNetwork({
+      sources: [new SyncNetworkSource()],
+    })
+
+    expect(network.enable()).toBeUndefined()
+    expect(() => network.enable()).toThrow(
+      'Failed to call "enable" on the network: already enabled',
+    )
+
+    network.disable()
+    expect(network.enable()).toBeUndefined()
+  })
+
+  it('returns a sync enable if all the sources are sync', () => {
+    class SyncNetworkSource extends NetworkSource {
+      enable = () => {}
+    }
+    const network = defineNetwork({
+      sources: [new SyncNetworkSource()],
+    })
+
+    expect(network.enable()).toBeUndefined()
+  })
+
+  it('returns an async enable if any of the sources are async', () => {
+    class SyncNetworkSource extends NetworkSource {
+      enable = () => {}
+    }
+    class AsyncNetworkSource extends NetworkSource {
+      enable = async () => {}
+    }
+
+    const network = defineNetwork({
+      sources: [new SyncNetworkSource(), new AsyncNetworkSource()],
+    })
+
+    expect(network.enable()).toBeInstanceOf(Promise)
+  })
+
+  it('returns an async enable if all the sources are async', () => {
+    class AsyncNetworkSource extends NetworkSource {
+      enable = async () => {}
+    }
+
+    const network = defineNetwork({
+      sources: [new AsyncNetworkSource()],
+    })
+
+    expect(network.enable()).toBeInstanceOf(Promise)
+  })
+})
+
+describe('disable()', () => {
+  it('throws if called on already enabled network', () => {
+    class SyncNetworkSource extends NetworkSource {
+      enable = () => {}
+    }
+    const network = defineNetwork({
+      sources: [new SyncNetworkSource()],
+    })
+
+    network.enable()
+    expect(network.disable()).toBeUndefined()
+    expect(() => network.disable()).toThrow(
+      'Failed to call "disable" on the network: already disabled',
+    )
+
+    network.enable()
+    expect(network.disable()).toBeUndefined()
+  })
+
+  it('returns a sync disable if all the sources are sync', () => {
+    class SyncNetworkSource extends NetworkSource {
+      enable = () => {}
+      disable = () => {}
+    }
+    const network = defineNetwork({
+      sources: [new SyncNetworkSource()],
+    })
+
+    network.enable()
+    expect(network.disable()).toBeUndefined()
+  })
+
+  it('returns an async disable if any of the sources are async', async () => {
+    class SyncNetworkSource extends NetworkSource {
+      enable = () => {}
+      disable = () => {}
+    }
+    class AsyncNetworkSource extends NetworkSource {
+      enable = async () => {}
+      disable = async () => {}
+    }
+
+    const network = defineNetwork({
+      sources: [new SyncNetworkSource(), new AsyncNetworkSource()],
+    })
+
+    await network.enable()
+    expect(network.disable()).toBeInstanceOf(Promise)
+  })
+
+  it('returns an async disable if all the sources are async', async () => {
+    class AsyncNetworkSource extends NetworkSource {
+      enable = async () => {}
+      disable = async () => {}
+    }
+
+    const network = defineNetwork({
+      sources: [new AsyncNetworkSource()],
+    })
+
+    await network.enable()
+    expect(network.disable()).toBeInstanceOf(Promise)
+  })
+})

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

@@ -0,0 +1,215 @@
+import { invariant } from 'outvariant'
+import { Emitter, type DefaultEventMap } from 'rettime'
+import {
+  type 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,
+} from './handlers-controller'
+import { toReadonlyArray } from '../utils/internal/toReadonlyArray'
+
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
+  k: infer I,
+) => void
+  ? I
+  : never
+
+type MergeEventMaps<Sources extends Array<NetworkSource<any>>> =
+  UnionToIntersection<ExtractSourceEvents<Sources[number]>> extends infer R
+    ? R extends Record<string, any>
+      ? R
+      : DefaultEventMap
+    : DefaultEventMap
+
+type MaybePromise<T> =
+  Extract<T, Promise<unknown>> extends never ? void : Promise<void>
+
+export interface DefineNetworkOptions<
+  Sources extends Array<NetworkSource<any>>,
+> {
+  /**
+   * List of the network sources.
+   * Every network source emits frames, and every frame describes how
+   * to handle the various network scenarios, like mocking a response,
+   * erroring the request, or performing it as-is.
+   */
+  sources: Sources
+  /**
+   * List of handlers to describe the network.
+   */
+  handlers?: Array<AnyHandler> | HandlersController
+  context?: NetworkFrameResolutionContext
+  onUnhandledFrame?: UnhandledFrameHandle
+}
+
+export interface NetworkApi<Sources extends Array<NetworkSource<any>>>
+  extends NetworkHandlersApi {
+  readyState: NetworkReadyState
+  /**
+   * Enable the network interception and handling.
+   */
+  enable: () => MaybePromise<ReturnType<Sources[number]['enable']>>
+  /**
+   * Disable the network interception and handling.
+   */
+  disable: () => MaybePromise<ReturnType<Sources[number]['disable']>>
+  /**
+   * Configure the network instance with additional options.
+   * The options provided in the `.configure()` call will override the same
+   * options in the `defineNetwork()` call.
+   */
+  configure: (options: Partial<DefineNetworkOptions<Sources>>) => void
+  events: Emitter<MergeEventMaps<Sources>>
+}
+
+export interface NetworkHandlersApi {
+  use: (...handlers: Array<AnyHandler>) => void
+  resetHandlers: (...handlers: Array<AnyHandler>) => void
+  restoreHandlers: () => void
+  listHandlers: () => ReadonlyArray<AnyHandler>
+}
+
+function colorlessPromiseAll<T>(values: Array<T>): MaybePromise<T>
+function colorlessPromiseAll(values: Array<unknown>): Promise<void> | void {
+  const promises: Array<Promise<void>> = []
+
+  for (const value of values) {
+    if (value instanceof Promise) {
+      promises.push(value)
+    }
+  }
+
+  if (promises.length > 0) {
+    return Promise.all(promises).then(() => {})
+  }
+}
+
+export enum NetworkReadyState {
+  DISABLED,
+  ENABLED,
+}
+
+/**
+ * Define a network instance with the given configuration.
+ * @example
+ * import { InterceptorSource } from 'msw/experimental'
+ * import { handlers } from './handlers'
+ *
+ * const network = defineNetwork({
+ *   sources: [new InterceptorSource({ interceptors })],
+ *   handlers,
+ * })
+ * await network.enable()
+ */
+export function defineNetwork<Sources extends Array<NetworkSource<any>>>(
+  options: DefineNetworkOptions<Sources>,
+): NetworkApi<Sources> {
+  let readyState: NetworkReadyState = NetworkReadyState.DISABLED
+  const events = new Emitter<MergeEventMaps<Sources>>()
+
+  const deriveHandlersController = (
+    handlers: DefineNetworkOptions<Sources>['handlers'],
+  ) => {
+    return handlers instanceof HandlersController
+      ? handlers
+      : new InMemoryHandlersController(handlers || [])
+  }
+
+  let resolvedOptions: DefineNetworkOptions<Sources> = {
+    ...options,
+  }
+
+  /**
+   * @note Create the handlers controller immediately because
+   * certain setup APIs, like `setupServer`, don't await `.enable` (`.listen`).
+   */
+  let handlersController = deriveHandlersController(resolvedOptions.handlers)
+  let listenersController: AbortController
+
+  return {
+    get readyState() {
+      return readyState
+    },
+    events,
+    configure(options) {
+      invariant(readyState === NetworkReadyState.DISABLED, '')
+
+      if (
+        options.handlers &&
+        !Object.is(options.handlers, resolvedOptions.handlers)
+      ) {
+        handlersController = deriveHandlersController(options.handlers)
+      }
+
+      resolvedOptions = {
+        ...resolvedOptions,
+        ...options,
+      }
+    },
+    enable() {
+      invariant(
+        readyState === NetworkReadyState.DISABLED,
+        'Failed to call "enable" on the network: already enabled',
+      )
+
+      listenersController = new AbortController()
+      readyState = NetworkReadyState.ENABLED
+
+      const result = resolvedOptions.sources.map((source) => {
+        source.on('frame', async ({ frame }) => {
+          frame.events.on('*', (event) => events.emit(event), {
+            signal: listenersController.signal,
+          })
+
+          const handlers = frame.getHandlers(handlersController)
+
+          await frame.resolve(
+            handlers,
+            resolvedOptions.onUnhandledFrame || 'warn',
+            resolvedOptions.context,
+          )
+        })
+
+        return source.enable()
+      })
+
+      return colorlessPromiseAll(result) as MaybePromise<
+        ReturnType<Sources[number]['enable']>
+      >
+    },
+    disable() {
+      invariant(
+        readyState === NetworkReadyState.ENABLED,
+        'Failed to call "disable" on the network: already disabled',
+      )
+
+      listenersController.abort()
+      readyState = NetworkReadyState.DISABLED
+
+      return colorlessPromiseAll(
+        resolvedOptions.sources.map((source) => source.disable()),
+      ) as MaybePromise<ReturnType<Sources[number]['disable']>>
+    },
+    use(...handlers) {
+      handlersController.use(handlers)
+    },
+    resetHandlers(...handlers) {
+      handlersController.reset(handlers)
+    },
+    restoreHandlers() {
+      for (const handler of handlersController.currentHandlers()) {
+        if ('isUsed' in handler) {
+          handler.isUsed = false
+        }
+      }
+    },
+    listHandlers() {
+      return toReadonlyArray(handlersController.currentHandlers())
+    },
+  }
+}