0
# NestJS Platform Socket.IO
1

2
NestJS Platform Socket.IO provides a Socket.IO adapter implementation for the NestJS WebSocket framework. It enables real-time WebSocket communication in NestJS applications by implementing the AbstractWsAdapter interface, offering seamless integration with Socket.IO's robust WebSocket protocol with fallback support for older browsers.
3

4
## Package Information
5

6
- **Package Name**: @nestjs/platform-socket.io
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @nestjs/platform-socket.io`
10

11
## Core Imports
12

13
```typescript
14
import { IoAdapter } from '@nestjs/platform-socket.io';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { IoAdapter } = require('@nestjs/platform-socket.io');
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { IoAdapter } from '@nestjs/platform-socket.io';
27
import { NestFactory } from '@nestjs/core';
28
import { INestApplication } from '@nestjs/common';
29

30
// Set up Socket.IO adapter in NestJS application
31
const app = await NestFactory.create(AppModule);
32
app.useWebSocketAdapter(new IoAdapter(app));
33

34
// Create custom server configuration
35
const adapter = new IoAdapter(app);
36
const server = adapter.create(3001, {
37
  cors: {
38
    origin: "http://localhost:3000",
39
    credentials: true
40
  }
41
});
42
```
43

44
## Architecture
45

46
The IoAdapter extends NestJS's AbstractWsAdapter to provide Socket.IO specific implementations:
47

48
- **Server Creation**: Handles Socket.IO server instantiation and configuration
49
- **Namespace Support**: Manages Socket.IO namespaces for organizing connections
50
- **Message Handling**: Routes messages between NestJS and Socket.IO using RxJS observables
51
- **Payload Processing**: Transforms Socket.IO payloads and handles acknowledgment functions
52
- **Connection Management**: Manages client connections and disconnections
53

54
## Capabilities
55

56
### Server Creation
57

58
Creates Socket.IO server instances with flexible configuration options including namespace support.
59

60
```typescript { .api }
61
/**
62
 * Creates a Socket.IO server instance with optional configuration
63
 * @param port - Port number for the server
64
 * @param options - Optional server configuration including namespace and existing server
65
 * @returns Socket.IO server instance
66
 */
67
create(
68
  port: number,
69
  options?: ServerOptions & { namespace?: string; server?: any }
70
): Server;
71

72
/**
73
 * Creates a raw Socket.IO server instance
74
 * @param port - Port number for the server  
75
 * @param options - Optional server configuration
76
 * @returns Socket.IO server instance
77
 */
78
createIOServer(port: number, options?: any): any;
79
```
80

81
### Message Handler Binding
82

83
Binds NestJS message handlers to Socket.IO client sockets with RxJS observables for reactive message processing.
84

85
```typescript { .api }
86
/**
87
 * Binds message handlers to a Socket.IO client socket with RxJS observables
88
 * @param socket - Socket.IO client socket instance
89
 * @param handlers - Array of message handler mappings
90
 * @param transform - Transform function for data processing with observables
91
 */
92
bindMessageHandlers(
93
  socket: Socket,
94
  handlers: MessageMappingProperties[],
95
  transform: (data: any) => Observable<any>
96
);
97
```
98

99
### Payload Processing
100

101
Processes Socket.IO payloads to extract data and acknowledgment callbacks for proper message handling.
102

103
```typescript { .api }
104
/**
105
 * Maps incoming Socket.IO payload to structured data with optional acknowledgment callback
106
 * @param payload - Raw payload from Socket.IO
107
 * @returns Structured payload with optional acknowledgment function
108
 */
109
mapPayload(payload: unknown): { data: any; ack?: Function };
110
```
111

112
### Server Management
113

114
Handles Socket.IO server lifecycle including proper shutdown and cleanup.
115

116
```typescript { .api }
117
/**
118
 * Closes the Socket.IO server instance
119
 * @param server - Socket.IO server instance to close
120
 * @returns Promise that resolves when server is closed
121
 */
122
async close(server: Server): Promise<void>;
123
```
124

125
### Inherited Connection Management
126

127
Provides connection lifecycle management through inherited AbstractWsAdapter methods.
128

129
```typescript { .api }
130
/**
131
 * Binds client connection event handler
132
 * @param server - Socket.IO server instance
133
 * @param callback - Function to call when clients connect
134
 */
135
bindClientConnect(server: any, callback: Function): any;
136

137
/**
138
 * Binds client disconnection event handler  
139
 * @param client - Socket.IO client socket
140
 * @param callback - Function to call when client disconnects
141
 */
142
bindClientDisconnect(client: any, callback: Function): any;
143

144
/**
145
 * Controls whether to force close connections
146
 */
147
forceCloseConnections: boolean;
148
```
149

150
## Types
151

152
```typescript { .api }
153
/**
154
 * Socket.IO adapter for NestJS WebSocket framework
155
 * Extends AbstractWsAdapter to provide Socket.IO specific functionality
156
 */
157
class IoAdapter extends AbstractWsAdapter {
158
  constructor(appOrHttpServer?: INestApplicationContext | object);
159
}
160

161
/**
162
 * Socket.IO server configuration options with NestJS extensions
163
 * Based on Socket.IO ServerOptions with additional namespace and server properties
164
 */
165
interface ServerOptions {
166
  namespace?: string;
167
  server?: any;
168
  cors?: any;
169
  path?: string;
170
  connectTimeout?: number;
171
  pingTimeout?: number;
172
  pingInterval?: number;
173
  [key: string]: any;
174
}
175

176
/**
177
 * Message handler mapping properties for NestJS WebSocket routing
178
 */
179
interface MessageMappingProperties {
180
  message: any;
181
  methodName: string;
182
  callback: (...args: any[]) => Observable<any> | Promise<any>;
183
}
184

185
/**
186
 * Socket.IO server instance
187
 */
188
interface Server {
189
  of(namespace: string): Server;
190
  httpServer?: any;
191
}
192

193
/**
194
 * Socket.IO client socket instance
195
 */  
196
interface Socket {
197
  emit(event: string, data: any): void;
198
  on(event: string, callback: Function): void;
199
}
200

201
/**
202
 * NestJS application context interface for dependency injection
203
 */
204
interface INestApplicationContext {
205
  get<TInput = any, TResult = TInput>(
206
    typeOrToken: any,
207
    options?: any
208
  ): TResult;
209
}
210

211
/**
212
 * RxJS Observable for reactive programming
213
 */
214
interface Observable<T> {
215
  subscribe(observer: any): any;
216
}
217
```