Re-designs the RequestHandler API

[kettanaito]

This pull request introduces a BREAKING CHANGE.
This request does not introduce any direct public-facing changes. The exception is custom request handlers authors.

GitHub

• Closes Non-GraphQL requests with 'query' in URL params fail with AbortError #489 (Differentiating a GraphQL query from a compatible REST API request #535) by introducing an improved GraphQL request parsing logic.
• Related to RFC: Request handler API #290
• Closes build: validate types #579

Motivation

The Request Handler API can be reviewed and improved based on the usage scenarios and request handling workflow that we've learned.

• Revisit and standardize the lifecycle of a request handler.
• Return a clear execution result upon calling handler.run() that includes mocked response, as well as additional request information (i.e. parsing results).
• Simplify the creation of custom request handlers by extending a base RequestHandler class, or any standard request handler exported by the library (i.e. RestHandler or GraphQLHandler).

Example

// Example of a REST API request handler that extends a base `RequestHandler` class.
const handler = new RestHandler('GET', '/user', resolver)

// Test if a given request satisfies the handler.
handler.test(req)

// Resolve the request: parses, tests, and produces a mocked response.
handler.run(req)

Roadmap

• Introduce a new Request Handler API.
• Migrate rest request handlers.
• Migrate graphql request handlers.
• Clean up.
• Resolve all @fixme comments.
• Ensure that test/msw-api/setup-worker/start/on-unhandled-request/suggestions.test.ts doesn't error and can perform requests that intentionally fail without polluting the stdout.

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit b96fd21:

Sandbox	Source
MSW React	Configuration

[kettanaito]

REST API request handlers have been successfully migrated to the new Request Handler API.

[kettanaito]

GraphQL API request handlers have been successfully migrated to the new Request Handler API.

[kettanaito]

@timdeschryver I'm addressing the types validation in dbd5bef with the test:ts command. It's going to validate the usage scenarios in terms of type compliance against the built library. I've checked and it also detects type violations in d.ts and glossary modules (something we tried to address in #579).

[cdomigan]

It looks like the docs are now out of date on creating Custom Handlers? https://mswjs.io/docs/recipes/custom-request-handler

[kettanaito]

@cdomigan, looks like you're right. That recipe needs updating to be in sync with these changes.

Please, would you be interested in adjusting that recipe? Its source is here.