Skip to content

Commit 8fae95d

Browse files
docs: add jsdoc for each public method
1 parent e6f6b90 commit 8fae95d

File tree

4 files changed

+822
-231
lines changed

4 files changed

+822
-231
lines changed

lib/broadcast-operator.ts

+120-35
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
2222
/**
2323
* Targets a room when emitting.
2424
*
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
2837
*/
2938
public to(room: Room | Room[]) {
3039
const rooms = new Set(this.rooms);
@@ -42,11 +51,14 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
4251
}
4352

4453
/**
45-
* Targets a room when emitting.
54+
* Targets a room when emitting. Similar to `to()`, but might feel clearer in some cases:
4655
*
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
5062
*/
5163
public in(room: Room | Room[]) {
5264
return this.to(room);
@@ -55,9 +67,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
5567
/**
5668
* Excludes a room when emitting.
5769
*
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
6182
*/
6283
public except(room: Room | Room[]) {
6384
const exceptRooms = new Set(this.exceptRooms);
@@ -77,9 +98,11 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
7798
/**
7899
* Sets the compress flag.
79100
*
101+
* @example
102+
* io.compress(false).emit("hello");
103+
*
80104
* @param compress - if `true`, compresses the sending data
81105
* @return a new BroadcastOperator instance
82-
* @public
83106
*/
84107
public compress(compress: boolean) {
85108
const flags = Object.assign({}, this.flags, { compress });
@@ -96,8 +119,10 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
96119
* receive messages (because of network slowness or other issues, or because they’re connected through long polling
97120
* and is in the middle of a request-response cycle).
98121
*
122+
* @example
123+
* io.volatile.emit("hello"); // the clients may or may not receive it
124+
*
99125
* @return a new BroadcastOperator instance
100-
* @public
101126
*/
102127
public get volatile() {
103128
const flags = Object.assign({}, this.flags, { volatile: true });
@@ -112,8 +137,11 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
112137
/**
113138
* Sets a modifier for a subsequent event emission that the event data will only be broadcast to the current node.
114139
*
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
117145
*/
118146
public get local() {
119147
const flags = Object.assign({}, this.flags, { local: true });
@@ -128,14 +156,15 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
128156
/**
129157
* Adds a timeout in milliseconds for the next operation
130158
*
131-
* <pre><code>
132-
*
159+
* @example
133160
* 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+
* }
135166
* });
136167
*
137-
* </pre></code>
138-
*
139168
* @param timeout
140169
*/
141170
public timeout(timeout: number) {
@@ -151,8 +180,23 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
151180
/**
152181
* Emits to all clients.
153182
*
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+
*
154199
* @return Always true
155-
* @public
156200
*/
157201
public emit<Ev extends EventNames<EmitEvents>>(
158202
ev: Ev,
@@ -235,7 +279,8 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
235279
/**
236280
* Gets a list of clients.
237281
*
238-
* @public
282+
* @deprecated this method will be removed in the next major release, please use {@link Server#serverSideEmit} or
283+
* {@link fetchSockets} instead.
239284
*/
240285
public allSockets(): Promise<Set<SocketId>> {
241286
if (!this.adapter) {
@@ -247,9 +292,28 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
247292
}
248293

249294
/**
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();
251302
*
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+
* }
253317
*/
254318
public fetchSockets(): Promise<RemoteSocket<EmitEvents, SocketData>[]> {
255319
return this.adapter
@@ -274,10 +338,19 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
274338
}
275339

276340
/**
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
278346
*
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
281354
*/
282355
public socketsJoin(room: Room | Room[]): void {
283356
this.adapter.addSockets(
@@ -291,10 +364,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
291364
}
292365

293366
/**
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"]);
295377
*
296-
* @param room
297-
* @public
378+
* @param room - a room, or an array of rooms
298379
*/
299380
public socketsLeave(room: Room | Room[]): void {
300381
this.adapter.delSockets(
@@ -308,10 +389,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
308389
}
309390

310391
/**
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);
312402
*
313403
* @param close - whether to close the underlying connection
314-
* @public
315404
*/
316405
public disconnectSockets(close: boolean = false): void {
317406
this.adapter.disconnectSockets(
@@ -370,7 +459,6 @@ export class RemoteSocket<EmitEvents extends EventsMap, SocketData>
370459
* Joins a room.
371460
*
372461
* @param {String|Array} room - room or array of rooms
373-
* @public
374462
*/
375463
public join(room: Room | Room[]): void {
376464
return this.operator.socketsJoin(room);
@@ -380,7 +468,6 @@ export class RemoteSocket<EmitEvents extends EventsMap, SocketData>
380468
* Leaves a room.
381469
*
382470
* @param {String} room
383-
* @public
384471
*/
385472
public leave(room: Room): void {
386473
return this.operator.socketsLeave(room);
@@ -391,8 +478,6 @@ export class RemoteSocket<EmitEvents extends EventsMap, SocketData>
391478
*
392479
* @param {Boolean} close - if `true`, closes the underlying connection
393480
* @return {Socket} self
394-
*
395-
* @public
396481
*/
397482
public disconnect(close = false): this {
398483
this.operator.disconnectSockets(close);

0 commit comments

Comments
 (0)