Class: BroadcastOperator<EmitEvents, SocketData>

Type Parameters

Type Parameter
EmitEvents extends EventsMap
SocketData

Implements

• TypedEventBroadcaster<EmitEvents>

Constructors

Constructor

new BroadcastOperator<EmitEvents, SocketData>(
   adapter: Adapter,
   rooms?: Set<string>,
   exceptRooms?: Set<string>,
   flags?: BroadcastFlags & {
  expectSingleResponse: boolean;
}): BroadcastOperator<EmitEvents, SocketData>;

Parameters

Parameter	Type
adapter	Adapter
rooms?	Set<string>
exceptRooms?	Set<string>
flags?	BroadcastFlags & { expectSingleResponse: boolean; }

Returns

BroadcastOperator<EmitEvents, SocketData>

Accessors

local

Get Signature

get local(): BroadcastOperator<EmitEvents, SocketData>;

Sets a modifier for a subsequent event emission that the event data will only be broadcast to the current node.

Example

// the “foo” event will be broadcast to all connected clients on this node
io.local.emit("foo", "bar");

Returns

BroadcastOperator<EmitEvents, SocketData>

a new BroadcastOperator instance for chaining

---

volatile

Get Signature

get volatile(): BroadcastOperator<EmitEvents, SocketData>;

Sets a modifier for a subsequent event emission that the event data may be lost if the client is not ready to 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

Returns

BroadcastOperator<EmitEvents, SocketData>

a new BroadcastOperator instance

Methods

allSockets()

allSockets(): Promise<Set<string>>;

Gets a list of clients.

Returns

Promise<Set<string>>

Deprecated

this method will be removed in the next major release, please use Server#serverSideEmit or fetchSockets instead.

---

compress()

compress(compress: boolean): BroadcastOperator<EmitEvents, SocketData>;

Sets the compress flag.

Parameters

Parameter	Type	Description
compress	boolean	if true, compresses the sending data

Returns

BroadcastOperator<EmitEvents, SocketData>

a new BroadcastOperator instance

Example

io.compress(false).emit("hello");

---

disconnectSockets()

disconnectSockets(close?: boolean): void;

Makes the matching socket instances disconnect.

Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible Adapter.

Parameters

Parameter	Type	Description
close?	boolean	whether to close the underlying connection

Returns

void

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);

---

emit()

emit<Ev>(ev: Ev, ...args: EventParams<EmitEvents, Ev>): boolean;

Emits to all clients.

Type Parameters

Type Parameter
Ev extends string | symbol

Parameters

Parameter	Type
ev	Ev
...args	EventParams<EmitEvents, Ev>

Returns

boolean

Always true

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
  }
});

Implementation of

TypedEventBroadcaster.emit;

---

emitWithAck()

emitWithAck<Ev>(ev: Ev, ...args: AllButLast<EventParams<EmitEvents, Ev>>): Promise<FirstNonErrorArg<Last<EventParams<EmitEvents, Ev>>>>;

Emits an event and waits for an acknowledgement from all clients.

Type Parameters

Type Parameter
Ev extends string | symbol

Parameters

Parameter	Type
ev	Ev
...args	AllButLast<EventParams<EmitEvents, Ev>>

Returns

Promise<FirstNonErrorArg<Last<EventParams<EmitEvents, Ev>>>>

a Promise that will be fulfilled when all clients have acknowledged the event

Example

try {
  const responses = await io.timeout(1000).emitWithAck("some-event");
  console.log(responses); // one response per client
} catch (e) {
  // some clients did not acknowledge the event in the given delay
}

---

except()

except(room: string | string[]): BroadcastOperator<EmitEvents, SocketData>;

Excludes a room when emitting.

Parameters

Parameter	Type	Description
room	string | string[]	a room, or an array of rooms

Returns

BroadcastOperator<EmitEvents, SocketData>

a new BroadcastOperator instance for chaining

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");

---

fetchSockets()

fetchSockets(): Promise<RemoteSocket<EmitEvents, SocketData>[]>;

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 Adapter.

Returns

Promise<RemoteSocket<EmitEvents, SocketData>[]>

Example

// return all Socket instances
const sockets = await io.fetchSockets();

// 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();
}

---

in()

in(room: string | string[]): BroadcastOperator<EmitEvents, SocketData>;

Targets a room when emitting. Similar to to(), but might feel clearer in some cases:

Parameters

Parameter	Type	Description
room	string | string[]	a room, or an array of rooms

Returns

BroadcastOperator<EmitEvents, SocketData>

a new BroadcastOperator instance for chaining

Example

// disconnect all clients in the "room-101" room
io.in("room-101").disconnectSockets();

---

socketsJoin()

socketsJoin(room: string | string[]): void;

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 Adapter.

Parameters

Parameter	Type	Description
room	string | string[]	a room, or an array of rooms

Returns

void

Example

// 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"]);

---

socketsLeave()

socketsLeave(room: string | string[]): void;

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 Adapter.

Parameters

Parameter	Type	Description
room	string | string[]	a room, or an array of rooms

Returns

void

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"]);

---

timeout()

timeout(timeout: number): BroadcastOperator<DecorateAcknowledgements<EmitEvents>, SocketData>;

Adds a timeout in milliseconds for the next operation

Parameters

Parameter	Type	Description
timeout	number

Returns

BroadcastOperator<DecorateAcknowledgements<EmitEvents>, SocketData>

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
  }
});

---

to()

to(room: string | string[]): BroadcastOperator<EmitEvents, SocketData>;

Targets a room when emitting.

Parameters

Parameter	Type	Description
room	string | string[]	a room, or an array of rooms

Returns

BroadcastOperator<EmitEvents, SocketData>

a new BroadcastOperator instance for chaining

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");