NestJS Socket.io Client

Socket.io Client for NestJS based on socket.io-client

Install

1npm i nestjs-io-client

Register module

Configuration params

nestjs-io-client can be configured with this options:

1/**
2 * Socket.io Client options
3 * @see {@link https://socket.io/docs/v4/client-api/#iourl}
4 */
5interface IoClientModuleOptions {
6  /**
7   * Required parameter a URL to connect.
8   * such as http://localhost:3000/my-namespace or ws://localhost:3000/my-namespace.
9   */
10  uri: string;
11
12  /**
13   * Optional parameter a client or http request options.
14   */
15  options?: Partial<ManagerOptions & SocketOptions>
16}

Synchronous configuration

Use IoClientModule.forRoot method with Options interface:

1import { IoClientModule } from 'nestjs-io-client'
2
3@Module({
4  imports: [
5    IoClientModule.forRoot({
6      uri: 'ws://localhost:3000/my-namespace',
7      options: {
8        reconnectionDelayMax: 10000,
9        auth: { token: '123' },
10        query: {
11          foo: 'value'
12        },
13      },
14    }),
15  ],
16  ...
17})
18class MyModule {}

Asynchronous configuration

With IoClientModule.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:

1import { Module, Injectable } from '@nestjs/common'
2import { IoClientModule } from 'nestjs-io-client'
3
4@Injectable()
5class ConfigService {
6  public readonly uri = 'ws://localhost:3000/my-namespace'
7}
8
9@Module({
10  providers: [ConfigService],
11  exports: [ConfigService]
12})
13class ConfigModule {}
14
15@Module({
16  imports: [
17    IoClientModule.forRootAsync({
18      imports: [ConfigModule],
19      inject: [ConfigService],
20      useFactory: (config: ConfigService) => {
21        return {
22          uri: config.uri,
23        }
24      },
25    }),
26  ],
27  ...
28})
29class MyModule {}

Or you can just pass ConfigService to providers, if you don't have any ConfigModule:

1import { Module, Injectable } from '@nestjs/common'
2import { IoClientModule } from 'nestjs-io-client'
3
4@Injectable()
5class ConfigService {
6  public readonly uri = 'ws://localhost:3000/my-namespace'
7}
8
9@Module({
10  imports: [
11    IoClientModule.forRootAsync({
12      providers: [ConfigService],
13      inject: [ConfigService],
14      useFactory: (config: ConfigService) => {
15        return {
16          uri: config.uri,
17        }
18      },
19    }),
20  ],
21  controllers: [TestController]
22})
23class TestModule {}

IoClient

IoClient implements a Socket. So if you are familiar with it, you are ready to go.

1import { Injectable } from '@nestjs/common'
2import {
3  InjectIoClientProvider,
4  IoClient,
5  OnConnect,
6  OnConnectError,
7  EventListener,
8} from 'nestjs-io-client';
9
10@Injectable()
11class TestService {
12  constructor(
13    @InjectIoClientProvider()
14    private readonly io: IoClient,
15  ) {}
16
17  @OnConnect()
18  connect() {
19    console.log('connected!')
20    console.log(this.io.id); // "G5p5..."
21    console.log(this.io.connected); // true
22  }
23  
24  @OnConnectError()
25  connectError(err: Error) {
26    console.error(`An error occurs: ${err}`)
27  }
28
29  @EventListener('news')
30  message(data: any) {
31    console.log(data);
32  }
33}

Socket.io Events

EventListener

@EventListener decorator will handle any event emitted from socket.io server.

1import { Injectable } from '@nestjs/common'
2import {
3  EventListener
4} from 'nestjs-io-client';
5
6@Injectable()
7class TestService {
8  @EventListener('connect')
9  open() {
10    console.log('The connection is established.')
11  }
12  
13  @EventListener('ping')
14  ping() {
15    console.log('A ping is received from the server.')
16  }
17  
18  @EventListener('reconnect')
19  unexpectedResponse() {
20    console.log('successful reconnection')
21  }
22  
23  @EventListener('news')
24  upgrade(data: any) {
25    console.log(data);
26  }
27}

OnConnect

@OnConnect is a shortcut for @EventListener('connect'). Event emitted when the connection is established.

1import { Injectable } from '@nestjs/common'
2import {
3  OnConnect
4} from 'nestjs-io-client';
5
6@Injectable()
7class TestService {
8  @OnConnect()
9  connect() {
10    console.log('The connection is established.')
11  }
12}

OnDisconnect

@OnDisconnect is a shortcut for @EventListener('disconnect') Event emitted when the connection is closed. reason is a string explaining why the connection has been closed.

1import { Injectable } from '@nestjs/common'
2import {
3  IoClient,
4  OnDisconnect
5} from 'nestjs-io-client';
6
7@Injectable()
8class TestService {
9  @OnDisconnect()
10  disconnect(reason: IoClient.DisconnectReason) {
11    if (reason === "io server disconnect") {
12      // the disconnection was initiated by the server, you need to reconnect manually
13      socket.connect();
14    }
15    // else the socket will automatically try to reconnect
16  }
17}

OnConnectError

@OnConnectError is a shortcut for @EventListener('connect_error') Event emitted when when an namespace middleware error occurs.

1import { Injectable } from '@nestjs/common'
2import {
3  OnConnectError
4} from 'nestjs-io-client';
5
6@Injectable()
7class TestService {
8  @OnConnectError()
9  connectError(err: Error) {
10    console.error(`An error occurs: ${err}`)
11  }
12}

Testing a class that uses @InjectIoClientProvider

This package exposes a getIoClientToken() function that returns a prepared injection token based on the provided context. Using this token, you can easily provide a mock implementation of the Socket using any of the standard custom provider techniques, including useClass, useValue, and useFactory.

1const module: TestingModule = await Test.createTestingModule({
2  providers: [
3    MyService,
4    {
5      provide: getIoClientToken(),
6      useValue: mockProvider,
7    },
8  ],
9}).compile();

Change Log

See Changelog for more information.

Contributing

Contributions welcome! See Contributing.

Collaborators

• Jose Ramirez

License

Licensed under the Apache 2.0 - see the LICENSE file for details.