Websocket Client for NestJS based on ws
npm i nestjs-websocketnestjs-websocket can be configured with this options:
/**
* WebSocket Client options
* @see {@link https://github.com/websockets/ws/blob/master/doc/ws.md#class-websocket}
*/
interface WebSocketModuleOptions {
/**
* Required parameter a URL to connect to.
* such as http://localhost:3000 or wss://localhost:3000.
*/
url: string | URL;
/**
* Optional parameter a list of subprotocols.
*/
protocols?: string | string[]
/**
* Optional parameter a client or http request options.
*/
options?: ClientOptions | ClientRequestArgs
}Use WebSocketModule.forRoot method with Options interface:
import { WebSocketModule } from 'nestjs-websocket'
@Module({
imports: [
WebSocketModule.forRoot({
url: 'ws://localhost:3000',
protocols: ['foo', 'bar'],
options: {
followRedirects: false,
handshakeTimeout: 10000,
maxPayload: 2000000,
maxRedirects: 10,
origin: 'http:/example.com',
perMessageDeflate: false,
protocolVersion: 1,
skipUTF8Validation: false,
},
}),
],
...
})
class MyModule {}With WebSocketModule.forRootAsync you can, for example, import your ConfigModule and inject ConfigService to use it in useFactory method.
useFactory should return object with Options interface
Here's an example:
import { Module, Injectable } from '@nestjs/common'
import { WebSocketModule } from 'nestjs-websocket'
@Injectable()
class ConfigService {
public readonly url = 'ws://localhost:3000'
}
@Module({
providers: [ConfigService],
exports: [ConfigService]
})
class ConfigModule {}
@Module({
imports: [
WebSocketModule.forRootAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (config: ConfigService) => {
return {
url: config.url,
}
},
}),
],
...
})
class MyModule {}Or you can just pass ConfigService to providers, if you don't have any ConfigModule:
import { Module, Injectable } from '@nestjs/common'
import { WebSocketModule } from 'nestjs-websocket'
@Injectable()
class ConfigService {
public readonly url = 'ws://localhost:3000'
}
@Module({
imports: [
WebSocketModule.forRootAsync({
providers: [ConfigService],
inject: [ConfigService],
useFactory: (config: ConfigService) => {
return {
url: config.url,
}
},
}),
],
controllers: [TestController]
})
class TestModule {}WebSocketClient implements a WebSocket. So if you are familiar with it, you are ready to go.
import { Injectable } from '@nestjs/common'
import {
InjectWebSocketProvider,
WebSocketClient,
OnOpen,
OnMessage,
} from 'nestjs-websocket';
@Injectable()
class TestService {
private data: Record<any, any> = {}
constructor(
@InjectWebSocketProvider()
private readonly ws: WebSocketClient,
) {}
@OnOpen()
onOpen() {
this.ws.send(JSON.stringify(eventData))
}
@OnMessage()
message(data: WebSocketClient.Data) {
this.data = JSON.parse(data.toString())
}
async getData(): Promise<Record<any, any>> {
return this.data
}
}@EventListener decorator will handle any event emitted from websocket server.
import { Injectable } from '@nestjs/common'
import { ClientRequest, IncomingMessage } from 'http'
import {
EventListener
} from 'nestjs-websocket';
@Injectable()
class TestService {
@EventListener('open')
open() {
console.log('The connection is established.')
}
@EventListener('ping')
ping(data: Buffer) {
console.log(`A ping ${data.toString()} is received from the server.`)
}
@EventListener('unexpected-response')
unexpectedResponse(request: ClientRequest, response: IncomingMessage) {
console.log(`The server response ${response} is not the expected one.`)
}
@EventListener('upgrade')
upgrade(response: IncomingMessage) {
console.log(`Response headers ${response} are received from the server as part of the handshake.`)
}
}@OnOpen is a shortcut for @EventListener('open'). Event emitted when the connection is established.
import { Injectable } from '@nestjs/common'
import {
OnOpen
} from 'nestjs-websocket';
@Injectable()
class TestService {
@OnOpen()
open() {
console.log('The connection is established.')
}
}@OnClose is a shortcut for @EventListener('close') Event emitted when the connection is closed. code property is a numeric value for status code explaining why the connection has been closed. reason is a Buffer containing a human-readable string explaining why the connection has been closed.
import { Injectable } from '@nestjs/common'
import {
OnClose
} from 'nestjs-websocket';
@Injectable()
class TestService {
@OnClose()
close(code: number, reason: string) {
console.log(`The connection is closed. Reason: ${code} - ${reason}`)
}
}@OnError is a shortcut for @EventListener('error'). Event emitted when an error occurs. Errors may have a .code property.
import { Injectable } from '@nestjs/common'
import {
OnError
} from 'nestjs-websocket';
@Injectable()
class TestService {
@OnError()
error(err: Error) {
console.log(`An error occurs: ${err}`)
}
}@OnMessage is a shortcut for @EventListener('message'). Event emitted when a message is received. data is the message content.
import { Injectable } from '@nestjs/common'
import {
OnMessage
} from 'nestjs-websocket';
@Injectable()
class TestService {
@OnMessage()
message(data: WebSocketClient.Data) {
console.log(`Data received: ${JSON.parse(data.toString())}`)
}
}This package exposes a getWebSocketToken() function that returns a prepared injection token based on the provided context.
Using this token, you can easily provide a mock implementation of the ws using any of the standard custom provider techniques, including useClass, useValue, and useFactory.
const module: TestingModule = await Test.createTestingModule({
providers: [
MyService,
{
provide: getWebSocketToken(),
useValue: mockProvider,
},
],
}).compile();See Changelog for more information.
Contributions welcome! See Contributing.
Licensed under the Apache 2.0 - see the LICENSE file for details.