Create clearer WebSocket documentation

[dieeisenefaust]

I'm submitting a...

• Regression
• Bug report
• Feature request
• [x ] Documentation issue or request (new chapter/page)
• Support request => Please do not submit support request here, instead post your question on Stack Overflow.

Current behavior

By searching answers on the web, like on StackOverflow, you can see that most solutions users have come up with don't conform with the approach NestJS expects/recommends. I believe this is due to lacking/misleading documentation. Even after hours of searching and putting the pieces together I can't be 100% sure I have it correct.

Instructions try to be 'general' for both the ws and Socket.io platforms. It would be much clearer to separate out documentation for each platform or to at least have platform specific instructions/examples next to each other since there are some fundimental functional differences.

How to return data from a @SubscribeMessage is not explained very clearly, especially with the difference b/w ws & Socket.io. Many of the examples show return data which doesn't work with Socket.io. The only section of the documentation to even hint at the expected message format for returning data using Socket.io is on Gateways > Multiple Responses and does not clearly state that Socket.io returns need to take the form of {event: eventName, data: dataObject}. It is also not intuative for users to figure out without clear instructions since pure Socket.io uses the label "type" instead of "event" (ex. "{ type: CONNECT_ERROR, namespace: "/", data: { message: "Not authorized" } }").

Even example projects like "02-gateways" (which is intended to be Socket.io specific, since there is a separate 'gateways-ws' example project) mixes one method with a return statement that will work and another that just has return data.

The end result is that the majority of solutions I have found posted online are the user invoking the server object in order to call the emit function even though, as stated in the NestJS documentation, this means you can't use interceptors on the results being sent back to the client.

WebSocket Exception Filter documentation also doesn't call out that the included BaseWsExceptionsFilter only works with Socket.io and not the ws platform. This is due to it using the emit function to send the error back to the client which is a function that doesn't exist in ws. I consider this an issue and have opened a separate case for this ( #11433). (Note: the examples on the Exceptions Filter page also reference a WsExceptionsFilter that doesn't appear to exist anymore and which, I believe, was renamed to or replaced by the BaseWsExceptionsFilter).

Expected behavior

Clear, concise documentation with supporting examples.

Minimal reproduction of the problem with instructions

What is the motivation / use case for changing the behavior?

Make the correct information available to NestJS users, reducing frustration, development time and suboptimal programming patterns.

Environment

For Tooling issues:

• Node version: 18.14.2

• Platform: Linux/Windows ( developement environment is running in WSL environment)

Others: