feat(experimental): migrate to the network source architecture (defineNetwork)

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: 'pnpm'
 
       - name: Install dependencies
@@ -93,7 +93,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: 'pnpm'
 
       - name: Restore build cache
@@ -129,7 +129,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: 'pnpm'
 
       - name: Restore build cache
@@ -195,7 +195,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: 'pnpm'
 
       - name: Install dependencies
@@ -220,7 +220,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: 'pnpm'
 
       - name: Restore build cache
@@ -263,7 +263,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: 'pnpm'
 
       - name: Restore build cache

.github/workflows/compat.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Set up pnpm
         uses: pnpm/action-setup@v4
@@ -62,7 +62,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
 
       - uses: pnpm/action-setup@v4
         with:

.github/workflows/release-preview.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Set up pnpm
         uses: pnpm/action-setup@v4

.github/workflows/smoke-test.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Set up pnpm
         uses: pnpm/action-setup@v4

.github/workflows/typescript-nightly.yml

@@ -13,7 +13,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Get latest TypeScript version
         id: get-versions
@@ -42,7 +42,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Set up pnpm
         uses: pnpm/action-setup@v4

.nvmrc

@@ -1 +1 @@
-v20
+v22

config/replaceCoreImports.js

@@ -1,5 +1,5 @@
-const CORE_ESM_IMPORT_PATTERN = /from ["'](~\/core(.*))["'](;)?/gm
-const CORE_CJS_IMPORT_PATTERN = /require\(["'](~\/core(.*))["']\)(;)?/gm
+const CORE_ESM_IMPORT_PATTERN = /from ["'](#core(.*))["'](;)?/gm
+const CORE_CJS_IMPORT_PATTERN = /require\(["'](#core(.*))["']\)(;)?/gm
 
 function getCoreImportPattern(isEsm) {
   return isEsm ? CORE_ESM_IMPORT_PATTERN : CORE_CJS_IMPORT_PATTERN

config/scripts/patch-ts.js

@@ -29,13 +29,13 @@ async function patchTypeDefs() {
 
   if (typeDefsWithCoreImports.length === 0) {
     console.log(
-      'Found no .d.ts modules containing the "~/core" import, skipping...',
+      'Found no .d.ts modules containing the "#core" import, skipping...',
     )
     return process.exit(0)
   }
 
   console.log(
-    'Found %d module(s) with the "~/core" import, resolving...',
+    'Found %d module(s) with the "#core" import, resolving...',
     typeDefsWithCoreImports.length,
   )
 
@@ -56,9 +56,9 @@ async function patchTypeDefs() {
     typeDefsWithCoreImports.length,
   )
 
-  // Next, validate that we left no "~/core" imports unresolved.
+  // Next, validate that we left no "#core" imports unresolved.
   const result = await execAsync(
-    `grep "~/core" ./**/*.d.{ts,mts} -R -l || exit 0`,
+    `grep "#core" ./**/*.d.{ts,mts} -R -l || exit 0`,
     {
       cwd: BUILD_DIR,
       shell: '/bin/bash',
@@ -67,7 +67,7 @@ async function patchTypeDefs() {
 
   invariant(
     result.stderr === '',
-    'Failed to validate the .d.ts modules for the presence of the "~/core" import. See the original error below.',
+    'Failed to validate the .d.ts modules for the presence of the "#core" import. See the original error below.',
     result.stderr,
   )
 
@@ -77,7 +77,7 @@ async function patchTypeDefs() {
       .filter(Boolean)
 
     console.error(
-      `Found .d.ts modules containing unresolved "~/core" import after the patching:
+      `Found .d.ts modules containing unresolved "#core" import after the patching:
 
 ${modulesWithUnresolvedImports.map((path) => `  - ${new URL(path, BUILD_DIR).pathname}`).join('\n')}
         `,
@@ -86,7 +86,7 @@ ${modulesWithUnresolvedImports.map((path) => `  - ${new URL(path, BUILD_DIR).pat
     return process.exit(1)
   }
 
-  // Ensure that the .d.ts files compile without errors after resolving the "~/core" imports.
+  // Ensure that the .d.ts files compile without errors after resolving the "#core" imports.
   console.log('Compiling the .d.ts modules with tsc...')
   const tscCompilation = await execAsync(
     `tsc --noEmit --skipLibCheck ${typeDefsPaths.join(' ')}`,
@@ -135,7 +135,7 @@ ${modulesWithUnresolvedImports.map((path) => `  - ${new URL(path, BUILD_DIR).pat
   }
 
   console.log(
-    'The "~/core" imports resolved successfully in %d .d.ts modules! 🎉',
+    'The "#core" imports resolved successfully in %d .d.ts modules! 🎉',
     typeDefsWithCoreImports.length,
   )
 }

package.json

@@ -159,9 +159,22 @@
         "default": "./lib/core/ws.js"
       }
     },
+    "./experimental": {
+      "import": {
+        "types": "./lib/core/experimental/index.d.mts",
+        "default": "./lib/core/experimental/index.mjs"
+      },
+      "default": {
+        "types": "./lib/core/experimental/index.d.ts",
+        "default": "./lib/core/experimental/index.js"
+      }
+    },
     "./mockServiceWorker.js": "./lib/mockServiceWorker.js",
     "./package.json": "./package.json"
   },
+  "imports": {
+    "#core": "./src/core"
+  },
   "bin": {
     "msw": "cli/index.js"
   },

src/browser/setupWorker/glossary.ts → src/browser/glossary.ts

@@ -1,33 +1,13 @@
-import { Emitter } from 'strict-event-emitter'
-import type { HttpRequestEventMap, Interceptor } from '@mswjs/interceptors'
-import type { DeferredPromise } from '@open-draft/deferred-promise'
-import {
-  LifeCycleEventEmitter,
-  LifeCycleEventsMap,
-  SharedOptions,
-} from '~/core/sharedOptions'
-import { RequestHandler } from '~/core/handlers/RequestHandler'
-import type { RequiredDeep } from '~/core/typeUtils'
-import type { WebSocketHandler } from '~/core/handlers/WebSocketHandler'
-import type { WorkerChannel } from '../utils/workerChannel'
+import type { LifeCycleEventEmitter, SharedOptions } from '#core/sharedOptions'
+import type { RequiredDeep } from '#core/typeUtils'
+import type { HttpNetworkFrameEventMap } from '#core/experimental/frames/http-frame'
+import type { WebSocketNetworkFrameEventMap } from '#core/experimental/frames/websocket-frame'
+import { AnyHandler } from '#core/experimental/handlers-controller'
 
 export interface StringifiedResponse extends ResponseInit {
   body: string | ArrayBuffer | ReadableStream<Uint8Array> | null
 }
 
-export type SetupWorkerInternalContext = {
-  isMockingEnabled: boolean
-  workerStoppedAt?: number
-  startOptions: RequiredDeep<StartOptions>
-  workerPromise: DeferredPromise<ServiceWorker>
-  registration: ServiceWorkerRegistration | undefined
-  getRequestHandlers: () => Array<RequestHandler | WebSocketHandler>
-  emitter: Emitter<LifeCycleEventsMap>
-  keepAliveInterval?: number
-  workerChannel: WorkerChannel
-  fallbackInterceptor?: Interceptor<HttpRequestEventMap>
-}
-
 export type ServiceWorkerInstanceTuple = [
   ServiceWorker | null,
   ServiceWorkerRegistration,
@@ -62,6 +42,7 @@ export interface StartOptions extends SharedOptions {
    * Defers any network requests until the Service Worker
    * instance is activated.
    * @default true
+   * @deprecated
    */
   waitUntilReady?: boolean
 
@@ -81,6 +62,9 @@ export type StartHandler = (
 
 export type StopHandler = () => void
 
+/**
+ * @deprecated Use the `SetupWorkerApi` type instead.
+ */
 export interface SetupWorker {
   /**
    * Registers and activates the mock Service Worker.
@@ -98,11 +82,11 @@ export interface SetupWorker {
 
   /**
    * Prepends given request handlers to the list of existing handlers.
-   * @param {RequestHandler[]} handlers List of runtime request handlers.
+   * @param {Array<AnyHandler>} handlers List of runtime request handlers.
    *
    * @see {@link https://mswjs.io/docs/api/setup-worker/use `worker.use()` API reference}
    */
-  use: (...handlers: Array<RequestHandler | WebSocketHandler>) => void
+  use: (...handlers: Array<AnyHandler>) => void
 
   /**
    * Marks all request handlers that respond using `res.once()` as unused.
@@ -113,26 +97,26 @@ export interface SetupWorker {
 
   /**
    * Resets request handlers to the initial list given to the `setupWorker` call, or to the explicit next request handlers list, if given.
-   * @param {RequestHandler[]} nextHandlers List of the new initial request handlers.
+   * @param {Array<AnyHandler>} nextHandlers List of the new initial request handlers.
    *
    * @see {@link https://mswjs.io/docs/api/setup-worker/reset-handlers `worker.resetHandlers()` API reference}
    */
-  resetHandlers: (
-    ...nextHandlers: Array<RequestHandler | WebSocketHandler>
-  ) => void
+  resetHandlers: (...nextHandlers: Array<AnyHandler>) => void
 
   /**
    * Returns a readonly list of currently active request handlers.
    *
    * @see {@link https://mswjs.io/docs/api/setup-worker/list-handlers `worker.listHandlers()` API reference}
    */
-  listHandlers(): ReadonlyArray<RequestHandler | WebSocketHandler>
+  listHandlers: () => ReadonlyArray<AnyHandler>
 
   /**
    * Life-cycle events.
    * Life-cycle events allow you to subscribe to the internal library events occurring during the request/response handling.
    *
    * @see {@link https://mswjs.io/docs/api/life-cycle-events Life-cycle Events API reference}
    */
-  events: LifeCycleEventEmitter<LifeCycleEventsMap>
+  events: LifeCycleEventEmitter<
+    HttpNetworkFrameEventMap | WebSocketNetworkFrameEventMap
+  >
 }

src/browser/index.ts

@@ -1,3 +1,2 @@
-export { setupWorker } from './setupWorker/setupWorker'
-export type { SetupWorker, StartOptions } from './setupWorker/glossary'
-export { SetupWorkerApi } from './setupWorker/setupWorker'
+export { setupWorker, type SetupWorkerApi } from './setup-worker'
+export type { SetupWorker, StartOptions } from './glossary'

src/browser/setupWorker/setupWorker.node.test.ts → src/browser/setup-worker.node.test.ts

@@ -1,7 +1,5 @@
-/**
- * @vitest-environment node
- */
-import { setupWorker } from './setupWorker'
+// @vitest-environment node
+import { setupWorker } from './setup-worker'
 
 test('returns an error when run in a Node.js environment', () => {
   expect(setupWorker).toThrow(