@depup/msw 2.12.13-depup.0

package/src/browser/setupWorker/start/utils/getWorkerInstance.ts

@@ -0,0 +1,97 @@
+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'
+
+/**
+ * Returns an active Service Worker instance.
+ * When not found, registers a new Service Worker.
+ */
+export const getWorkerInstance = async (
+  url: string,
+  options: RegistrationOptions = {},
+  findWorker: FindWorker,
+): Promise<ServiceWorkerInstanceTuple> => {
+  // Resolve the absolute Service Worker URL.
+  const absoluteWorkerUrl = getAbsoluteWorkerUrl(url)
+
+  const mockRegistrations = await navigator.serviceWorker
+    .getRegistrations()
+    .then((registrations) =>
+      registrations.filter((registration) =>
+        getWorkerByRegistration(registration, absoluteWorkerUrl, findWorker),
+      ),
+    )
+  if (!navigator.serviceWorker.controller && mockRegistrations.length > 0) {
+    // Reload the page when it has associated workers, but no active controller.
+    // The absence of a controller can mean either:
+    // - page has no Service Worker associated with it
+    // - page has been hard-reloaded and its workers won't be used until the next reload.
+    // Since we've checked that there are registrations associated with this page,
+    // at this point we are sure it's hard reload that falls into this clause.
+    location.reload()
+  }
+
+  const [existingRegistration] = mockRegistrations
+
+  if (existingRegistration) {
+    // Schedule the worker update in the background.
+    // Update ensures the existing worker is up-to-date.
+    existingRegistration.update()
+
+    // Return the worker reference immediately.
+    return [
+      getWorkerByRegistration(
+        existingRegistration,
+        absoluteWorkerUrl,
+        findWorker,
+      ),
+      existingRegistration,
+    ]
+  }
+
+  // When the Service Worker wasn't found, register it anew and return the reference.
+  const [registrationError, registrationResult] = await until<
+    Error,
+    ServiceWorkerInstanceTuple
+  >(async () => {
+    const registration = await navigator.serviceWorker.register(url, options)
+    return [
+      // Compare existing worker registration by its worker URL,
+      // to prevent irrelevant workers to resolve here (such as Codesandbox worker).
+      getWorkerByRegistration(registration, absoluteWorkerUrl, findWorker),
+      registration,
+    ]
+  })
+
+  // Handle Service Worker registration errors.
+  if (registrationError) {
+    const isWorkerMissing = registrationError.message.includes('(404)')
+
+    // Produce a custom error message when given a non-existing Service Worker url.
+    // Suggest developers to check their setup.
+    if (isWorkerMissing) {
+      const scopeUrl = new URL(options?.scope || '/', location.href)
+
+      throw new Error(
+        devUtils.formatMessage(`\
+Failed to register a Service Worker for scope ('${scopeUrl.href}') with script ('${absoluteWorkerUrl}'): Service Worker script does not exist at the given path.
+
+Did you forget to run "npx msw init <PUBLIC_DIR>"?
+
+Learn more about creating the Service Worker script: https://mswjs.io/docs/cli/init`),
+      )
+    }
+
+    // Fallback error message for any other registration errors.
+    throw new Error(
+      devUtils.formatMessage(
+        'Failed to register the Service Worker:\n\n%s',
+        registrationError.message,
+      ),
+    )
+  }
+
+  return registrationResult
+}

package/src/browser/setupWorker/start/utils/prepareStartHandler.test.ts

@@ -0,0 +1,59 @@
+import { SetupWorkerInternalContext, StartOptions } from '../../glossary'
+import {
+  DEFAULT_START_OPTIONS,
+  resolveStartOptions,
+  prepareStartHandler,
+} from './prepareStartHandler'
+
+describe('resolveStartOptions', () => {
+  test('returns default options given no custom start options', () => {
+    expect(resolveStartOptions()).toEqual(DEFAULT_START_OPTIONS)
+    expect(resolveStartOptions(undefined)).toEqual(DEFAULT_START_OPTIONS)
+    expect(resolveStartOptions({})).toEqual(DEFAULT_START_OPTIONS)
+  })
+
+  test('deeply merges the default and custom start options', () => {
+    expect(
+      resolveStartOptions({
+        quiet: true,
+        serviceWorker: {
+          url: './custom.js',
+        },
+      }),
+    ).toEqual({
+      ...DEFAULT_START_OPTIONS,
+      quiet: true,
+      serviceWorker: {
+        url: './custom.js',
+        options: null,
+      },
+    })
+  })
+})
+
+describe('prepareStartHandler', () => {
+  test('exposes resolved start options to the generated star handler', () => {
+    const createStartHandler = vi.fn()
+    const context: SetupWorkerInternalContext = {} as any
+    const startHandler = prepareStartHandler(createStartHandler, context)
+    expect(startHandler).toBeInstanceOf(Function)
+
+    const initialOptions: StartOptions = {
+      quiet: true,
+      serviceWorker: {
+        url: './custom.js',
+      },
+    }
+    const resolvedOptions = resolveStartOptions(initialOptions)
+    startHandler(initialOptions)
+
+    // Calls the handler creator with both resolved and initial options.
+    expect(createStartHandler).toHaveBeenCalledWith(
+      resolvedOptions,
+      initialOptions,
+    )
+
+    // Sets the resolved options on the internal context.
+    expect(context).toHaveProperty('startOptions', resolvedOptions)
+  })
+})

package/src/browser/setupWorker/start/utils/prepareStartHandler.ts

@@ -0,0 +1,44 @@
+import { RequiredDeep } from '~/core/typeUtils'
+import { mergeRight } from '~/core/utils/internal/mergeRight'
+import {
+  SetupWorker,
+  SetupWorkerInternalContext,
+  StartHandler,
+  StartOptions,
+} from '../../glossary'
+
+export const DEFAULT_START_OPTIONS: RequiredDeep<StartOptions> = {
+  serviceWorker: {
+    url: '/mockServiceWorker.js',
+    options: null as any,
+  },
+  quiet: false,
+  waitUntilReady: true,
+  onUnhandledRequest: 'warn',
+  findWorker(scriptURL, mockServiceWorkerUrl) {
+    return scriptURL === mockServiceWorkerUrl
+  },
+}
+
+/**
+ * Returns resolved worker start options, merging the default options
+ * with the given custom options.
+ */
+export function resolveStartOptions(
+  initialOptions?: StartOptions,
+): RequiredDeep<StartOptions> {
+  return mergeRight(
+    DEFAULT_START_OPTIONS,
+    initialOptions || {},
+  ) as RequiredDeep<StartOptions>
+}
+
+export function prepareStartHandler(
+  handler: StartHandler,
+  context: SetupWorkerInternalContext,
+): SetupWorker['start'] {
+  return (initialOptions) => {
+    context.startOptions = resolveStartOptions(initialOptions)
+    return handler(context.startOptions, initialOptions || {})
+  }
+}

package/src/browser/setupWorker/start/utils/printStartMessage.test.ts

@@ -0,0 +1,84 @@
+import { printStartMessage } from './printStartMessage'
+
+beforeEach(() => {
+  vi.spyOn(console, 'groupCollapsed').mockImplementation(() => void 0)
+  vi.spyOn(console, 'log').mockImplementation(() => void 0)
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+test('prints out a default start message into console', () => {
+  printStartMessage({
+    workerScope: 'http://localhost:3000/',
+    workerUrl: 'http://localhost:3000/worker.js',
+  })
+
+  expect(console.groupCollapsed).toHaveBeenCalledWith(
+    '%c[MSW] Mocking enabled.',
+    expect.anything(),
+  )
+
+  // Includes a link to the documentation.
+  expect(console.log).toHaveBeenCalledWith(
+    '%cDocumentation: %chttps://mswjs.io/docs',
+    expect.anything(),
+    expect.anything(),
+  )
+
+  // Includes a link to the GitHub issues page.
+  expect(console.log).toHaveBeenCalledWith(
+    'Found an issue? https://github.com/mswjs/msw/issues',
+  )
+
+  // Includes service worker scope.
+  expect(console.log).toHaveBeenCalledWith(
+    'Worker scope:',
+    'http://localhost:3000/',
+  )
+
+  // Includes service worker script location.
+  expect(console.log).toHaveBeenCalledWith(
+    'Worker script URL:',
+    'http://localhost:3000/worker.js',
+  )
+})
+
+test('supports printing a custom start message', () => {
+  printStartMessage({ message: 'Custom start message' })
+
+  expect(console.groupCollapsed).toHaveBeenCalledWith(
+    '%c[MSW] Custom start message',
+    expect.anything(),
+  )
+})
+
+test('does not print any messages when log level is quiet', () => {
+  printStartMessage({ quiet: true })
+
+  expect(console.groupCollapsed).not.toHaveBeenCalled()
+  expect(console.log).not.toHaveBeenCalled()
+})
+
+test('prints a worker scope in the start message', () => {
+  printStartMessage({
+    workerScope: 'http://localhost:3000/user',
+  })
+
+  expect(console.log).toHaveBeenCalledWith(
+    'Worker scope:',
+    'http://localhost:3000/user',
+  )
+})
+
+test('prints a worker script url in the start message', () => {
+  printStartMessage({
+    workerUrl: 'http://localhost:3000/mockServiceWorker.js',
+  })
+
+  expect(console.log).toHaveBeenCalledWith(
+    'Worker script URL:',
+    'http://localhost:3000/mockServiceWorker.js',
+  )
+})

package/src/browser/setupWorker/start/utils/printStartMessage.ts

@@ -0,0 +1,51 @@
+import type { ServiceWorkerIncomingEventsMap } from '../../glossary'
+import { devUtils } from '~/core/utils/internal/devUtils'
+
+interface PrintStartMessageArgs {
+  quiet?: boolean
+  message?: string
+  workerUrl?: string
+  workerScope?: string
+  client?: ServiceWorkerIncomingEventsMap['MOCKING_ENABLED']['client']
+}
+
+/**
+ * Prints a worker activation message in the browser's console.
+ */
+export function printStartMessage(args: PrintStartMessageArgs = {}) {
+  if (args.quiet) {
+    return
+  }
+
+  const message = args.message || 'Mocking enabled.'
+
+  console.groupCollapsed(
+    `%c${devUtils.formatMessage(message)}`,
+    'color:orangered;font-weight:bold;',
+  )
+  // eslint-disable-next-line no-console
+  console.log(
+    '%cDocumentation: %chttps://mswjs.io/docs',
+    'font-weight:bold',
+    'font-weight:normal',
+  )
+  // eslint-disable-next-line no-console
+  console.log('Found an issue? https://github.com/mswjs/msw/issues')
+
+  if (args.workerUrl) {
+    // eslint-disable-next-line no-console
+    console.log('Worker script URL:', args.workerUrl)
+  }
+
+  if (args.workerScope) {
+    // eslint-disable-next-line no-console
+    console.log('Worker scope:', args.workerScope)
+  }
+
+  if (args.client) {
+    // eslint-disable-next-line no-console
+    console.log('Client ID: %s (%s)', args.client.id, args.client.frameType)
+  }
+
+  console.groupEnd()
+}

package/src/browser/setupWorker/start/utils/validateWorkerScope.ts

@@ -0,0 +1,18 @@
+import { devUtils } from '~/core/utils/internal/devUtils'
+import { StartOptions } from '../../glossary'
+
+export function validateWorkerScope(
+  registration: ServiceWorkerRegistration,
+  options?: StartOptions,
+): void {
+  if (!options?.quiet && !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/setupWorker/stop/utils/printStopMessage.test.ts

@@ -0,0 +1,26 @@
+import { printStopMessage } from './printStopMessage'
+
+beforeAll(() => {
+  vi.spyOn(global.console, 'log').mockImplementation(() => void 0)
+})
+
+afterEach(() => {
+  vi.resetAllMocks()
+})
+
+afterAll(() => {
+  vi.restoreAllMocks()
+})
+
+test('prints a stop message to the console', () => {
+  printStopMessage()
+  expect(console.log).toHaveBeenCalledWith(
+    '%c[MSW] Mocking disabled.',
+    'color:orangered;font-weight:bold;',
+  )
+})
+
+test('does not print any message when log level is quiet', () => {
+  printStopMessage({ quiet: true })
+  expect(console.log).not.toHaveBeenCalled()
+})

package/src/browser/setupWorker/stop/utils/printStopMessage.ts

@@ -0,0 +1,13 @@
+import { devUtils } from '~/core/utils/internal/devUtils'
+
+export function printStopMessage(args: { quiet?: boolean } = {}): void {
+  if (args.quiet) {
+    return
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(
+    `%c${devUtils.formatMessage('Mocking disabled.')}`,
+    'color:orangered;font-weight:bold;',
+  )
+}

package/src/browser/tsconfig.browser.build.json

@@ -0,0 +1,6 @@
+{
+  "extends": "./tsconfig.browser.json",
+  "compilerOptions": {
+    "composite": false
+  }
+}

package/src/browser/tsconfig.browser.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.src.json",
+  "compilerOptions": {
+    // Expose browser-specific libraries only for the
+    // source code under the "src/browser" directory.
+    "lib": ["DOM", "WebWorker", "DOM.Iterable"]
+  },
+  "include": ["../../global.d.ts", "./global.browser.d.ts", "./**/*.ts"]
+}

package/src/browser/utils/checkWorkerIntegrity.ts

@@ -0,0 +1,42 @@
+import { devUtils } from '~/core/utils/internal/devUtils'
+import type { SetupWorkerInternalContext } from '../setupWorker/glossary'
+import { DeferredPromise } from '@open-draft/deferred-promise'
+
+/**
+ * Check whether the registered Service Worker has been
+ * generated by the installed version of the library.
+ * Prints a warning message if the worker scripts mismatch.
+ */
+export function checkWorkerIntegrity(
+  context: SetupWorkerInternalContext,
+): Promise<void> {
+  const integrityCheckPromise = new DeferredPromise<void>()
+
+  // Request the integrity checksum from the registered worker.
+  context.workerChannel.postMessage('INTEGRITY_CHECK_REQUEST')
+  context.workerChannel.once('INTEGRITY_CHECK_RESPONSE', (event) => {
+    const { checksum, packageVersion } = event.data
+
+    // Compare the response from the Service Worker and the
+    // global variable set during the build.
+
+    // The integrity is validated based on the worker script's checksum
+    // that's derived from its minified content during the build.
+    // The "SERVICE_WORKER_CHECKSUM" global variable is injected by the build.
+    if (checksum !== SERVICE_WORKER_CHECKSUM) {
+      devUtils.warn(
+        `The currently registered Service Worker has been generated by a different version of MSW (${packageVersion}) and may not be fully compatible with the installed version.
+
+It's recommended you update your worker script by running this command:
+
+  \u2022 npx msw init <PUBLIC_DIR>
+
+You can also automate this process and make the worker script update automatically upon the library installations. Read more: https://mswjs.io/docs/cli/init.`,
+      )
+    }
+
+    integrityCheckPromise.resolve()
+  })
+
+  return integrityCheckPromise
+}

package/src/browser/utils/deserializeRequest.ts

@@ -0,0 +1,15 @@
+import { pruneGetRequestBody } from './pruneGetRequestBody'
+import type { ServiceWorkerIncomingRequest } from '../setupWorker/glossary'
+
+/**
+ * Converts a given request received from the Service Worker
+ * into a Fetch `Request` instance.
+ */
+export function deserializeRequest(
+  serializedRequest: ServiceWorkerIncomingRequest,
+): Request {
+  return new Request(serializedRequest.url, {
+    ...serializedRequest,
+    body: pruneGetRequestBody(serializedRequest),
+  })
+}

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

@@ -0,0 +1,29 @@
+// @vitest-environment jsdom
+import { getAbsoluteWorkerUrl } from './getAbsoluteWorkerUrl'
+
+const rawLocation = window.location
+
+afterAll(() => {
+  Object.defineProperty(window, 'location', {
+    value: rawLocation,
+  })
+})
+
+it('returns absolute worker url relatively to the root', () => {
+  expect(getAbsoluteWorkerUrl('./worker.js')).toBe('http://localhost/worker.js')
+})
+
+it('returns an absolute worker url relatively to the current path', () => {
+  Object.defineProperty(window, 'location', {
+    value: {
+      href: 'http://localhost/path/to/page',
+    },
+  })
+
+  expect(getAbsoluteWorkerUrl('./worker.js')).toBe(
+    'http://localhost/path/to/worker.js',
+  )
+
+  // Leading slash must still resolve to the root.
+  expect(getAbsoluteWorkerUrl('/worker.js')).toBe('http://localhost/worker.js')
+})

package/src/browser/utils/getAbsoluteWorkerUrl.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns an absolute Service Worker URL based on the given
+ * relative URL (known during the registration).
+ */
+export function getAbsoluteWorkerUrl(workerUrl: string): string {
+  return new URL(workerUrl, location.href).href
+}

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

@@ -0,0 +1,53 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { TextEncoder } from 'util'
+import { pruneGetRequestBody } from './pruneGetRequestBody'
+
+test('sets empty GET request body to undefined', () => {
+  expect(
+    pruneGetRequestBody({
+      method: 'GET',
+    }),
+  ).toBeUndefined()
+
+  expect(
+    pruneGetRequestBody({
+      method: 'GET',
+      // There's no such thing as a GET request with a body.
+      body: new ArrayBuffer(5),
+    }),
+  ).toBeUndefined()
+})
+
+test('sets HEAD request body to undefined', () => {
+  expect(
+    pruneGetRequestBody({
+      method: 'HEAD',
+    }),
+  ).toBeUndefined()
+
+  expect(
+    pruneGetRequestBody({
+      method: 'HEAD',
+      body: new ArrayBuffer(5),
+    }),
+  ).toBeUndefined()
+})
+
+test('ignores requests of the other methods than GET', () => {
+  const body = new TextEncoder().encode('hello world')
+  expect(
+    pruneGetRequestBody({
+      method: 'POST',
+      body,
+    }),
+  ).toEqual(body)
+
+  expect(
+    pruneGetRequestBody({
+      method: 'PUT',
+      body,
+    }),
+  ).toEqual(body)
+})

package/src/browser/utils/pruneGetRequestBody.ts

@@ -0,0 +1,21 @@
+import type { ServiceWorkerIncomingRequest } from '../setupWorker/glossary'
+
+type Input = Pick<ServiceWorkerIncomingRequest, 'method' | 'body'>
+
+/**
+ * Ensures that an empty GET request body is always represented as `undefined`.
+ */
+export function pruneGetRequestBody(
+  request: Input,
+): ServiceWorkerIncomingRequest['body'] {
+  // Force HEAD/GET request body to always be empty.
+  // The worker reads any request's body as ArrayBuffer,
+  // and you cannot re-construct a GET/HEAD Request
+  // with an ArrayBuffer, even if empty. Also note that
+  // "request.body" is always undefined in the worker.
+  if (['HEAD', 'GET'].includes(request.method)) {
+    return undefined
+  }
+
+  return request.body
+}

package/src/browser/utils/supports.ts

@@ -0,0 +1,30 @@
+/**
+ * Checks if the Service Worker API is supproted and available
+ * in the current browsing context.
+ */
+export function supportsServiceWorker(): boolean {
+  return (
+    typeof navigator !== 'undefined' &&
+    'serviceWorker' in navigator &&
+    typeof location !== 'undefined' &&
+    location.protocol !== 'file:'
+  )
+}
+
+/**
+ * Returns a boolean indicating whether the current browser
+ * supports `ReadableStream` as a `Transferable` when posting
+ * messages.
+ */
+export function supportsReadableStreamTransfer() {
+  try {
+    const stream = new ReadableStream({
+      start: (controller) => controller.close(),
+    })
+    const message = new MessageChannel()
+    message.port1.postMessage(stream, [stream])
+    return true
+  } catch {
+    return false
+  }
+}