msw 2.15.0 → 3.0.0

package/lib/graphql/index.d.ts

@@ -0,0 +1,550 @@
+import { a as RequestHandler, c as RequestHandlerOptions, g as ResponseResolutionContext, h as StrictRequest, l as ResponseResolver, n as DefaultBodyType, o as RequestHandlerDefaultInfo, s as RequestHandlerExecutionResult, u as ResponseResolverFinalizeFunction, y as MaybePromise } from "../_chunks/request-handler.js";
+import { c as WebSocketHandler, f as WebSocketResolutionContext, l as WebSocketHandlerConnection, p as kConnect } from "../_chunks/handlers-controller.js";
+import { n as Path, r as PathParams, t as Match } from "../_chunks/match-request-url.js";
+import { Emitter, TypedEvent } from "rettime";
+import { WebSocketClientHandle, WebSocketConnectionEventData, WebSocketServerHandle } from "@mswjs/interceptors/WebSocket";
+import { DocumentNode, GraphQLError, OperationTypeNode } from "graphql";
+//#region src/graphql/parse-graphql-request.d.ts
+interface ParsedGraphQLQuery {
+  /**
+   * Undefined if the document has no operation matching the
+   * requested operation name.
+   */
+  operationType?: OperationTypeNode;
+  operationName?: string;
+}
+type ParsedGraphQLRequest<VariablesType extends GraphQLVariables = GraphQLVariables> = (ParsedGraphQLQuery & {
+  query: string;
+  variables?: VariablesType;
+}) | undefined;
+type GraphQLMultipartRequestBody = {
+  operations: string;
+  map?: string;
+} & {
+  [fileName: string]: File;
+};
+//#endregion
+//#region src/graphql/graphql-handler.d.ts
+interface DocumentTypeDecoration<Result = {
+  [key: string]: any;
+}, Variables = {
+  [key: string]: any;
+}> {
+  __apiType?: (variables: Variables) => Result;
+  __resultType?: Result;
+  __variablesType?: Variables;
+}
+type GraphQLOperationType = OperationTypeNode | 'all';
+type GraphQLHandlerNameSelector = DocumentNode | RegExp | string;
+type GraphQLQuery = Record<string, any> | null;
+type GraphQLVariables = Record<string, any>;
+interface GraphQLHandlerInfo extends RequestHandlerDefaultInfo {
+  operationType: GraphQLOperationType;
+  operationName: GraphQLHandlerNameSelector | GraphQLCustomPredicate;
+}
+type GraphQLRequestParsedResult = {
+  match: Match;
+  cookies: Record<string, string>;
+} & (ParsedGraphQLRequest<GraphQLVariables> |
+/**
+ * An empty version of the ParsedGraphQLRequest
+ * which simplifies the return type of the resolver
+ * when the request is to a non-matching endpoint
+ */
+{
+  operationType?: undefined;
+  operationName?: undefined;
+  query?: undefined;
+  variables?: undefined;
+});
+type GraphQLResolverExtras<Variables extends GraphQLVariables> = {
+  query: string;
+  operationName: string;
+  variables: Variables;
+  cookies: Record<string, string>;
+};
+type GraphQLRequestBody<VariablesType extends GraphQLVariables> = GraphQLJsonRequestBody<VariablesType> | GraphQLMultipartRequestBody | Record<string, any> | undefined;
+interface GraphQLJsonRequestBody<Variables extends GraphQLVariables> {
+  query: string;
+  variables?: Variables;
+}
+type GraphQLResponseBody<BodyType extends DefaultBodyType> = {
+  data?: BodyType | null;
+  errors?: readonly Partial<GraphQLError>[] | null;
+  extensions?: Record<string, any>;
+} | null | undefined;
+type GraphQLCustomPredicate = (args: {
+  request: Request;
+  query: string;
+  operationType: GraphQLOperationType;
+  operationName: string;
+  variables: GraphQLVariables;
+  cookies: Record<string, string>;
+}) => GraphQLCustomPredicateResult | Promise<GraphQLCustomPredicateResult>;
+type GraphQLCustomPredicateResult = boolean | {
+  matches: boolean;
+};
+type GraphQLPredicate<Query = any, Variables = any> = GraphQLHandlerNameSelector | DocumentTypeDecoration<Query, Variables> | GraphQLCustomPredicate;
+export declare class GraphQLHandler extends RequestHandler<GraphQLHandlerInfo, GraphQLRequestParsedResult, GraphQLResolverExtras<any>> {
+  #private;
+  private endpoint;
+  static parsedRequestCache: WeakMap<Request, ParsedGraphQLRequest<GraphQLVariables>>;
+  /**
+   * Creates a GraphQL handler information object from the given
+   * operation predicate. Normalizes `DocumentNode` and typed document
+   * string predicates to plain operation names.
+   */
+  static parseGraphQLRequestInfo(args: {
+    operationType: GraphQLOperationType;
+    predicate: GraphQLPredicate;
+    url: Path;
+  }): GraphQLHandlerInfo;
+  constructor(operationType: GraphQLOperationType, predicate: GraphQLPredicate, endpoint: Path, resolver: ResponseResolver<GraphQLResolverExtras<any>, any, any>, options?: RequestHandlerOptions);
+  /**
+   * Parses the request body, once per request, cached across all
+   * GraphQL handlers. This is done to avoid multiple parsing of the
+   * request body, which each requires a clone of the request.
+   */
+  parseGraphQLRequestOrGetFromCache(request: Request): Promise<ParsedGraphQLRequest<GraphQLVariables>>;
+  parse(args: {
+    request: Request;
+  }): Promise<GraphQLRequestParsedResult>;
+  predicate(args: {
+    request: Request;
+    parsedResult: GraphQLRequestParsedResult;
+  }): Promise<boolean>;
+  run(args: {
+    request: StrictRequest<any>;
+    requestId: string;
+    resolutionContext?: ResponseResolutionContext;
+  }): Promise<RequestHandlerExecutionResult<GraphQLRequestParsedResult> | null>;
+  private matchOperationName;
+  protected extendResolverArgs(args: {
+    request: Request;
+    parsedResult: GraphQLRequestParsedResult;
+  }): {
+    query: string;
+    operationType: OperationTypeNode;
+    operationName: string;
+    variables: GraphQLVariables;
+    cookies: Record<string, string>;
+  };
+  log(args: {
+    request: Request;
+    response: Response;
+    parsedResult: GraphQLRequestParsedResult;
+  }): Promise<void>;
+}
+//#endregion
+//#region src/graphql/graphql-subscription.d.ts
+interface GraphQLWebSocketSubscribePayload<Variables extends GraphQLVariables = GraphQLVariables> {
+  operationName?: string | null;
+  query: string;
+  variables?: Variables;
+  extensions?: Record<string, unknown>;
+}
+interface GraphQLWebSocketSubscribeMessage<Variables extends GraphQLVariables = GraphQLVariables> {
+  type: 'subscribe';
+  id: string;
+  payload: GraphQLWebSocketSubscribePayload<Variables>;
+}
+interface GraphQLWebSocketCompleteMessage {
+  type: 'complete';
+  id: string;
+}
+interface GraphQLWebSocketNextMessage {
+  type: 'next';
+  id: string;
+  payload: GraphQLSubscriptionPayload;
+}
+interface GraphQLWebSocketErrorMessage {
+  type: 'error';
+  id: string;
+  payload: ReadonlyArray<Partial<GraphQLError>>;
+}
+/**
+ * A GraphQL execution result published to a subscription.
+ */
+interface GraphQLSubscriptionPayload<Query extends GraphQLQuery = GraphQLQuery> {
+  data?: Query | null;
+  errors?: ReadonlyArray<Partial<GraphQLError>> | null;
+  extensions?: Record<string, unknown>;
+}
+/**
+ * A subscriber provided by a `GraphQLSubscriptionHandler` for a particular
+ * WebSocket connection. Returns true if the handler matched the parsed
+ * subscribe operation and resolved it.
+ */
+type GraphQLSubscriptionSubscriber = (args: {
+  node: ParsedGraphQLQuery;
+  message: GraphQLWebSocketSubscribeMessage;
+}) => boolean;
+interface GraphQLSubscriptionSubscriberEntry {
+  transport: GraphQLSubscriptionTransportHandler;
+  subscriber: GraphQLSubscriptionSubscriber;
+}
+type GraphQLSubscriptionCleanup = () => MaybePromise<void>;
+interface GraphQLSubscriptionConnection {
+  client: WebSocketClientHandle;
+  server: WebSocketServerHandle;
+  subscribers: Map<WebSocketHandler, GraphQLSubscriptionSubscriberEntry>;
+  /**
+   * The active subscriptions of this connection, mapped to the cleanups
+   * scheduled for them via the resolver's `finalize()`.
+   */
+  subscriptions: Map<string, Array<GraphQLSubscriptionCleanup>>;
+  events?: WebSocketResolutionContext['events'];
+  /**
+   * The payload of the client's `connection_init` message (i.e. the
+   * `connectionParams` of the GraphQL client). Kept so it can be
+   * replayed to the original server on passthrough.
+   */
+  connectionParams?: Record<string, unknown>;
+  /**
+   * Resolves once the original server has acknowledged this connection.
+   * The upstream session is established once per connection, no matter
+   * how many subscriptions pass through it.
+   */
+  upstreamSession?: Promise<void>;
+}
+/**
+ * A WebSocket handler that only matches connections that requested the
+ * `graphql-transport-ws` protocol. Connections without it (e.g.
+ * arbitrary non-GraphQL WebSockets whose URL matched a permissive
+ * endpoint like a wildcard link) are left unhandled so they follow the
+ * regular unhandled connection flow (warnings, passthrough).
+ */
+declare abstract class GraphQLWebSocketHandler extends WebSocketHandler {
+  run(connection: WebSocketConnectionEventData, resolutionContext?: WebSocketResolutionContext): Promise<WebSocketHandlerConnection | null>;
+}
+/**
+ * A WebSocket handler implementing the `graphql-transport-ws` protocol
+ * session for a single GraphQL endpoint. One transport is shared across
+ * all subscription handlers created from the same `graphql.link()` call
+ * (attached to each of them as a sibling handler).
+ *
+ * The transport owns the protocol/session concerns: connection
+ * acknowledgement, keep-alive, the per-connection registry of active
+ * subscriptions, and dispatching parsed `subscribe` operations to the
+ * matching subscription handler.
+ */
+declare class GraphQLSubscriptionTransportHandler extends GraphQLWebSocketHandler {
+  #private;
+  /**
+   * Register the given handler as a subscriber to the GraphQL
+   * subscriptions on the given WebSocket connection. Subscribers are
+   * dispatched in registration order, which follows the handlers
+   * resolution order (runtime handlers take precedence).
+   */
+  subscribe(connection: WebSocketHandlerConnection, handler: WebSocketHandler, subscriber: GraphQLSubscriptionSubscriber): void;
+  getConnection(clientId: string): GraphQLSubscriptionConnection | undefined;
+  run(connection: WebSocketConnectionEventData, resolutionContext?: WebSocketResolutionContext): Promise<WebSocketHandlerConnection | null>;
+  /**
+   * End the given subscription without notifying the client. Used when
+   * the subscription has already been terminated over the wire (e.g. the
+   * original server completed it and that frame reached the client).
+   */
+  endSubscription(args: {
+    clientId: string;
+    subscriptionId: string;
+  }): void;
+  /**
+   * Schedule a cleanup to run once the given subscription ends.
+   *
+   * @note If the subscription has already ended by the time this is
+   * called, the cleanup runs immediately. The resolver can no longer
+   * affect that subscription, so there is nothing left to wait for.
+   */
+  finalize(args: {
+    clientId: string;
+    subscriptionId: string;
+    cleanup: GraphQLSubscriptionCleanup;
+  }): void;
+  /**
+   * Send a `next` message with the given payload to the subscription.
+   */
+  publish(args: {
+    clientId: string;
+    subscriptionId: string;
+    payload: GraphQLSubscriptionPayload;
+  }): void;
+  /**
+   * Send a terminal `error` message to the subscription and
+   * removes it from the registry of active subscriptions.
+   */
+  error(args: {
+    clientId: string;
+    subscriptionId: string;
+    errors: ReadonlyArray<Partial<GraphQLError>>;
+  }): void;
+  /**
+   * Send a `complete` message to the subscription and removes it
+   * from the registry of active subscriptions.
+   */
+  complete(args: {
+    clientId: string;
+    subscriptionId: string;
+  }): void;
+  /**
+   * Drop this transport's subscribers and active subscriptions from the
+   * sessions it participates in. The sessions themselves are left intact:
+   * they are shared with the other transports of the same connection and
+   * own the protocol listeners for as long as the client stays connected.
+   *
+   * @note This method is invoked automatically when the handlers
+   * controller resets the handlers (e.g. `server.resetHandlers()`).
+   */
+  reset(): void;
+  /**
+   * Forget the sessions of this transport, ending their subscriptions.
+   * @note This method is invoked automatically when the network is
+   * disabled (e.g. `server.close()`).
+   */
+  dispose(): MaybePromise<void>;
+  /**
+   * @note The transport is the sole owner of logging for GraphQL
+   * subscription connections. It logs parsed `graphql-transport-ws`
+   * frames instead of raw WebSocket messages.
+   */
+  log(connection: WebSocketConnectionEventData): () => void;
+  protected [kConnect](connection: WebSocketHandlerConnection): boolean;
+}
+type GraphQLSubscriptionName<Query extends GraphQLQuery = GraphQLQuery, Variables extends GraphQLVariables = GraphQLVariables> = GraphQLHandlerNameSelector | DocumentTypeDecoration<Query, Variables>;
+interface GraphQLSubscriptionResolverInfo<Query extends GraphQLQuery = GraphQLQuery, Variables extends GraphQLVariables = GraphQLVariables> {
+  /**
+   * Path parameters parsed from the WebSocket connection URL.
+   */
+  params: PathParams;
+  /**
+   * The name of the intercepted operation.
+   */
+  operationName: string;
+  /**
+   * Intercepted GraphQL subscription.
+   */
+  subscription: GraphQLSubscription<Query, Variables>;
+  /**
+   * The request that established the WebSocket connection this
+   * subscription is multiplexed over.
+   */
+  request: Request;
+  /**
+   * Schedule a cleanup to run once this subscription ends and the
+   * resolver can no longer affect it: it has been completed (by the mock,
+   * the client, or the original server), terminated with errors, or the
+   * client has disconnected.
+   *
+   * @example
+   * api.subscription('OnCommentAdded', ({ subscription, finalize }) => {
+   *   const interval = setInterval(() => subscription.publish(payload), 1000)
+   *   finalize(() => clearInterval(interval))
+   * })
+   */
+  finalize: ResponseResolverFinalizeFunction;
+}
+type GraphQLSubscriptionResolver<Query extends GraphQLQuery = GraphQLQuery, Variables extends GraphQLVariables = GraphQLVariables> = (info: GraphQLSubscriptionResolverInfo<Query, Variables>) => void;
+interface GraphQLSubscriptionHandlerOptions {
+  /**
+   * Mark this handler as used after its first match.
+   * Used handlers do not match subsequent subscriptions.
+   */
+  once?: boolean;
+}
+/**
+ * A WebSocket handler intercepting GraphQL subscriptions by their
+ * operation name. Matching and resolution are delegated to it by the
+ * subscription transport (its sibling handler) so the first matching
+ * handler wins, respecting runtime handler overrides.
+ */
+export declare class GraphQLSubscriptionHandler<Query extends GraphQLQuery = GraphQLQuery, Variables extends GraphQLVariables = GraphQLVariables> extends GraphQLWebSocketHandler {
+  #private;
+  info: GraphQLHandlerInfo;
+  isUsed: boolean;
+  constructor(args: {
+    url: Path;
+    operationName: GraphQLSubscriptionName<Query, Variables>;
+    transport: GraphQLSubscriptionTransportHandler;
+    resolver: GraphQLSubscriptionResolver<Query, Variables>;
+    options?: GraphQLSubscriptionHandlerOptions;
+  });
+  reset(): void;
+  /**
+   * @note Individual subscription handlers stay silent. The subscription
+   * transport owns the GraphQL-aware logging for the entire connection
+   * (a logger is attached once per matching handler otherwise).
+   */
+  log(): () => void;
+  protected [kConnect](connection: WebSocketHandlerConnection): boolean;
+}
+/**
+ * Representation of the intercepted GraphQL subscription.
+ */
+export declare class GraphQLSubscription<Query extends GraphQLQuery = GraphQLQuery, Variables extends GraphQLVariables = GraphQLVariables> {
+  #private;
+  id: string;
+  query: string;
+  variables: Variables;
+  extensions?: Record<string, unknown>;
+  constructor(args: {
+    message: GraphQLWebSocketSubscribeMessage;
+    clientId: string;
+    transport: GraphQLSubscriptionTransportHandler;
+  });
+  /**
+   * Publish an execution result to the subscribed client.
+   *
+   * @example
+   * subscription.publish({
+   *   data: {
+   *     postAdded: {
+   *       id: 'abc-123'
+   *     }
+   *   }
+   * })
+   */
+  publish(payload: GraphQLSubscriptionPayload<Query>): void;
+  /**
+   * Use the given `Iterable` or `AsyncIterable` as the source
+   * of data for this subscription. Whenever the iterable yields a
+   * value, it gets published to this subscription.
+   *
+   * @example
+   * subscription.from(async function* () {
+   *   yield { text: 'hello world' }
+   * })
+   */
+  from(source: Iterable<Query> | AsyncIterable<Query>): Promise<void>;
+  /**
+   * Terminate this subscription with the given errors.
+   *
+   * @example
+   * subscription.error([{ message: 'Something went wrong' }])
+   */
+  error(errors: ReadonlyArray<Partial<GraphQLError>>): void;
+  /**
+   * Marks this subscription as complete.
+   *
+   * @example
+   * subscription.complete()
+   */
+  complete(): void;
+  /**
+   * Perform this GraphQL subscription as-is.
+   * This establishes a connection to the actual server, replays
+   * the intercepted subscription, and forwards the server payloads
+   * to the GraphQL client. You can intercept, modify, or prevent
+   * any of the original server messages.
+   *
+   * @example
+   * const postAddedSubscription = subscription.passthrough()
+   * postAddedSubscription.addEventListener('next', (event) => {
+   *   event.preventDefault()
+   *   event.data.payload.data.postAdded.id = 'mock-id'
+   *   subscription.publish(event.data.payload)
+   * })
+   */
+  passthrough(): GraphQLPassthroughSubscription;
+}
+type GraphQLPassthroughSubscriptionEventMap = {
+  connection_ack: TypedEvent;
+  next: TypedEvent<GraphQLWebSocketNextMessage>;
+  error: TypedEvent<GraphQLWebSocketErrorMessage>;
+  complete: TypedEvent<GraphQLWebSocketCompleteMessage>;
+};
+/**
+ * Representation of a GraphQL subscription to the actual server.
+ * You interface with this object from the client's perspective.
+ */
+export declare class GraphQLPassthroughSubscription {
+  #private;
+  constructor(args: {
+    server: WebSocketServerHandle;
+    message: GraphQLWebSocketSubscribeMessage;
+    upstreamSession: Promise<void>;
+    onTerminate: () => void;
+  });
+  /**
+   * Add an event listener to the given GraphQL subscription event.
+   *
+   * @example
+   * const onPostAddedSubscription = subscription.passthrough()
+   * onPostAddedSubscription.addEventListener('next', (event) => {
+   *   console.log(event.data)
+   *   // { id, payload, ... }
+   * })
+   */
+  addEventListener<EventType extends keyof GraphQLPassthroughSubscriptionEventMap & string>(event: EventType, listener: Emitter.Listener<Emitter<GraphQLPassthroughSubscriptionEventMap>, EventType>): void;
+  /**
+   * Unsubscribe from this passthrough GraphQL subscription.
+   * This stops this subscription on the original server.
+   *
+   * @note Unsubscribing from the original subscription has no
+   * effect on the intercepted `subscription` object.
+   *
+   * @example
+   * const onPostAddedSubscription = subscription.passthrough()
+   * onPostAddedSubscription.unsubscribe()
+   */
+  unsubscribe(): void;
+}
+type GraphQLSubscriptionHandlerFactory = <Query extends GraphQLQuery = GraphQLQuery, Variables extends GraphQLVariables = GraphQLVariables>(operationName: GraphQLSubscriptionName<Query, Variables>, resolver: GraphQLSubscriptionResolver<Query, Variables>, options?: GraphQLSubscriptionHandlerOptions) => GraphQLSubscriptionHandler<Query, Variables>;
+/**
+ * Create a `subscription()` handler factory bound to the given GraphQL
+ * endpoint. All subscription handlers created by the factory share a single
+ * subscription transport and a single WebSocket upgrade handler, both
+ * attached to each handler as siblings.
+ *
+ * @example
+ * const subscription = createGraphQLSubscriptionHandler('https://api.example.com/graphql')
+ * subscription('OnPostAdded', ({ subscription }) => {
+ *   subscription.publish({ data: { postAdded: { id: 'abc-123' } } })
+ * })
+ */
+export declare function createGraphQLSubscriptionHandler(url: Path): GraphQLSubscriptionHandlerFactory;
+//#endregion
+//#region src/graphql/graphql.d.ts
+type GraphQLRequestHandler = <Query extends GraphQLQuery = GraphQLQuery, Variables extends GraphQLVariables = GraphQLVariables>(predicate: GraphQLPredicate<Query, Variables>, resolver: GraphQLResponseResolver<[Query] extends [never] ? GraphQLQuery : Query, Variables>, options?: RequestHandlerOptions) => GraphQLHandler;
+type GraphQLOperationHandler = <Query extends GraphQLQuery = GraphQLQuery, Variables extends GraphQLVariables = GraphQLVariables>(resolver: GraphQLResponseResolver<[Query] extends [never] ? GraphQLQuery : Query, Variables>, options?: RequestHandlerOptions) => GraphQLHandler;
+type GraphQLResponseResolver<Query extends GraphQLQuery = GraphQLQuery, Variables extends GraphQLVariables = GraphQLVariables> = ResponseResolver<GraphQLResolverExtras<Variables>, null, GraphQLResponseBody<[Query] extends [never] ? GraphQLQuery : Query>>;
+interface GraphQLLink {
+  query: GraphQLRequestHandler;
+  mutation: GraphQLRequestHandler;
+  operation: GraphQLOperationHandler;
+  /**
+   * Intercept a GraphQL subscription.
+   *
+   * @example
+   * const api = graphql.link('https://api.example.com/graphql')
+   * api.subscription('OnPostAdded', ({ subscription }) => {
+   *   subscription.publish({
+   *    data: { postAdded: { id: 'abc-123' } },
+   *   })
+   * })
+   */
+  subscription: GraphQLSubscriptionHandlerFactory;
+}
+/**
+ * A namespace to intercept and mock GraphQL operations
+ *
+ * @example
+ * const api = graphql.link('https://api.example.com/graphql')
+ * api.query('GetUser', resolver)
+ * api.mutation('DeletePost', resolver)
+ *
+ * @see {@link https://mswjs.io/docs/api/graphql `graphql` API reference}
+ */
+export declare const graphql: {
+  /**
+   * Intercepts GraphQL operations scoped by the given URL.
+   *
+   * @example
+   * const github = graphql.link('https://api.github.com/graphql')
+   * github.query('GetRepo', resolver)
+   *
+   * @see {@link https://mswjs.io/docs/api/graphql#graphqllinkurl `graphql.link()` API reference}
+   */
+  link(url: Path): GraphQLLink;
+};
+//#endregion
+export type { GraphQLCustomPredicate, GraphQLJsonRequestBody, GraphQLLink, GraphQLOperationHandler, GraphQLOperationType, GraphQLPassthroughSubscriptionEventMap, GraphQLQuery, GraphQLRequestBody, GraphQLRequestHandler, GraphQLResponseBody, GraphQLResponseResolver, GraphQLSubscriptionHandlerFactory, GraphQLSubscriptionHandlerOptions, GraphQLSubscriptionName, GraphQLSubscriptionPayload, GraphQLSubscriptionResolver, GraphQLSubscriptionResolverInfo, GraphQLVariables, ParsedGraphQLRequest };
+//# sourceMappingURL=index.d.ts.map