msw 2.15.0 → 3.0.0

package/src/vite/plugin.ts

@@ -0,0 +1,133 @@
+import * as fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import type { Plugin } from 'vite'
+
+const WORKER_FILENAME = 'mockServiceWorker.js'
+const WORKER_SCRIPT_PATH = new URL('../mockServiceWorker.js', import.meta.url)
+const VIRTUAL_MODULE_ID = 'virtual:msw'
+const VIRTUAL_OPTIONS_ID = 'virtual:msw/options'
+const RUNTIME_PATH = fileURLToPath(new URL('./runtime.js', import.meta.url))
+
+export interface MswPluginOptions {
+  /**
+   * Use automatic integration or only provide the worker script for manual setup.
+   * In worker-only mode, virtual modules are disabled.
+   * @default "auto"
+   */
+  mode?: 'auto' | 'worker-only'
+}
+
+/**
+ * A Vite plugin for Mock Service Worker.
+ *
+ * @example
+ * // vite.config.ts
+ * import { msw } from 'msw/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [msw()]
+ * })
+ *
+ * @example
+ * // src/{client,server}.ts
+ * if (import.meta.env.DEV) {
+ *   const { network } = await import('virtual:msw')
+ *   const { handlers } = await import('./mocks/handlers')
+ *
+ *   network.configure({ handlers })
+ *   await network.enable()
+ * }
+ *
+ * @remarks
+ * The worker script is served during development and emitted next to any
+ * client bundle that imports `virtual:msw`. Guard mocking setup with
+ * `import.meta.env.DEV` to exclude both from production builds.
+ *
+ * For application TypeScript projects that do not include the Vite config,
+ * add `/// <reference types="msw/vite/client" />` to an included declaration file.
+ */
+export function msw(options: MswPluginOptions = {}): Plugin {
+  const mode = options.mode ?? 'auto'
+  let workerUrl = `/${WORKER_FILENAME}`
+  const environmentsUsingNetwork = new Set<string>()
+
+  return {
+    name: 'msw',
+    async resolveId(id) {
+      if (mode === 'worker-only') {
+        return
+      }
+
+      if (id === VIRTUAL_OPTIONS_ID) {
+        return `\0${VIRTUAL_OPTIONS_ID}`
+      }
+
+      if (id === VIRTUAL_MODULE_ID) {
+        return this.resolve(RUNTIME_PATH)
+      }
+    },
+    load(id) {
+      if (mode === 'worker-only' || id !== `\0${VIRTUAL_OPTIONS_ID}`) {
+        return
+      }
+
+      if (this.environment.config.consumer === 'server') {
+        return `export { defaultNetworkOptions } from 'msw/node'`
+      }
+
+      environmentsUsingNetwork.add(this.environment.name)
+
+      return `
+import { createDefaultNetworkOptions } from 'msw/browser'
+export const defaultNetworkOptions = createDefaultNetworkOptions(${JSON.stringify(workerUrl)})
+`
+    },
+    configResolved(config) {
+      // Keep relative build bases relative and service workers on the app's origin.
+      const base =
+        config.base === './'
+          ? config.base
+          : new URL(config.base, 'http://localhost').pathname
+      workerUrl = `${base}${WORKER_FILENAME}`
+    },
+    generateBundle() {
+      if (this.environment.config.consumer !== 'client') {
+        return
+      }
+
+      // In "auto" mode, the worker is only useful to bundles that contain the
+      // network. A user guard (e.g. `import.meta.env.DEV`) that drops the
+      // `virtual:msw` import drops the worker too.
+      if (
+        mode === 'auto' &&
+        !environmentsUsingNetwork.has(this.environment.name)
+      ) {
+        return
+      }
+
+      this.emitFile({
+        type: 'asset',
+        fileName: WORKER_FILENAME,
+        source: fs.readFileSync(WORKER_SCRIPT_PATH, 'utf8'),
+      })
+    },
+    configureServer(server) {
+      const workerScript = fs.readFileSync(WORKER_SCRIPT_PATH, 'utf8')
+      server.middlewares.use((request, response, next) => {
+        const requestUrl = new URL(request.url ?? '/', 'http://localhost')
+
+        if (requestUrl.pathname !== workerUrl) {
+          next()
+          return
+        }
+
+        response.writeHead(200, {
+          'cache-control': 'no-cache',
+          'content-type': 'application/javascript; charset=utf-8',
+          'service-worker-allowed': '/',
+        })
+        response.end(workerScript)
+      })
+    },
+  }
+}

package/src/vite/runtime.ts

@@ -0,0 +1,117 @@
+/// <reference types="vite/client" />
+
+import {
+  defineNetwork,
+  NetworkReadyState,
+  type NetworkApi,
+} from 'msw/experimental'
+import { defaultNetworkOptions } from 'virtual:msw/options'
+
+const hot = import.meta.hot
+const hotData: { disposeNetwork?: () => Promise<void> } | undefined = hot?.data
+
+// SSR imports can re-evaluate this module before the old HMR listener runs.
+while (hotData?.disposeNetwork) {
+  const disposePrevious = hotData.disposeNetwork
+  await disposePrevious()
+
+  if (hotData.disposeNetwork === disposePrevious) {
+    break
+  }
+}
+
+export const network: NetworkApi<typeof defaultNetworkOptions.sources> =
+  defineNetwork<typeof defaultNetworkOptions.sources>(defaultNetworkOptions)
+
+if (hot && hotData) {
+  let resumeAfterUpdate = false
+  let retired = false
+  let pendingOperation: Promise<void> | undefined
+  const configure = network.configure
+  const enable = network.enable
+  const disable = network.disable
+
+  const runOperation = (action: () => void | Promise<void>) => {
+    const result = pendingOperation ? pendingOperation.then(action) : action()
+
+    if (result instanceof Promise) {
+      const operation = result.finally(() => {
+        if (pendingOperation === operation) {
+          pendingOperation = undefined
+        }
+      })
+      pendingOperation = operation
+
+      return operation
+    }
+  }
+
+  const stop = () => {
+    if (network.readyState === NetworkReadyState.ENABLED) {
+      return disable()
+    }
+  }
+
+  // An SSR entry may be re-evaluated while this module remains cached.
+  network.configure = (options) => {
+    void runOperation(() => {
+      if (retired) {
+        return
+      }
+
+      const stopped = stop()
+
+      if (stopped instanceof Promise) {
+        return stopped.then(() => configure(options))
+      }
+
+      configure(options)
+    })
+  }
+  network.enable = async () => {
+    await runOperation(() => {
+      if (!retired && network.readyState === NetworkReadyState.DISABLED) {
+        return enable()
+      }
+    })
+  }
+  network.disable = async () => {
+    await runOperation(stop)
+  }
+
+  const disableNetwork = async () => {
+    await network.disable()
+  }
+
+  const beforeUpdate = async () => {
+    resumeAfterUpdate = network.readyState === NetworkReadyState.ENABLED
+    await disableNetwork()
+  }
+
+  const afterUpdate = async () => {
+    const shouldResume = resumeAfterUpdate
+    resumeAfterUpdate = false
+
+    if (shouldResume && network.readyState === NetworkReadyState.DISABLED) {
+      await network.enable()
+    }
+  }
+
+  hot.on('vite:beforeUpdate', beforeUpdate)
+  hot.on('vite:afterUpdate', afterUpdate)
+  hot.on('vite:beforeFullReload', disableNetwork)
+
+  const disposeNetwork = async () => {
+    retired = true
+    resumeAfterUpdate = false
+
+    hot.off('vite:beforeUpdate', beforeUpdate)
+    hot.off('vite:afterUpdate', afterUpdate)
+    hot.off('vite:beforeFullReload', disableNetwork)
+
+    await disableNetwork()
+  }
+
+  hotData.disposeNetwork = disposeNetwork
+  hot.dispose(disposeNetwork)
+}

package/src/vite/tsconfig.build.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["./index.ts", "./plugin.ts", "./runtime.ts", "./options.d.ts"],
+  "compilerOptions": {
+    "types": ["node"]
+  }
+}

package/src/ws/index.ts

@@ -0,0 +1,23 @@
+export {
+  ws,
+  type WebSocketLink,
+  type WebSocketLinkOptions,
+  type WebSocketLinkExtension,
+  type WebSocketData,
+  type WebSocketEventListener,
+} from './ws'
+
+export {
+  WebSocketHandler,
+  WebSocketConnectionEvent,
+  type WebSocketHandlerOptions,
+  type WebSocketHandlerEventMap,
+  type WebSocketHandlerConnection,
+} from './websocket-handler'
+
+export {
+  WebSocketExtension,
+  type WebSocketExtensionContext,
+  type WebSocketExtensionMessageContext,
+  type WebSocketExtensionResult,
+} from '@mswjs/interceptors/WebSocket'

package/src/{core/ws/utils/attachWebSocketLogger.ts → ws/utils/attach-websocket-logger.ts}

@@ -1,23 +1,20 @@
-import type {
+import {
   WebSocketClientConnection,
-  WebSocketConnectionData,
-  WebSocketData,
+  WebSocketServerConnection,
+  type WebSocketClientHandle,
+  type WebSocketServerHandle,
+  type WebSocketConnectionEventData,
+  type WebSocketData,
 } from '@mswjs/interceptors/WebSocket'
-import { devUtils } from '../../utils/internal/devUtils'
-import { getTimestamp } from '../../utils/logging/getTimestamp'
-import { toPublicUrl } from '../../utils/request/toPublicUrl'
-import { getMessageLength } from './getMessageLength'
-import { getPublicData } from './getPublicData'
-
-export const colors = {
-  system: '#3b82f6',
-  outgoing: '#22c55e',
-  incoming: '#ef4444',
-  mocked: '#ff6a33',
-}
+import { devUtils } from '#core/utils/internal/dev-utils'
+import { getTimestamp } from '#core/utils/logging/get-timestamp'
+import { toPublicUrl } from '#core/utils/request/to-public-url'
+import { getMessageLength } from './get-message-length'
+import { getPublicData } from './get-public-data'
+import { colors } from '#core/utils/logging/colors'
 
 export function attachWebSocketLogger(
-  connection: WebSocketConnectionData,
+  connection: WebSocketConnectionEventData,
 ): () => void {
   const { client, server } = connection
   const controller = new AbortController()
@@ -48,7 +45,7 @@ export function attachWebSocketLogger(
   )
 
   // Log client errors (connection closures due to errors).
-  client.socket.addEventListener(
+  getClientSocket(client)?.addEventListener(
     'error',
     (event) => {
       logClientError(event)
@@ -65,12 +62,12 @@ export function attachWebSocketLogger(
         currentTarget: {
           enumerable: true,
           writable: false,
-          value: client.socket,
+          value: getClientSocket(client),
         },
         target: {
           enumerable: true,
           writable: false,
-          value: client.socket,
+          value: getClientSocket(client),
         },
       })
 
@@ -106,12 +103,12 @@ export function attachWebSocketLogger(
         currentTarget: {
           enumerable: true,
           writable: false,
-          value: server.socket,
+          value: getServerSocket(server),
         },
         target: {
           enumerable: true,
           writable: false,
-          value: server.socket,
+          value: getServerSocket(server),
         },
       })
 
@@ -142,7 +139,7 @@ export function attachWebSocketLogger(
  * that intercepted this connection. This helps you see
  * what handlers observe this connection.
  */
-export function logConnectionOpen(client: WebSocketClientConnection) {
+function logConnectionOpen(client: WebSocketClientHandle) {
   const publicUrl = toPublicUrl(client.url)
 
   console.groupCollapsed(
@@ -151,10 +148,35 @@ export function logConnectionOpen(client: WebSocketClientConnection) {
     'color:inherit',
   )
   // eslint-disable-next-line no-console
-  console.log('Client:', client.socket)
+  console.log('Client:', getClientSocket(client) ?? client)
   console.groupEnd()
 }
 
+/**
+ * Return the underlying `WebSocket` of the given client, if any.
+ * Only in-process client connections are backed by a socket;
+ * a handle to a connection elsewhere (e.g. another runtime) is not.
+ */
+function getClientSocket(client: WebSocketClientHandle): WebSocket | undefined {
+  if (client instanceof WebSocketClientConnection) {
+    return client.socket
+  }
+
+  return undefined
+}
+
+/**
+ * Return the underlying `WebSocket` of the given server, if any.
+ * Only in-process server connections are backed by a socket.
+ */
+function getServerSocket(server: WebSocketServerHandle): WebSocket | undefined {
+  if (server instanceof WebSocketServerConnection) {
+    return server.socket
+  }
+
+  return undefined
+}
+
 function logConnectionClose(event: CloseEvent) {
   const target = event.target as WebSocket
   const publicUrl = toPublicUrl(target.url)

package/src/{core/ws/utils/getMessageLength.test.ts → ws/utils/get-message-length.test.ts}

@@ -1,16 +1,16 @@
-import { getMessageLength } from './getMessageLength'
+import { getMessageLength } from './get-message-length'
 
-it('returns the length of the string', () => {
+test('returns the length of the string', () => {
   expect(getMessageLength('')).toBe(0)
   expect(getMessageLength('hello')).toBe(5)
 })
 
-it('returns the size of the Blob', () => {
+test('returns the size of the Blob', () => {
   expect(getMessageLength(new Blob())).toBe(0)
   expect(getMessageLength(new Blob(['hello']))).toBe(5)
 })
 
-it('returns the byte length of ArrayBuffer', () => {
+test('returns the byte length of ArrayBuffer', () => {
   expect(getMessageLength(new ArrayBuffer(0))).toBe(0)
   expect(getMessageLength(new ArrayBuffer(5))).toBe(5)
 })

package/src/{core/ws/utils/getMessageLength.ts → ws/utils/get-message-length.ts}

@@ -1,5 +1,5 @@
 import type { WebSocketData } from '@mswjs/interceptors/WebSocket'
-import { isObject } from '../../utils/internal/isObject'
+import { isObject } from '#core/utils/internal/is-object'
 
 /**
  * Returns the byte length of the given WebSocket message.

package/src/{core/ws/utils/getPublicData.test.ts → ws/utils/get-public-data.test.ts}

@@ -1,28 +1,28 @@
-import { getPublicData } from './getPublicData'
+import { getPublicData } from './get-public-data'
 
-it('returns a short string as-is', async () => {
+test('returns a short string as-is', async () => {
   expect(await getPublicData('')).toBe('')
   expect(await getPublicData('hello')).toBe('hello')
 })
 
-it('returns a truncated long string', async () => {
+test('returns a truncated long string', async () => {
   expect(await getPublicData('this is a very long string')).toBe(
     'this is a very long stri…',
   )
 })
 
-it('returns a short Blob text as-is', async () => {
+test('returns a short Blob text as-is', async () => {
   expect(await getPublicData(new Blob(['']))).toBe('Blob()')
   expect(await getPublicData(new Blob(['hello']))).toBe('Blob(hello)')
 })
 
-it('returns a truncated long Blob text', async () => {
+test('returns a truncated long Blob text', async () => {
   expect(await getPublicData(new Blob(['this is a very long string']))).toBe(
     'Blob(this is a very long stri…)',
   )
 })
 
-it('returns a short ArrayBuffer text as-is', async () => {
+test('returns a short ArrayBuffer text as-is', async () => {
   expect(await getPublicData(new TextEncoder().encode(''))).toBe(
     'ArrayBuffer()',
   )
@@ -31,7 +31,7 @@ it('returns a short ArrayBuffer text as-is', async () => {
   )
 })
 
-it('returns a truncated ArrayBuffer text', async () => {
+test('returns a truncated ArrayBuffer text', async () => {
   expect(
     await getPublicData(new TextEncoder().encode('this is a very long string')),
   ).toBe('ArrayBuffer(this is a very long stri…)')

package/src/ws/utils/get-public-data.ts

@@ -0,0 +1,23 @@
+import { truncateMessage } from './truncate-message'
+
+/**
+ * Format the given WebSocket data or protocol message for logging.
+ */
+export async function getPublicData(data: unknown): Promise<string> {
+  if (typeof data === 'string') {
+    return truncateMessage(data)
+  }
+
+  if (data instanceof Blob) {
+    const text = await data.text()
+    return `Blob(${truncateMessage(text)})`
+  }
+
+  if (data instanceof ArrayBuffer || ArrayBuffer.isView(data)) {
+    const text = new TextDecoder().decode(data)
+    return `ArrayBuffer(${truncateMessage(text)})`
+  }
+
+  // Protocol messages can be any structured data.
+  return truncateMessage(JSON.stringify(data))
+}

package/src/{core/ws/utils/truncateMessage.test.ts → ws/utils/truncate-message.test.ts}

@@ -1,11 +1,11 @@
-import { truncateMessage } from './truncateMessage'
+import { truncateMessage } from './truncate-message'
 
-it('returns a short string as-is', () => {
+test('returns a short string as-is', () => {
   expect(truncateMessage('')).toBe('')
   expect(truncateMessage('hello')).toBe('hello')
 })
 
-it('truncates a long string', () => {
+test('truncates a long string', () => {
   expect(truncateMessage('this is a very long string')).toBe(
     'this is a very long stri…',
   )

package/src/{core/ws/WebSocketClientManager.test.ts → ws/websocket-client-manager.test.ts}

@@ -1,9 +1,8 @@
-// @vitest-environment node-websocket
 import { setMaxListeners } from 'node:events'
 import { WebSocketClientConnection } from '@mswjs/interceptors/WebSocket'
-import type { WebSocketBroadcastChannelMessage } from './WebSocketClientManager'
-import { WebSocketClientManager } from './WebSocketClientManager'
-import { TestWebSocketTransport } from '../../../test/support/ws-test-utils'
+import type { WebSocketBroadcastChannelMessage } from './websocket-client-manager'
+import { WebSocketClientManager } from './websocket-client-manager'
+import { TestWebSocketTransport } from '../../test/support/ws-test-utils'
 
 const channel = new BroadcastChannel('test:channel')
 
@@ -22,7 +21,7 @@ afterEach(() => {
   vi.resetAllMocks()
 })
 
-it('adds a client from this runtime to the list of clients', async () => {
+test('adds a client from this runtime to the list of clients', async () => {
   const manager = new WebSocketClientManager(channel)
   const connection = new WebSocketClientConnection(
     socket,
@@ -35,7 +34,7 @@ it('adds a client from this runtime to the list of clients', async () => {
   expect(Array.from(manager.clients.values())).toEqual([connection])
 })
 
-it('adds multiple clients from this runtime to the list of clients', async () => {
+test('adds multiple clients from this runtime to the list of clients', async () => {
   const manager = new WebSocketClientManager(channel)
   const connectionOne = new WebSocketClientConnection(
     socket,
@@ -59,7 +58,7 @@ it('adds multiple clients from this runtime to the list of clients', async () =>
   ])
 })
 
-it('replays a "send" event coming from another runtime', async () => {
+test('replays a "send" event coming from another runtime', async () => {
   const manager = new WebSocketClientManager(channel)
   const connection = new WebSocketClientConnection(
     socket,
@@ -88,7 +87,7 @@ it('replays a "send" event coming from another runtime', async () => {
   })
 })
 
-it('replays a "close" event coming from another runtime', async () => {
+test('replays a "close" event coming from another runtime', async () => {
   const manager = new WebSocketClientManager(channel)
   const connection = new WebSocketClientConnection(
     socket,
@@ -118,7 +117,7 @@ it('replays a "close" event coming from another runtime', async () => {
   })
 })
 
-it('removes the extraneous message listener when the connection closes', async () => {
+test('removes the extraneous message listener when the connection closes', async () => {
   const manager = new WebSocketClientManager(channel)
   const transport = new TestWebSocketTransport()
   const connection = new WebSocketClientConnection(socket, transport)