Skip to content

Commit

Permalink
docs: add jsdoc for each public method
Browse files Browse the repository at this point in the history
  • Loading branch information
@darrachequesne
darrachequesne committed Oct 14, 2022
1 parent e6f6b90 commit 8fae95d
Show file tree
Hide file tree
Showing 4 changed files with 822 additions and 231 deletions.
155 changes: 120 additions & 35 deletions lib/broadcast-operator.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
/**
* Targets a room when emitting.
*
* @param room
* @return a new BroadcastOperator instance
* @public
* @example
* // the “foo” event will be broadcast to all connected clients in the “room-101” room
* io.to("room-101").emit("foo", "bar");
*
* // with an array of rooms (a client will be notified at most once)
* io.to(["room-101", "room-102"]).emit("foo", "bar");
*
* // with multiple chained calls
* io.to("room-101").to("room-102").emit("foo", "bar");
*
* @param room - a room, or an array of rooms
* @return a new {@link BroadcastOperator} instance for chaining
*/
public to(room: Room | Room[]) {
const rooms = new Set(this.rooms);
Expand All @@ -42,11 +51,14 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
}

/**
* Targets a room when emitting.
* Targets a room when emitting. Similar to `to()`, but might feel clearer in some cases:
*
* @param room
* @return a new BroadcastOperator instance
* @public
* @example
* // disconnect all clients in the "room-101" room
* io.in("room-101").disconnectSockets();
*
* @param room - a room, or an array of rooms
* @return a new {@link BroadcastOperator} instance for chaining
*/
public in(room: Room | Room[]) {
return this.to(room);
Expand All @@ -55,9 +67,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
/**
* Excludes a room when emitting.
*
* @param room
* @return a new BroadcastOperator instance
* @public
* @example
* // the "foo" event will be broadcast to all connected clients, except the ones that are in the "room-101" room
* io.except("room-101").emit("foo", "bar");
*
* // with an array of rooms
* io.except(["room-101", "room-102"]).emit("foo", "bar");
*
* // with multiple chained calls
* io.except("room-101").except("room-102").emit("foo", "bar");
*
* @param room - a room, or an array of rooms
* @return a new {@link BroadcastOperator} instance for chaining
*/
public except(room: Room | Room[]) {
const exceptRooms = new Set(this.exceptRooms);
Expand All @@ -77,9 +98,11 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
/**
* Sets the compress flag.
*
* @example
* io.compress(false).emit("hello");
*
* @param compress - if `true`, compresses the sending data
* @return a new BroadcastOperator instance
* @public
*/
public compress(compress: boolean) {
const flags = Object.assign({}, this.flags, { compress });
Expand All @@ -96,8 +119,10 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
* receive messages (because of network slowness or other issues, or because they’re connected through long polling
* and is in the middle of a request-response cycle).
*
* @example
* io.volatile.emit("hello"); // the clients may or may not receive it
*
* @return a new BroadcastOperator instance
* @public
*/
public get volatile() {
const flags = Object.assign({}, this.flags, { volatile: true });
Expand All @@ -112,8 +137,11 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
/**
* Sets a modifier for a subsequent event emission that the event data will only be broadcast to the current node.
*
* @return a new BroadcastOperator instance
* @public
* @example
* // the “foo” event will be broadcast to all connected clients on this node
* io.local.emit("foo", "bar");
*
* @return a new {@link BroadcastOperator} instance for chaining
*/
public get local() {
const flags = Object.assign({}, this.flags, { local: true });
Expand All @@ -128,14 +156,15 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
/**
* Adds a timeout in milliseconds for the next operation
*
* <pre><code>
*
* @example
* io.timeout(1000).emit("some-event", (err, responses) => {
* // ...
* if (err) {
* // some clients did not acknowledge the event in the given delay
* } else {
* console.log(responses); // one response per client
* }
* });
*
* </pre></code>
*
* @param timeout
*/
public timeout(timeout: number) {
Expand All @@ -151,8 +180,23 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
/**
* Emits to all clients.
*
* @example
* // the “foo” event will be broadcast to all connected clients
* io.emit("foo", "bar");
*
* // the “foo” event will be broadcast to all connected clients in the “room-101” room
* io.to("room-101").emit("foo", "bar");
*
* // with an acknowledgement expected from all connected clients
* io.timeout(1000).emit("some-event", (err, responses) => {
* if (err) {
* // some clients did not acknowledge the event in the given delay
* } else {
* console.log(responses); // one response per client
* }
* });
*
* @return Always true
* @public
*/
public emit<Ev extends EventNames<EmitEvents>>(
ev: Ev,
Expand Down Expand Up @@ -235,7 +279,8 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
/**
* Gets a list of clients.
*
* @public
* @deprecated this method will be removed in the next major release, please use {@link Server#serverSideEmit} or
* {@link fetchSockets} instead.
*/
public allSockets(): Promise<Set<SocketId>> {
if (!this.adapter) {
Expand All @@ -247,9 +292,28 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
}

/**
* Returns the matching socket instances
* Returns the matching socket instances. This method works across a cluster of several Socket.IO servers.
*
* Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
*
* @example
* // return all Socket instances
* const sockets = await io.fetchSockets();
*
* @public
* // return all Socket instances in the "room1" room
* const sockets = await io.in("room1").fetchSockets();
*
* for (const socket of sockets) {
* console.log(socket.id);
* console.log(socket.handshake);
* console.log(socket.rooms);
* console.log(socket.data);
*
* socket.emit("hello");
* socket.join("room1");
* socket.leave("room2");
* socket.disconnect();
* }
*/
public fetchSockets(): Promise<RemoteSocket<EmitEvents, SocketData>[]> {
return this.adapter
Expand All @@ -274,10 +338,19 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
}

/**
* Makes the matching socket instances join the specified rooms
* Makes the matching socket instances join the specified rooms.
*
* Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
*
* @example
*
* @param room
* @public
* // make all socket instances join the "room1" room
* io.socketsJoin("room1");
*
* // make all socket instances in the "room1" room join the "room2" and "room3" rooms
* io.in("room1").socketsJoin(["room2", "room3"]);
*
* @param room - a room, or an array of rooms
*/
public socketsJoin(room: Room | Room[]): void {
this.adapter.addSockets(
Expand All @@ -291,10 +364,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
}

/**
* Makes the matching socket instances leave the specified rooms
* Makes the matching socket instances leave the specified rooms.
*
* Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
*
* @example
* // make all socket instances leave the "room1" room
* io.socketsLeave("room1");
*
* // make all socket instances in the "room1" room leave the "room2" and "room3" rooms
* io.in("room1").socketsLeave(["room2", "room3"]);
*
* @param room
* @public
* @param room - a room, or an array of rooms
*/
public socketsLeave(room: Room | Room[]): void {
this.adapter.delSockets(
Expand All @@ -308,10 +389,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
}

/**
* Makes the matching socket instances disconnect
* Makes the matching socket instances disconnect.
*
* Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
*
* @example
* // make all socket instances disconnect (the connections might be kept alive for other namespaces)
* io.disconnectSockets();
*
* // make all socket instances in the "room1" room disconnect and close the underlying connections
* io.in("room1").disconnectSockets(true);
*
* @param close - whether to close the underlying connection
* @public
*/
public disconnectSockets(close: boolean = false): void {
this.adapter.disconnectSockets(
Expand Down Expand Up @@ -370,7 +459,6 @@ export class RemoteSocket<EmitEvents extends EventsMap, SocketData>
* Joins a room.
*
* @param {String|Array} room - room or array of rooms
* @public
*/
public join(room: Room | Room[]): void {
return this.operator.socketsJoin(room);
Expand All @@ -380,7 +468,6 @@ export class RemoteSocket<EmitEvents extends EventsMap, SocketData>
* Leaves a room.
*
* @param {String} room
* @public
*/
public leave(room: Room): void {
return this.operator.socketsLeave(room);
Expand All @@ -391,8 +478,6 @@ export class RemoteSocket<EmitEvents extends EventsMap, SocketData>
*
* @param {Boolean} close - if `true`, closes the underlying connection
* @return {Socket} self
*
* @public
*/
public disconnect(close = false): this {
this.operator.disconnectSockets(close);
Expand Down
Loading

0 comments on commit 8fae95d

Please sign in to comment.