fix: add "listHandlers" method to server and worker

[AlexeiDarmin]

@kettanaito is something like this what you had in mind?

Change overview

This PR adds a listHandlers() method that returns a list of currently active handlers as suggested in #474 (comment).

You can list currently active handlers via server.printHandlers(). Alas, it prints the handlers summary stdout instead of returning a list. If you are interested, it'd be awesome to have a change where printHandlers() returns a list of handlers:

Additional change proposal

Now that devs would have access to individual handlers, handlers would benefit from having a .toString() or .stringSummary() to easily see a string summary of the handler. The logging logic within printHandlers could be moved to handler.toString(), then printHandlers would simply be:

 printHandlers() {
        currentHandlers.forEach((handler) => {
          console.log(handler.toString())
        })
      }

[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 50f6b9b:

Sandbox	Source
MSW React	Configuration

[kettanaito]

Hey, @AlexeiDarmin. Thank you for opening this on such a short notice!

I absolutely agree with the summary proposal and .toString() on individual handlers. A great idea. Would you have a chance to add it to this pull request?

[kettanaito]

We need to be cautious exposing internals, and currentHandlers is internals. I fear that developers will be tempted to meddle with this array directly. That should never happen. They should use explicit APIs like use or resetHandlers to affect the list of handlers, and listHandlers() must be purely readonly.

Maybe let's make this array readonly before exposing it?

// First, guard the array on the type level.
listHandlers(): ReadonlyArray<RequestHandler> {
  // Second, prevent mutations on runtime.
  const immutableHandlers = [...currentHandlers]
  Object.freeze(immutableHandlers)
  return immutableHandlers
}

[kettanaito]

If we go to the readonly list route (which I think we should), let's adjust this return type as well.

[kettanaito]

I absolutely love the changes! The only suggestion I have is to make sure that we expose a readonly array from listHandlers() so that people are not tempted to mutate it.

[kettanaito]

Since we're not deprecating printHandlers() just yet, I will rename this change to be a fix.

[kettanaito]

I've covered some of the previous suggestions, also added listHandlers to the worker API. Let's see if the tests pass.

[AlexeiDarmin]

@kettanaito thanks for applying the changes! I appreciate your feedback and was going to incorporate when I had a minute.

[kettanaito]

Released: v0.46.0 🎉

This has been released in v0.46.0!

• 📄 Release notes
• 📦 npm package

Make sure to always update to the latest version (npm i msw@latest) to get the newest features and bug fixes.

---

Predictable release automation by @ossjs/release.