feat: custom request predicate function

src/core/graphql.ts

@@ -11,6 +11,7 @@ import {
   GraphQLResolverExtras,
   GraphQLResponseBody,
   GraphQLQuery,
+  GraphQLCustomPredicate,
 } from './handlers/GraphQLHandler'
 import type { Path } from './utils/matching/matchRequestUrl'
 
@@ -30,7 +31,8 @@ export type GraphQLRequestHandler = <
   operationName:
     | GraphQLHandlerNameSelector
     | DocumentNode
-    | TypedDocumentNode<Query, Variables>,
+    | TypedDocumentNode<Query, Variables>
+    | GraphQLCustomPredicate<GraphQLVariables>,
   resolver: GraphQLResponseResolver<
     [Query] extends [never] ? GraphQLQuery : Query,
     Variables
@@ -52,6 +54,12 @@ function createScopedGraphQLHandler(
   url: Path,
 ): GraphQLRequestHandler {
   return (operationName, resolver, options = {}) => {
+    if (typeof operationName === 'function') {
+      return new GraphQLHandler(operationType, '', url, resolver, {
+        ...options,
+        predicate: operationName,
+      })
+    }
     return new GraphQLHandler(
       operationType,
       operationName,

src/core/handlers/GraphQLHandler.test.ts

@@ -557,13 +557,13 @@ describe('predicate', () => {
     })
 
     expect(
-      handler.predicate({
+      await handler.predicate({
         request,
         parsedResult: await handler.parse({ request }),
       }),
     ).toBe(true)
     expect(
-      handler.predicate({
+      await handler.predicate({
         request: alienRequest,
         parsedResult: await handler.parse({ request: alienRequest }),
       }),
@@ -591,13 +591,13 @@ describe('predicate', () => {
     })
 
     expect(
-      handler.predicate({
+      await handler.predicate({
         request,
         parsedResult: await handler.parse({ request }),
       }),
     ).toBe(true)
     expect(
-      handler.predicate({
+      await handler.predicate({
         request: alienRequest,
         parsedResult: await handler.parse({ request: alienRequest }),
       }),
@@ -618,7 +618,7 @@ describe('predicate', () => {
     })
 
     expect(
-      handler.predicate({
+      await handler.predicate({
         request,
         parsedResult: await handler.parse({ request }),
       }),
@@ -643,13 +643,13 @@ describe('predicate', () => {
     })
 
     expect(
-      handler.predicate({
+      await handler.predicate({
         request,
         parsedResult: await handler.parse({ request }),
       }),
     ).toBe(true)
     expect(
-      handler.predicate({
+      await handler.predicate({
         request: alienRequest,
         parsedResult: await handler.parse({ request: alienRequest }),
       }),

src/core/handlers/GraphQLHandler.ts

@@ -77,6 +77,14 @@ export type GraphQLResponseBody<BodyType extends DefaultBodyType> =
   | null
   | undefined
 
+export type GraphQLCustomPredicate<GraphQLVariables> = (args: {
+  request: Request
+  query: string
+  operationName: string
+  variables: GraphQLVariables
+  cookies: Record<string, string>
+}) => boolean | Promise<boolean>
+
 export function isDocumentNode(
   value: DocumentNode | any,
 ): value is DocumentNode {
@@ -93,6 +101,7 @@ export class GraphQLHandler extends RequestHandler<
   GraphQLResolverExtras<any>
 > {
   private endpoint: Path
+  private customPredicate?: GraphQLCustomPredicate<GraphQLVariables>
 
   static parsedRequestCache = new WeakMap<
     Request,
@@ -104,7 +113,9 @@ export class GraphQLHandler extends RequestHandler<
     operationName: GraphQLHandlerNameSelector,
     endpoint: Path,
     resolver: ResponseResolver<GraphQLResolverExtras<any>, any, any>,
-    options?: RequestHandlerOptions,
+    options?: RequestHandlerOptions & {
+      predicate?: GraphQLCustomPredicate<GraphQLVariables>
+    },
   ) {
     let resolvedOperationName = operationName
 
@@ -141,6 +152,7 @@ export class GraphQLHandler extends RequestHandler<
       options,
     })
 
+    this.customPredicate = options?.predicate
     this.endpoint = endpoint
   }
 
@@ -196,33 +208,42 @@ export class GraphQLHandler extends RequestHandler<
     }
   }
 
-  predicate(args: {
+  async predicate(args: {
     request: Request
     parsedResult: GraphQLRequestParsedResult
-  }) {
+  }): Promise<boolean> {
+    if (this.customPredicate) {
+      // Clone the request to avoid locking its body stream.
+      // The body can only be read once, so cloning allows both
+      // the predicate and resolver to access it independently.
+      const clonedRequest = args.request.clone()
+
+      return await this.customPredicate({
+        request: clonedRequest,
+        ...this.extendResolverArgs({
+          request: clonedRequest,
+          parsedResult: args.parsedResult,
+        }),
+      })
+    }
     if (args.parsedResult.operationType === undefined) {
       return false
     }
-
     if (!args.parsedResult.operationName && this.info.operationType !== 'all') {
       const publicUrl = toPublicUrl(args.request.url)
-
       devUtils.warn(`\
 Failed to intercept a GraphQL request at "${args.request.method} ${publicUrl}": anonymous GraphQL operations are not supported.
 
 Consider naming this operation or using "graphql.operation()" request handler to intercept GraphQL requests regardless of their operation name/type. Read more: https://mswjs.io/docs/api/graphql/#graphqloperationresolver`)
       return false
     }
-
     const hasMatchingOperationType =
       this.info.operationType === 'all' ||
       args.parsedResult.operationType === this.info.operationType
-
     const hasMatchingOperationName =
       this.info.operationName instanceof RegExp
         ? this.info.operationName.test(args.parsedResult.operationName || '')
         : args.parsedResult.operationName === this.info.operationName
-
     return (
       args.parsedResult.match.matches &&
       hasMatchingOperationType &&

src/core/handlers/HttpHandler.test.ts

@@ -78,7 +78,7 @@ describe('predicate', () => {
     })
 
     expect(
-      handler.predicate({
+      await handler.predicate({
         request,
         parsedResult: await handler.parse({ request }),
       }),
@@ -95,7 +95,7 @@ describe('predicate', () => {
 
     for (const request of requests) {
       expect(
-        handler.predicate({
+        await handler.predicate({
           request,
           parsedResult: await handler.parse({ request }),
         }),
@@ -108,7 +108,7 @@ describe('predicate', () => {
     const request = new Request(new URL('/user/abc-123', location.href))
 
     expect(
-      handler.predicate({
+      await handler.predicate({
         request,
         parsedResult: await handler.parse({ request }),
       }),

src/core/handlers/HttpHandler.ts

@@ -52,6 +52,13 @@ export type HttpRequestResolverExtras<Params extends PathParams> = {
   cookies: Record<string, string>
 }
 
+export type HttpCustomPredicate = (args: {
+  request: Request
+  cookies: Record<string, string>
+}) => boolean | Promise<boolean>
+
+export type HttpRequestPath = Path | HttpCustomPredicate
+
 /**
  * Request handler for HTTP requests.
  * Provides request matching based on method and URL.
@@ -61,11 +68,15 @@ export class HttpHandler extends RequestHandler<
   HttpRequestParsedResult,
   HttpRequestResolverExtras<any>
 > {
+  private customPredicate?: HttpCustomPredicate
+
   constructor(
     method: HttpHandlerMethod,
     path: Path,
     resolver: ResponseResolver<HttpRequestResolverExtras<any>, any, any>,
-    options?: RequestHandlerOptions,
+    options?: RequestHandlerOptions & {
+      predicate?: HttpCustomPredicate
+    },
   ) {
     super({
       info: {
@@ -76,14 +87,14 @@ export class HttpHandler extends RequestHandler<
       resolver,
       options,
     })
-
+    this.customPredicate = options?.predicate
     this.checkRedundantQueryParameters()
   }
 
   private checkRedundantQueryParameters() {
     const { method, path } = this.info
 
-    if (path instanceof RegExp) {
+    if (!path || path instanceof RegExp) {
       return
     }
 
@@ -111,11 +122,9 @@ export class HttpHandler extends RequestHandler<
     resolutionContext?: ResponseResolutionContext
   }) {
     const url = new URL(args.request.url)
-    const match = matchRequestUrl(
-      url,
-      this.info.path,
-      args.resolutionContext?.baseUrl,
-    )
+    const match = this.info.path
+      ? matchRequestUrl(url, this.info.path, args.resolutionContext?.baseUrl)
+      : { matches: false, params: {} }
     const cookies = getAllRequestCookies(args.request)
 
     return {
@@ -124,7 +133,22 @@ export class HttpHandler extends RequestHandler<
     }
   }
 
-  predicate(args: { request: Request; parsedResult: HttpRequestParsedResult }) {
+  async predicate(args: {
+    request: Request
+    parsedResult: HttpRequestParsedResult
+    resolutionContext?: ResponseResolutionContext
+  }) {
+    if (this.customPredicate) {
+      // Clone the request to avoid locking its body stream.
+      // The body can only be read once, so cloning allows both
+      // the predicate and resolver to access it independently.
+      const clonedRequest = args.request.clone()
+
+      return await this.customPredicate({
+        request: clonedRequest,
+        cookies: args.parsedResult.cookies,
+      })
+    }
     const hasMatchingMethod = this.matchMethod(args.request.method)
     const hasMatchingUrl = args.parsedResult.match.matches
     return hasMatchingMethod && hasMatchingUrl

src/core/handlers/RequestHandler.ts

@@ -179,7 +179,7 @@ export abstract class RequestHandler<
     request: Request
     parsedResult: ParsedResult
     resolutionContext?: ResponseResolutionContext
-  }): boolean
+  }): boolean | Promise<boolean>
 
   /**
    * Print out the successfully handled request.
@@ -273,7 +273,7 @@ export abstract class RequestHandler<
       request: args.request,
       resolutionContext: args.resolutionContext,
     })
-    const shouldInterceptRequest = this.predicate({
+    const shouldInterceptRequest = await this.predicate({
       request: args.request,
       parsedResult,
       resolutionContext: args.resolutionContext,

src/core/http.ts

@@ -7,8 +7,9 @@ import {
   HttpMethods,
   HttpHandler,
   HttpRequestResolverExtras,
+  HttpRequestPath,
 } from './handlers/HttpHandler'
-import type { Path, PathParams } from './utils/matching/matchRequestUrl'
+import type { PathParams } from './utils/matching/matchRequestUrl'
 
 export type HttpRequestHandler = <
   Params extends PathParams<keyof Params> = PathParams,
@@ -18,7 +19,7 @@ export type HttpRequestHandler = <
   // returns plain "Response" and the one returning "HttpResponse"
   // to enforce a stricter response body type.
   ResponseBodyType extends DefaultBodyType = undefined,
-  RequestPath extends Path = Path,
+  RequestPath extends HttpRequestPath = HttpRequestPath,
 >(
   path: RequestPath,
   resolver: HttpResponseResolver<Params, RequestBodyType, ResponseBodyType>,
@@ -39,6 +40,12 @@ function createHttpHandler<Method extends HttpMethods | RegExp>(
   method: Method,
 ): HttpRequestHandler {
   return (path, resolver, options = {}) => {
+    if (typeof path === 'function') {
+      return new HttpHandler(method, '', resolver, {
+        ...options,
+        predicate: path,
+      })
+    }
     return new HttpHandler(method, path, resolver, options)
   }
 }

src/core/index.ts

@@ -42,6 +42,7 @@ export type {
 export type {
   RequestQuery,
   HttpRequestParsedResult,
+  HttpCustomPredicate,
 } from './handlers/HttpHandler'
 export type { HttpRequestHandler, HttpResponseResolver } from './http'
 
@@ -50,6 +51,7 @@ export type {
   GraphQLVariables,
   GraphQLRequestBody,
   GraphQLJsonRequestBody,
+  GraphQLCustomPredicate,
 } from './handlers/GraphQLHandler'
 export type { GraphQLRequestHandler, GraphQLResponseResolver } from './graphql'