fix: implement setupServer and SetupServerCommonApi

Author: kettanaito

package.json

@@ -248,7 +248,7 @@
     "outvariant": "^1.4.3",
     "path-to-regexp": "^6.3.0",
     "picocolors": "^1.1.1",
-    "rettime": "^0.7.0",
+    "rettime": "^0.9.0",
     "statuses": "^2.0.2",
     "strict-event-emitter": "^0.5.1",
     "tough-cookie": "^6.0.0",

pnpm-lock.yaml

@@ -92,6 +92,13 @@ export { bypass } from './bypass'
 export { passthrough } from './passthrough'
 export { isCommonAssetRequest } from './isCommonAssetRequest'
 
+export { defineNetwork, type NetworkApi } from './new/define-network'
+export {
+  type AnyHandler,
+  HandlersController,
+  InMemoryHandlersController,
+} from './new/handlers-controller'
+
 // Validate environmental globals before executing any code.
 // This ensures that the library gives user-friendly errors
 // when ran in the environments that require additional polyfills

src/core/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Collection of helpers for briding the compatibility between the old and the new APIs.
+ */
+import { Emitter } from 'rettime'
+import {
+  Emitter as LegacyEmitter,
+  EventMap as LegacyEventMap,
+} from 'strict-event-emitter'
+import { type UnhandledRequestStrategy } from '~/core/utils/request/onUnhandledRequest'
+import {
+  onUnhandledFrame,
+  type UnhandledFrameCallback,
+} from './on-unhandled-frame'
+
+export function toLegacyEmitter<EventMap extends LegacyEventMap>(
+  emitter: Emitter<any>,
+): LegacyEmitter<EventMap> {
+  const legacy = new LegacyEmitter<EventMap>()
+
+  legacy
+    .addListener('newListener', (type, listener) => {
+      emitter.on(type as any, (event) => listener(event.data))
+    })
+    .addListener('removeListener', (type, listener) => {
+      emitter.removeListener(type as any, listener)
+    })
+
+  return legacy
+}
+
+export function fromLegacyOnUnhandledRequest(
+  getLegacyValue: () => UnhandledRequestStrategy | undefined,
+): UnhandledFrameCallback {
+  return ({ frame, defaults }) => {
+    const legacyOnUnhandledRequestStrategy = getLegacyValue()
+
+    if (legacyOnUnhandledRequestStrategy === undefined) {
+      return
+    }
+
+    if (typeof legacyOnUnhandledRequestStrategy === 'function') {
+      const request =
+        frame.protocol === 'http'
+          ? frame.data.request
+          : new Request(frame.data.connection.client.url, {
+              headers: {
+                connection: 'upgrade',
+                upgrade: 'websocket',
+              },
+            })
+
+      return legacyOnUnhandledRequestStrategy(request, {
+        warning: defaults.warn,
+        error: defaults.error,
+      })
+    }
+
+    return onUnhandledFrame(frame, legacyOnUnhandledRequestStrategy)
+  }
+}

src/core/new/compat.ts

@@ -1,7 +1,5 @@
 import { Emitter } from 'rettime'
 import { type NetworkSource } from './sources/network-source'
-
-import { pipeEvents } from '../utils/internal/pipeEvents'
 import { type NetworkFrameResolutionContext } from './frames/network-frame'
 import { onUnhandledFrame, UnhandledFrameHandle } from './on-unhandled-frame'
 import { isHandlerKind } from '../utils/internal/isHandlerKind'
@@ -23,13 +21,14 @@ export interface DefineNetworkOptions {
 export interface NetworkApi extends NetworkHandlersApi {
   enable: () => Promise<void>
   disable: () => Promise<void>
+  events: Emitter<any>
 }
 
 export interface NetworkHandlersApi {
   use: (...handlers: Array<AnyHandler>) => void
   resetHandlers: (...handlers: Array<AnyHandler>) => void
   restoreHandlers: () => void
-  listHandlers: () => void
+  listHandlers: () => ReadonlyArray<AnyHandler>
 }
 
 export function defineNetwork(options: DefineNetworkOptions): NetworkApi {
@@ -38,11 +37,17 @@ export function defineNetwork(options: DefineNetworkOptions): NetworkApi {
     options.controller || new InMemoryHandlersController(options.handlers || [])
 
   return {
+    events,
     async enable() {
       await Promise.all(
         options.sources.map(async (source) => {
           source.on('frame', async ({ data: frame }) => {
-            pipeEvents(frame.events, events)
+            /**
+             * @fixme Rettime has trouble typing `.on` when the emitter
+             * has a union of eventmap types. Add a type test and a runtime test
+             * for this use case (piping events).
+             */
+            frame.events.on((event) => events.emit(event))
 
             const handlerPredicate =
               frame.protocol === 'http'

src/core/new/define-network.ts

@@ -1,4 +1,3 @@
-import { UnhandledRequestStrategy } from 'src/iife'
 import { isCommonAssetRequest } from '../isCommonAssetRequest'
 import { devUtils, InternalError } from '../utils/internal/devUtils'
 import { type NetworkFrame } from './sources/network-source'
@@ -76,34 +75,3 @@ export async function onUnhandledFrame(
 
   return applyStrategy(handle)
 }
-
-export function fromLegacyOnUnhandledRequest(
-  getLegacyValue: () => UnhandledRequestStrategy | undefined,
-): UnhandledFrameCallback {
-  return ({ frame, defaults }) => {
-    const legacyOnUnhandledRequestStrategy = getLegacyValue()
-
-    if (legacyOnUnhandledRequestStrategy === undefined) {
-      return
-    }
-
-    if (typeof legacyOnUnhandledRequestStrategy === 'function') {
-      const request =
-        frame.protocol === 'http'
-          ? frame.data.request
-          : new Request(frame.data.connection.client.url, {
-              headers: {
-                connection: 'upgrade',
-                upgrade: 'websocket',
-              },
-            })
-
-      return legacyOnUnhandledRequestStrategy(request, {
-        warning: defaults.warn,
-        error: defaults.error,
-      })
-    }
-
-    return onUnhandledFrame(frame, legacyOnUnhandledRequestStrategy)
-  }
-}

src/core/new/on-unhandled-frame.ts

@@ -0,0 +1,48 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { AnyHandler, HandlersController } from '~/core/index'
+
+export interface AsyncHandlersControllerContext {
+  initialHandlers: Array<AnyHandler>
+  handlers: Array<AnyHandler>
+}
+
+export class AsyncHandlersController extends HandlersController {
+  public context: AsyncLocalStorage<AsyncHandlersControllerContext>
+  #fallbackContext: AsyncHandlersControllerContext
+
+  constructor(initialHandlers: Array<AnyHandler>) {
+    super(initialHandlers)
+
+    this.context = new AsyncLocalStorage()
+    this.#fallbackContext = {
+      initialHandlers: [...initialHandlers],
+      handlers: [],
+    }
+  }
+
+  get currentHandlers() {
+    const { initialHandlers, handlers } = this.#getContext()
+    return [...initialHandlers, ...handlers]
+  }
+
+  public use(nextHandlers: Array<AnyHandler>): void {
+    super.use(nextHandlers)
+
+    this.#getContext().handlers.unshift(...nextHandlers)
+  }
+
+  public reset(nextHandlers: Array<AnyHandler>): void {
+    super.reset(nextHandlers)
+
+    const context = this.#getContext()
+    context.handlers = []
+
+    if (nextHandlers.length > 0) {
+      context.initialHandlers = [...nextHandlers]
+    }
+  }
+
+  #getContext() {
+    return this.context.getStore() || this.#fallbackContext
+  }
+}

src/node/async-handlers-controller.ts

@@ -1,19 +1,20 @@
 import type { PartialDeep } from 'type-fest'
-import type { RequestHandler } from '~/core/handlers/RequestHandler'
-import type { WebSocketHandler } from '~/core/handlers/WebSocketHandler'
+import { AnyHandler } from '~/core'
 import type {
   LifeCycleEventEmitter,
   LifeCycleEventsMap,
   SharedOptions,
 } from '~/core/sharedOptions'
 
+export interface ListenOptions extends SharedOptions {}
+
 export interface SetupServerCommon {
   /**
    * Starts requests interception based on the previously provided request handlers.
    *
    * @see {@link https://mswjs.io/docs/api/setup-server/listen `server.listen()` API reference}
    */
-  listen(options?: PartialDeep<SharedOptions>): void
+  listen(options?: PartialDeep<ListenOptions>): void
 
   /**
    * Stops requests interception by restoring all augmented modules.
@@ -27,7 +28,7 @@ export interface SetupServerCommon {
    *
    * @see {@link https://mswjs.io/docs/api/setup-server/use `server.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.
@@ -41,14 +42,14 @@ export interface SetupServerCommon {
    *
    * @see {@link https://mswjs.io/docs/api/setup-server/reset-handlers `server.reset-handlers()` 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-server/list-handlers `server.listHandlers()` API reference}
    */
-  listHandlers(): ReadonlyArray<RequestHandler | WebSocketHandler>
+  listHandlers(): ReadonlyArray<AnyHandler>
 
   /**
    * Life-cycle events.

src/node/glossary.ts

@@ -0,0 +1,65 @@
+import type { PartialDeep } from 'type-fest'
+import { Interceptor } from '@mswjs/interceptors'
+import { ListenOptions, SetupServerCommon } from './glossary'
+import {
+  AnyHandler,
+  defineNetwork,
+  LifeCycleEventsMap,
+  NetworkApi,
+} from '~/core'
+import { HandlersController } from '~/core/new/handlers-controller'
+import { InterceptorSource } from '~/core/new/sources/interceptor-source'
+import {
+  fromLegacyOnUnhandledRequest,
+  toLegacyEmitter,
+} from '~/core/new/compat'
+
+export class SetupServerCommonApi implements SetupServerCommon {
+  #listenOptions?: PartialDeep<ListenOptions>
+
+  protected network: NetworkApi
+
+  constructor(
+    interceptors: Array<Interceptor<any>>,
+    handlers: Array<AnyHandler>,
+    handlersController?: HandlersController,
+  ) {
+    this.network = defineNetwork({
+      sources: [new InterceptorSource({ interceptors })],
+      handlers,
+      controller: handlersController,
+      onUnhandledFrame: fromLegacyOnUnhandledRequest(() => {
+        return this.#listenOptions?.onUnhandledRequest || 'warn'
+      }),
+    })
+  }
+
+  get events() {
+    return toLegacyEmitter<LifeCycleEventsMap>(this.network.events)
+  }
+
+  public listen(options?: PartialDeep<ListenOptions>): void {
+    this.#listenOptions = options
+    this.network.enable()
+  }
+
+  public use(...handlers: Array<AnyHandler>): void {
+    this.network.use(...handlers)
+  }
+
+  public resetHandlers(...nextHandlers: Array<AnyHandler>): void {
+    return this.network.resetHandlers(...nextHandlers)
+  }
+
+  public restoreHandlers(): void {
+    return this.network.restoreHandlers()
+  }
+
+  public listHandlers(): ReadonlyArray<AnyHandler> {
+    return this.network.listHandlers()
+  }
+
+  public close(): void {
+    this.network.disable()
+  }
+}