msw 0.22.2 → 0.24.1

package/lib/types/utils/handlers/requestHandler.d.ts

@@ -1,5 +1,5 @@
 import { Headers } from 'headers-utils';
-import { ResponseWithSerializedHeaders } from '../../setupWorker/glossary';
+import { Mask, ResponseWithSerializedHeaders } from '../../setupWorker/glossary';
 import { ResponseComposition, MockedResponse } from '../../response';
 import { set } from '../../context/set';
 export declare const defaultContext: {
@@ -36,6 +36,13 @@ export declare type RequestParams = {
 export declare type ResponseResolverReturnType<R> = R | undefined | void;
 export declare type AsyncResponseResolverReturnType<R> = Promise<ResponseResolverReturnType<R>> | ResponseResolverReturnType<R>;
 export declare type ResponseResolver<RequestType = MockedRequest, ContextType = typeof defaultContext, BodyType = any> = (req: RequestType, res: ResponseComposition<BodyType>, context: ContextType) => AsyncResponseResolverReturnType<MockedResponse<BodyType>>;
+declare type RequestHandlerType = 'rest' | 'graphql';
+export interface RequestHandlerMetaInfo<Type = RequestHandlerType> {
+    type: Type;
+    header: string;
+    mask: Mask;
+    callFrame: string | undefined;
+}
 export interface RequestHandler<RequestType = MockedRequest, ContextType = typeof defaultContext, ParsedRequest = any, PublicRequest = RequestType, ResponseBodyType = any> {
     /**
      * Parses a captured request to retrieve additional
@@ -69,6 +76,11 @@ export interface RequestHandler<RequestType = MockedRequest, ContextType = typeo
      * when dealing with any subsequent matching requests.
      */
     shouldSkip?: boolean;
+    /**
+     * Returns request handler's meta information used
+     * when listing each current request handler.
+     */
+    getMetaInfo: () => RequestHandlerMetaInfo;
 }
 declare const _default: null;
 export default _default;

package/lib/types/utils/internal/compose.d.ts

@@ -1,5 +1,13 @@
+declare type ArityOneFn = (arg: any) => any;
+declare type PickLastInTuple<T extends any[]> = T extends [
+    ...rest: infer U,
+    argn: infer L
+] ? L : never;
+declare type FirstFnParameterType<T extends any[]> = Parameters<PickLastInTuple<T>>[any];
+declare type LastFnParameterType<T extends any[]> = ReturnType<T[0]>;
 /**
  * Composes a given list of functions into a new function that
  * executes from right to left.
  */
-export declare function compose(...funcs: Array<(...args: any[]) => any>): (...args: any[]) => any;
+export declare function compose<T extends ArityOneFn[], LeftReturnType extends FirstFnParameterType<T>, RightReturnType extends LastFnParameterType<T>>(...fns: T): (...args: LeftReturnType extends never ? never[] : [LeftReturnType]) => RightReturnType;
+export {};

package/lib/types/utils/internal/getCallFrame.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Return the stack trace frame of a function's invocation.
+ */
+export declare function getCallFrame(): string | undefined;

package/lib/umd/index.js

@@ -70,6 +70,13 @@
   	"511": "Network Authentication Required"
   };
 
+  /**
+   * Sets a response status code and text.
+   * @example
+   * res(ctx.status(301))
+   * res(ctx.status(400, 'Custom status text'))
+   * @see {@link https://mswjs.io/docs/api/context/status `ctx.status()`}
+   */
   const status = (statusCode, statusText) => {
       return (res) => {
           res.status = statusCode;
@@ -333,6 +340,10 @@
   exports.flattenHeadersObject = flattenHeadersObject_1.flattenHeadersObject;
   });
 
+  /**
+   * Sets one or multiple response headers.
+   * @see {@link https://mswjs.io/docs/api/context/set `ctx.set()`}
+   */
   function set(...args) {
       return (res) => {
           const [name, value] = args;
@@ -551,9 +562,8 @@
   }
 
   /**
-   * Sets a given cookie on the response.
-   * @example
-   * res(cookie('name', 'value'))
+   * Sets a given cookie on the mocked response.
+   * @example res(ctx.cookie('name', 'value'))
    */
   const cookie = (name, value, options) => {
       return (res) => {
@@ -567,9 +577,11 @@
   };
 
   /**
-   * Sets the body of the response without any `Content-Type` header.
+   * Sets a raw response body. Does not append any `Content-Type` headers.
    * @example
-   * res(body('message'))
+   * res(ctx.body('Successful response'))
+   * res(ctx.body(JSON.stringify({ key: 'value' })))
+   * @see {@link https://mswjs.io/docs/api/context/body `ctx.body()`}
    */
   const body = (value) => {
       return (res) => {
@@ -578,6 +590,19 @@
       };
   };
 
+  /**
+   * Parses a given string into a JSON.
+   * Does not throw an exception on an invalid JSON string.
+   */
+  function jsonParse(str) {
+      try {
+          return JSON.parse(str);
+      }
+      catch (error) {
+          return undefined;
+      }
+  }
+
   /**
    * Determines if the given value is an object.
    */
@@ -607,24 +632,34 @@
 
   /**
    * Sets the given value as the JSON body of the response.
+   * Appends a `Content-Type: application/json` header on the
+   * mocked response.
    * @example
-   * res(json({ key: 'value' }))
-   * res(json('Some string'))
-   * res(json([1, '2', false, { ok: true }]))
+   * res(ctx.json('Some string'))
+   * res(ctx.json({ key: 'value' }))
+   * res(ctx.json([1, '2', false, { ok: true }]))
+   * @see {@link https://mswjs.io/docs/api/context/json `ctx.json()`}
    */
-  const json = (body, { merge = false } = {}) => {
+  const json = (body) => {
       return (res) => {
           res.headers.set('Content-Type', 'application/json');
-          res.body = merge ? mergeRight(res.body || {}, body) : body;
+          res.body = JSON.stringify(body);
           return res;
       };
   };
 
   /**
-   * Returns a GraphQL body payload.
+   * Sets a given payload as a GraphQL response body.
+   * @example
+   * res(ctx.data({ user: { firstName: 'John' }}))
+   * @see {@link https://mswjs.io/docs/api/context/data `ctx.data()`}
    */
   const data = (payload) => {
-      return json({ data: payload }, { merge: true });
+      return (res) => {
+          const prevBody = jsonParse(res.body) || {};
+          const nextBody = mergeRight(prevBody, { data: payload });
+          return json(nextBody)(res);
+      };
   };
 
   /**
@@ -654,10 +689,11 @@
           MIN_SERVER_RESPONSE_TIME);
   };
   /**
-   * Delays the current response for the given duration (in ms)
+   * Delays the response by the given duration (ms).
    * @example
-   * res(delay()) // realistic server response time
-   * res(delay(1500)) // explicit response delay duration
+   * res(ctx.delay()) // realistic server response time
+   * res(ctx.delay(1200))
+   * @see {@link https://mswjs.io/docs/api/context/delay `ctx.delay()`}
    */
   const delay = (durationMs) => {
       return (res) => {
@@ -668,12 +704,18 @@
 
   /**
    * Sets a given list of GraphQL errors on the mocked response.
+   * @example res(ctx.errors([{ message: 'Unauthorized' }]))
+   * @see {@link https://mswjs.io/docs/api/context/errors}
    */
   const errors = (errorsList) => {
-      if (errorsList == null) {
-          return (res) => res;
-      }
-      return json({ errors: errorsList }, { merge: true });
+      return (res) => {
+          if (errorsList == null) {
+              return res;
+          }
+          const prevBody = jsonParse(res.body) || {};
+          const nextBody = mergeRight(prevBody, { errors: errorsList });
+          return json(nextBody)(res);
+      };
   };
 
   const useFetch = isNodeProcess() ? require('node-fetch') : window.fetch;
@@ -693,9 +735,10 @@
       return requestParameters;
   };
   /**
-   * Wrapper around the native `window.fetch()` function that performs
-   * a request bypassing MSW. Requests performed using
-   * this function will never be mocked.
+   * Performs a bypassed request inside a request handler.
+   * @example
+   * const originalResponse = await ctx.fetch(req)
+   * @see {@link https://mswjs.io/docs/api/context/fetch `ctx.fetch()`}
    */
   const fetch = (input, requestInit = {}) => {
       // Keep the default `window.fetch()` call signature
@@ -708,9 +751,10 @@
   };
 
   /**
-   * Sets a given text as a "Cotent-Type: text/plain" body of the response.
-   * @example
-   * res(text('message'))
+   * Sets a textual response body. Appends a `Content-Type: text/plain`
+   * header on the mocked response.
+   * @example res(ctx.text('Successful response'))
+   * @see {@link https://mswjs.io/docs/api/context/text `ctx.text()`}
    */
   const text = (body) => {
       return (res) => {
@@ -721,9 +765,11 @@
   };
 
   /**
-   * Sets the given XML as the body of the response.
+   * Sets an XML response body. Appends a `Content-Type: text/xml` header
+   * on the mocked response.
    * @example
-   * res(xml('<key>value</key>'))
+   * res(ctx.xml('<node key="value">Content</node>'))
+   * @see {@link https://mswjs.io/docs/api/context/xml `ctx.xml()`}
    */
   const xml = (body) => {
       return (res) => {
@@ -930,8 +976,14 @@ Learn more about creating the Service Worker script: https://mswjs.io/docs/cli/i
    * Composes a given list of functions into a new function that
    * executes from right to left.
    */
-  function compose(...funcs) {
-      return funcs.reduce((f, g) => (...args) => f(g(...args)));
+  function compose(...fns) {
+      return (...args) => {
+          return fns.reduceRight((leftFn, rightFn) => {
+              return leftFn instanceof Promise
+                  ? Promise.resolve(leftFn).then(rightFn)
+                  : rightFn(leftFn);
+          }, args[0]);
+      };
   }
 
   class NetworkError extends Error {
@@ -941,17 +993,6 @@ Learn more about creating the Service Worker script: https://mswjs.io/docs/cli/i
       }
   }
 
-  /**
-   * Internal response transformer to ensure response JSON body
-   * is always stringified.
-   */
-  const stringifyJsonBody = (res) => {
-      var _a, _b;
-      if (res.body && ((_b = (_a = res.headers) === null || _a === void 0 ? void 0 : _a.get('content-type')) === null || _b === void 0 ? void 0 : _b.endsWith('json'))) {
-          res.body = JSON.stringify(res.body);
-      }
-      return res;
-  };
   const defaultResponse = {
       status: 200,
       statusText: 'OK',
@@ -959,11 +1000,9 @@ Learn more about creating the Service Worker script: https://mswjs.io/docs/cli/i
       delay: 0,
       once: false,
   };
-  const defaultResponseTransformers = [
-      stringifyJsonBody,
-  ];
+  const defaultResponseTransformers = [];
   function createResponseComposition(responseOverrides, defaultTransformers = defaultResponseTransformers) {
-      return (...transformers) => {
+      return (...transformers) => __awaiter(this, void 0, void 0, function* () {
           const initialResponse = Object.assign({}, defaultResponse, {
               headers: new lib.Headers({
                   'x-powered-by': 'msw',
@@ -977,7 +1016,7 @@ Learn more about creating the Service Worker script: https://mswjs.io/docs/cli/i
               ? compose(...resolvedTransformers)(initialResponse)
               : initialResponse;
           return resolvedResponse;
-      };
+      });
   }
   const response = Object.assign(createResponseComposition(), {
       once: createResponseComposition({ once: true }),
@@ -2442,19 +2481,6 @@ Learn more about creating the Service Worker script: https://mswjs.io/docs/cli/i
       }
   }
 
-  /**
-   * Parses a given string into a JSON.
-   * Does not throw an exception on an invalid JSON string.
-   */
-  function jsonParse(str) {
-      try {
-          return JSON.parse(str);
-      }
-      catch (error) {
-          return undefined;
-      }
-  }
-
   /**
    * Parses a given request/response body based on the `Content-Type` header.
    */
@@ -2758,6 +2784,12 @@ If this message still persists after updating, please report an issue: https://g
   // Declare the list of event handlers on the module's scope
   // so it persists between Fash refreshes of the application's code.
   let listeners = [];
+  /**
+   * Creates a new mock Service Worker registration
+   * with the given request handlers.
+   * @param {RequestHandler[]} requestHandlers List of request handlers
+   * @see {@link https://mswjs.io/docs/api/setup-worker `setupWorker`}
+   */
   function setupWorker(...requestHandlers) {
       requestHandlers.forEach((handler) => {
           if (Array.isArray(handler))
@@ -2818,6 +2850,18 @@ If this message still persists after updating, please report an issue: https://g
           resetHandlers(...nextHandlers) {
               context.requestHandlers = resetHandlers(requestHandlers, ...nextHandlers);
           },
+          printHandlers() {
+              context.requestHandlers.forEach((handler) => {
+                  const meta = handler.getMetaInfo();
+                  console.groupCollapsed(meta.header);
+                  console.log(`Declaration: ${meta.callFrame}`);
+                  console.log('Resolver: %s', handler.resolver);
+                  if (['rest'].includes(meta.type)) {
+                      console.log('Match:', `https://mswjs.io/repl?path=${meta.mask}`);
+                  }
+                  console.groupEnd();
+              });
+          },
       };
   }
 
@@ -2969,6 +3013,31 @@ If this message still persists after updating, please report an issue: https://g
       return match(cleanMask, cleanRequestUrl);
   }
 
+  /**
+   * Return the stack trace frame of a function's invocation.
+   */
+  function getCallFrame() {
+      try {
+          const inspectionError = new Error();
+          inspectionError.name = 'Inspection Error';
+          throw inspectionError;
+      }
+      catch (error) {
+          const frames = error.stack.split('\n');
+          // Get the first frame that doesn't reference the library's internal trace.
+          // Assume that frame is the invocation frame.
+          const declarationFrame = frames.slice(1).find((frame) => {
+              return !/(node_modules)?\/lib\/(umd|esm)\//.test(frame);
+          });
+          if (!declarationFrame) {
+              return;
+          }
+          // Extract file reference from the stack frame.
+          const [, declarationPath] = declarationFrame.match(/\((.+?)\)$/) || [];
+          return declarationPath;
+      }
+  }
+
   (function (RESTMethods) {
       RESTMethods["HEAD"] = "HEAD";
       RESTMethods["GET"] = "GET";
@@ -2992,6 +3061,7 @@ If this message still persists after updating, please report an issue: https://g
   const createRestHandler = (method) => {
       return (mask, resolver) => {
           const resolvedMask = getUrlByMask(mask);
+          const callFrame = getCallFrame();
           return {
               parse(req) {
                   // Match the request during parsing to prevent matching it twice
@@ -3042,16 +3112,85 @@ ${queryParams
                   console.log('Response', loggedResponse);
                   console.groupEnd();
               },
+              getMetaInfo() {
+                  return {
+                      type: 'rest',
+                      header: `[rest] ${method} ${mask.toString()}`,
+                      mask,
+                      callFrame,
+                  };
+              },
           };
       };
   };
   const rest = {
+      /**
+       * Captures a HEAD request by a given path.
+       * @example
+       * rest.head('/numbers', (req, res, ctx) => {
+       *   return res(ctx.status(302))
+       * })
+       * @see {@link https://mswjs.io/docs/api/rest `rest`}
+       */
       head: createRestHandler(exports.RESTMethods.HEAD),
+      /**
+       * Captures a GET request by a given path.
+       * @example
+       * rest.get('/numbers', (req, res, ctx) => {
+       *   return res(ctx.json([1, 2, 3]))
+       * })
+       * @see {@link https://mswjs.io/docs/api/rest `rest`}
+       */
       get: createRestHandler(exports.RESTMethods.GET),
+      /**
+       * Captures a POST request by a given path.
+       * @example
+       * rest.post('/numbers', (req, res, ctx) => {
+       *   return res(ctx.text('success'))
+       * })
+       * @see {@link https://mswjs.io/docs/api/rest `rest`}
+       */
       post: createRestHandler(exports.RESTMethods.POST),
+      /**
+       * Captures a PUT request by a given path.
+       * @example
+       * rest.put('/numbers', (req, res, ctx) => {
+       *   const { numbers } = req.body
+       *   return res(ctx.json(numbers))
+       * })
+       * @see {@link https://mswjs.io/docs/api/rest `rest`}
+       */
       put: createRestHandler(exports.RESTMethods.PUT),
+      /**
+       * Captures a DELETE request by a given path.
+       * @example
+       * rest.delete('/numbers', (req, res, ctx) => {
+       *   const index = req.url.searchParams.get('index')
+       *   prevNumbers.splice(index, 1)
+       *   return res(ctx.json(nextNumbers))
+       * })
+       * @see {@link https://mswjs.io/docs/api/rest `rest`}
+       */
       delete: createRestHandler(exports.RESTMethods.DELETE),
+      /**
+       * Captures a PATCH request by a given path.
+       * @example
+       * rest.patch('/numbers', (req, res, ctx) => {
+       *   const { numbers } = req.body
+       *   const nextNumbers = prevNumbers.concat(number)
+       *   return res(ctx.json(nextNumbers))
+       * })
+       * @see {@link https://mswjs.io/docs/api/rest `rest`}
+       */
       patch: createRestHandler(exports.RESTMethods.PATCH),
+      /**
+       * Captures an OPTIONS request by a given path.
+       * @example
+       * rest.options('/numbers', (req, res, ctx) => {
+       *   return res(ctx.set('Allow', 'GET,HEAD,POST'))
+       * })
+       * @see {@link https://mswjs.io/docs/api/rest `rest`}
+       */
       options: createRestHandler(exports.RESTMethods.OPTIONS),
   };
 
@@ -6196,6 +6335,7 @@ ${queryParams
       };
   }
   function graphQLRequestHandler(expectedOperationType, expectedOperationName, mask, resolver) {
+      const callFrame = getCallFrame();
       return {
           resolver,
           parse(req) {
@@ -6267,6 +6407,17 @@ ${queryParams
               console.log('Response:', loggedResponse);
               console.groupEnd();
           },
+          getMetaInfo() {
+              const header = expectedOperationType === 'all'
+                  ? `[graphql] ${expectedOperationType} (origin: ${mask.toString()})`
+                  : `[graphql] ${expectedOperationType} ${expectedOperationName} (origin: ${mask.toString()})`;
+              return {
+                  type: 'graphql',
+                  header,
+                  mask,
+                  callFrame,
+              };
+          },
       };
   }
   const createGraphQLScopedHandler = (expectedOperationType, mask) => {
@@ -6280,10 +6431,42 @@ ${queryParams
       };
   };
   const graphqlStandardHandlers = {
+      /**
+       * Captures any GraphQL operation, regardless of its name, under the current scope.
+       * @example
+       * graphql.operation((req, res, ctx) => {
+       *   return res(ctx.data({ name: 'John' }))
+       * })
+       * @see {@link https://mswjs.io/docs/api/graphql/operation `graphql.operation()`}
+       */
       operation: createGraphQLOperationHandler('*'),
+      /**
+       * Captures a GraphQL query by a given name.
+       * @example
+       * graphql.query('GetUser', (req, res, ctx) => {
+       *   return res(ctx.data({ user: { name: 'John' } }))
+       * })
+       * @see {@link https://mswjs.io/docs/api/graphql/query `graphql.query()`}
+       */
       query: createGraphQLScopedHandler('query', '*'),
+      /**
+       * Captures a GraphQL mutation by a given name.
+       * @example
+       * graphql.mutation('SavePost', (req, res, ctx) => {
+       *   return res(ctx.data({ post: { id: 'abc-123' } }))
+       * })
+       * @see {@link https://mswjs.io/docs/api/graphql/mutation `graphql.mutation()`}
+       */
       mutation: createGraphQLScopedHandler('mutation', '*'),
   };
+  /**
+   * Creates a GraphQL mocking API scoped to the given endpoint.
+   * @param uri Endpoint URL, or path.
+   * @example
+   * const api = graphql.link('https://api.site.com/graphql)
+   * api.query('GetUser', resolver)
+   * @see {@link https://mswjs.io/docs/api/graphql/link `graphql.link()`}
+   */
   function createGraphQLLink(uri) {
       return {
           operation: createGraphQLOperationHandler(uri),
@@ -6293,6 +6476,7 @@ ${queryParams
   }
   const graphql = Object.assign(Object.assign({}, graphqlStandardHandlers), { link: createGraphQLLink });
 
+  exports.compose = compose;
   exports.context = index;
   exports.createResponseComposition = createResponseComposition;
   exports.defaultContext = defaultContext;