Custom response transformer API

[kettanaito]

What:

I suggest to add a full support for custom response transformers.

Why:

With the functional composition it is easy to create custom response transformers.

• The library must expose its default response transformers (text, json, delay, etc.) so the end developer may combine them to their liking.
• The libarary must explain the call signature of response transformers, so custom functions can run as transformers.

How:

• Expose default response transformers (context) from the library's module directly, so they can be reused to create custom transformers
• Think how to make the writing of functional composition easier, especially on projects that do not use functional utils.
• Think about the call signature of default transformers. It would be nice to have them curried, so they can be used outside of functional composition

[kettanaito]

Currently is possible to provide custom response transformers as long as they follow this call signature:

import { MockedResponse } from 'msw'

const myCustomTransformer = (res: MockedResponse) => res

Most likely you'd be introducing your own high-order functions that return response transformers. Here's an example:

import { MockedResponse } from 'msw'

const halJson = (body: Record<string, any>) => {
  return (res: MockedResponse) => {
    res.headers.set('Content-Type', 'application/hal+json')
    res.body = JSON.stringify(body)
    return res
  }
}

This is exactly how standard ctx utils are implemented at the moment. I think this should be put into documentation somewhere.

[kettanaito]

I've added a recipe to the documentation on how to create your Custom context utility. It would be nice to add an integration test for such custom utility before closing this task.

[kettanaito]

Example of a custom response transformer is illustrated as a context utility function halJson() in this test suite:

https://github.com/open-draft/msw/blob/b2c10e623a099e64a7fe3b33aab3a00da4007f17/test/rest-api/custom-request-handler.mocks.ts#L44-L49

In the test above it's being used with a custom request handler and, thus, is provided in the defineContext property of the handler. If you wish to have an isolated context utility move it to a separate function and cover with typings according to those mentioned in the documentation.