Unclear WebSocket Documentation

[dieeisenefaust]

Is there an existing issue for this?

• I have searched the existing issues

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).

Minimum reproduction code

N/A

Steps to reproduce

No response

Expected behavior

Clear, concise documentation.

Package

• I don't know. Or some 3rd-party package
• @nestjs/common
• @nestjs/core
• @nestjs/microservices
• @nestjs/platform-express
• @nestjs/platform-fastify
• @nestjs/platform-socket.io
• @nestjs/platform-ws
• @nestjs/testing
• @nestjs/websockets
• Other (see below)

Other package

No response

NestJS version

No response

Packages versions

N/A

Node.js version

No response

In which operating systems have you tested?

• macOS
• Windows
• Linux

Other

No response

[Tony133]

Hi, @dieeisenefaust

For issues regarding documentation you should open them in this repository here: https://github.com/nestjs/docs.nestjs.com

[dieeisenefaust]

Thanks @Tony133, when searching the issues before submitting I had found some concerning documentation so didn't realize there was a separate repo. This issue has been submitted on that repo here (https://github.com/nestjs/docs.nestjs.com/issues/2695)

[Tony133]

@dieeisenefaust since now you have also opened this issue in the documentation repository (nestjs/docs.nestjs.com#2695), I would say close this issue so that there are no duplicates.