@@ -22,9 +22,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
22
22
/**
23
23
* Targets a room when emitting.
24
24
*
25
- * @param room
26
- * @return a new BroadcastOperator instance
27
- * @public
25
+ * @example
26
+ * // the “foo” event will be broadcast to all connected clients in the “room-101” room
27
+ * io.to("room-101").emit("foo", "bar");
28
+ *
29
+ * // with an array of rooms (a client will be notified at most once)
30
+ * io.to(["room-101", "room-102"]).emit("foo", "bar");
31
+ *
32
+ * // with multiple chained calls
33
+ * io.to("room-101").to("room-102").emit("foo", "bar");
34
+ *
35
+ * @param room - a room, or an array of rooms
36
+ * @return a new {@link BroadcastOperator} instance for chaining
28
37
*/
29
38
public to ( room : Room | Room [ ] ) {
30
39
const rooms = new Set ( this . rooms ) ;
@@ -42,11 +51,14 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
42
51
}
43
52
44
53
/**
45
- * Targets a room when emitting.
54
+ * Targets a room when emitting. Similar to `to()`, but might feel clearer in some cases:
46
55
*
47
- * @param room
48
- * @return a new BroadcastOperator instance
49
- * @public
56
+ * @example
57
+ * // disconnect all clients in the "room-101" room
58
+ * io.in("room-101").disconnectSockets();
59
+ *
60
+ * @param room - a room, or an array of rooms
61
+ * @return a new {@link BroadcastOperator} instance for chaining
50
62
*/
51
63
public in ( room : Room | Room [ ] ) {
52
64
return this . to ( room ) ;
@@ -55,9 +67,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
55
67
/**
56
68
* Excludes a room when emitting.
57
69
*
58
- * @param room
59
- * @return a new BroadcastOperator instance
60
- * @public
70
+ * @example
71
+ * // the "foo" event will be broadcast to all connected clients, except the ones that are in the "room-101" room
72
+ * io.except("room-101").emit("foo", "bar");
73
+ *
74
+ * // with an array of rooms
75
+ * io.except(["room-101", "room-102"]).emit("foo", "bar");
76
+ *
77
+ * // with multiple chained calls
78
+ * io.except("room-101").except("room-102").emit("foo", "bar");
79
+ *
80
+ * @param room - a room, or an array of rooms
81
+ * @return a new {@link BroadcastOperator} instance for chaining
61
82
*/
62
83
public except ( room : Room | Room [ ] ) {
63
84
const exceptRooms = new Set ( this . exceptRooms ) ;
@@ -77,9 +98,11 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
77
98
/**
78
99
* Sets the compress flag.
79
100
*
101
+ * @example
102
+ * io.compress(false).emit("hello");
103
+ *
80
104
* @param compress - if `true`, compresses the sending data
81
105
* @return a new BroadcastOperator instance
82
- * @public
83
106
*/
84
107
public compress ( compress : boolean ) {
85
108
const flags = Object . assign ( { } , this . flags , { compress } ) ;
@@ -96,8 +119,10 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
96
119
* receive messages (because of network slowness or other issues, or because they’re connected through long polling
97
120
* and is in the middle of a request-response cycle).
98
121
*
122
+ * @example
123
+ * io.volatile.emit("hello"); // the clients may or may not receive it
124
+ *
99
125
* @return a new BroadcastOperator instance
100
- * @public
101
126
*/
102
127
public get volatile ( ) {
103
128
const flags = Object . assign ( { } , this . flags , { volatile : true } ) ;
@@ -112,8 +137,11 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
112
137
/**
113
138
* Sets a modifier for a subsequent event emission that the event data will only be broadcast to the current node.
114
139
*
115
- * @return a new BroadcastOperator instance
116
- * @public
140
+ * @example
141
+ * // the “foo” event will be broadcast to all connected clients on this node
142
+ * io.local.emit("foo", "bar");
143
+ *
144
+ * @return a new {@link BroadcastOperator} instance for chaining
117
145
*/
118
146
public get local ( ) {
119
147
const flags = Object . assign ( { } , this . flags , { local : true } ) ;
@@ -128,14 +156,15 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
128
156
/**
129
157
* Adds a timeout in milliseconds for the next operation
130
158
*
131
- * <pre><code>
132
- *
159
+ * @example
133
160
* io.timeout(1000).emit("some-event", (err, responses) => {
134
- * // ...
161
+ * if (err) {
162
+ * // some clients did not acknowledge the event in the given delay
163
+ * } else {
164
+ * console.log(responses); // one response per client
165
+ * }
135
166
* });
136
167
*
137
- * </pre></code>
138
- *
139
168
* @param timeout
140
169
*/
141
170
public timeout ( timeout : number ) {
@@ -151,8 +180,23 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
151
180
/**
152
181
* Emits to all clients.
153
182
*
183
+ * @example
184
+ * // the “foo” event will be broadcast to all connected clients
185
+ * io.emit("foo", "bar");
186
+ *
187
+ * // the “foo” event will be broadcast to all connected clients in the “room-101” room
188
+ * io.to("room-101").emit("foo", "bar");
189
+ *
190
+ * // with an acknowledgement expected from all connected clients
191
+ * io.timeout(1000).emit("some-event", (err, responses) => {
192
+ * if (err) {
193
+ * // some clients did not acknowledge the event in the given delay
194
+ * } else {
195
+ * console.log(responses); // one response per client
196
+ * }
197
+ * });
198
+ *
154
199
* @return Always true
155
- * @public
156
200
*/
157
201
public emit < Ev extends EventNames < EmitEvents > > (
158
202
ev : Ev ,
@@ -235,7 +279,8 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
235
279
/**
236
280
* Gets a list of clients.
237
281
*
238
- * @public
282
+ * @deprecated this method will be removed in the next major release, please use {@link Server#serverSideEmit} or
283
+ * {@link fetchSockets} instead.
239
284
*/
240
285
public allSockets ( ) : Promise < Set < SocketId > > {
241
286
if ( ! this . adapter ) {
@@ -247,9 +292,28 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
247
292
}
248
293
249
294
/**
250
- * Returns the matching socket instances
295
+ * Returns the matching socket instances. This method works across a cluster of several Socket.IO servers.
296
+ *
297
+ * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
298
+ *
299
+ * @example
300
+ * // return all Socket instances
301
+ * const sockets = await io.fetchSockets();
251
302
*
252
- * @public
303
+ * // return all Socket instances in the "room1" room
304
+ * const sockets = await io.in("room1").fetchSockets();
305
+ *
306
+ * for (const socket of sockets) {
307
+ * console.log(socket.id);
308
+ * console.log(socket.handshake);
309
+ * console.log(socket.rooms);
310
+ * console.log(socket.data);
311
+ *
312
+ * socket.emit("hello");
313
+ * socket.join("room1");
314
+ * socket.leave("room2");
315
+ * socket.disconnect();
316
+ * }
253
317
*/
254
318
public fetchSockets ( ) : Promise < RemoteSocket < EmitEvents , SocketData > [ ] > {
255
319
return this . adapter
@@ -274,10 +338,19 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
274
338
}
275
339
276
340
/**
277
- * Makes the matching socket instances join the specified rooms
341
+ * Makes the matching socket instances join the specified rooms.
342
+ *
343
+ * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
344
+ *
345
+ * @example
278
346
*
279
- * @param room
280
- * @public
347
+ * // make all socket instances join the "room1" room
348
+ * io.socketsJoin("room1");
349
+ *
350
+ * // make all socket instances in the "room1" room join the "room2" and "room3" rooms
351
+ * io.in("room1").socketsJoin(["room2", "room3"]);
352
+ *
353
+ * @param room - a room, or an array of rooms
281
354
*/
282
355
public socketsJoin ( room : Room | Room [ ] ) : void {
283
356
this . adapter . addSockets (
@@ -291,10 +364,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
291
364
}
292
365
293
366
/**
294
- * Makes the matching socket instances leave the specified rooms
367
+ * Makes the matching socket instances leave the specified rooms.
368
+ *
369
+ * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
370
+ *
371
+ * @example
372
+ * // make all socket instances leave the "room1" room
373
+ * io.socketsLeave("room1");
374
+ *
375
+ * // make all socket instances in the "room1" room leave the "room2" and "room3" rooms
376
+ * io.in("room1").socketsLeave(["room2", "room3"]);
295
377
*
296
- * @param room
297
- * @public
378
+ * @param room - a room, or an array of rooms
298
379
*/
299
380
public socketsLeave ( room : Room | Room [ ] ) : void {
300
381
this . adapter . delSockets (
@@ -308,10 +389,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
308
389
}
309
390
310
391
/**
311
- * Makes the matching socket instances disconnect
392
+ * Makes the matching socket instances disconnect.
393
+ *
394
+ * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
395
+ *
396
+ * @example
397
+ * // make all socket instances disconnect (the connections might be kept alive for other namespaces)
398
+ * io.disconnectSockets();
399
+ *
400
+ * // make all socket instances in the "room1" room disconnect and close the underlying connections
401
+ * io.in("room1").disconnectSockets(true);
312
402
*
313
403
* @param close - whether to close the underlying connection
314
- * @public
315
404
*/
316
405
public disconnectSockets ( close : boolean = false ) : void {
317
406
this . adapter . disconnectSockets (
@@ -370,7 +459,6 @@ export class RemoteSocket<EmitEvents extends EventsMap, SocketData>
370
459
* Joins a room.
371
460
*
372
461
* @param {String|Array } room - room or array of rooms
373
- * @public
374
462
*/
375
463
public join ( room : Room | Room [ ] ) : void {
376
464
return this . operator . socketsJoin ( room ) ;
@@ -380,7 +468,6 @@ export class RemoteSocket<EmitEvents extends EventsMap, SocketData>
380
468
* Leaves a room.
381
469
*
382
470
* @param {String } room
383
- * @public
384
471
*/
385
472
public leave ( room : Room ) : void {
386
473
return this . operator . socketsLeave ( room ) ;
@@ -391,8 +478,6 @@ export class RemoteSocket<EmitEvents extends EventsMap, SocketData>
391
478
*
392
479
* @param {Boolean } close - if `true`, closes the underlying connection
393
480
* @return {Socket } self
394
- *
395
- * @public
396
481
*/
397
482
public disconnect ( close = false ) : this {
398
483
this . operator . disconnectSockets ( close ) ;
0 commit comments