Emit cheatsheet
caution
The following event names are reserved and must not be used in your application:
connectconnect_errordisconnectdisconnectingnewListenerremoveListener
// BAD, will throw an error
socket.emit("disconnecting");
Server
Single client
Basic emit
io.on("connection",(socket)=>{
socket.emit("hello",1,"2",{3:"4",5:Buffer.from([6])});
});
Acknowledgement
- Callback
- Promise
io.on("connection",(socket)=>{
socket.emit("hello","world",(arg1, arg2, arg3)=>{
// ...
});
});
io.on("connection",async(socket)=>{
const response =await socket.emitWithAck("hello","world");
});
Acknowledgement and timeout
- Callback
- Promise
io.on("connection",(socket)=>{
socket.timeout(5000).emit("hello","world",(err, arg1, arg2, arg3)=>{
if(err){
// the client did not acknowledge the event in the given delay
}else{
// ...
}
});
});
io.on("connection",async(socket)=>{
try{
const response =await socket.timeout(5000).emitWithAck("hello","world");
}catch(e){
// the client did not acknowledge the event in the given delay
}
});
Broadcasting
To all connected clients
io.emit("hello");
Except the sender
io.on("connection",(socket)=>{
socket.broadcast.emit("hello");
});
Acknowledgements
- Callback
- Promise
io.timeout(5000).emit("hello","world",(err, responses)=>{
if(err){
// some clients did not acknowledge the event in the given delay
}else{
console.log(responses);// one response per client
}
});
try{
const responses =await io.timeout(5000).emitWithAck("hello","world");
console.log(responses);// one response per client
}catch(e){
// some clients did not acknowledge the event in the given delay
}
In a room
- to all connected clients in the room named "my room"
io.to("my room").emit("hello");
- to all connected clients except the ones in the room named "my room"
io.except("my room").emit("hello");
- with multiple clauses
io.to("room1").to(["room2","room3"]).except("room4").emit("hello");
In a namespace
io.of("/my-namespace").emit("hello");
tip
The modifiers can absolutely be chained:
io.of("/my-namespace").on("connection",(socket)=>{
socket
.timeout(5000)
.to("room1")
.to(["room2","room3"])
.except("room4")
.emit("hello",(err, responses)=>{
// ...
});
});
This will emit a "hello" event to all connected clients:
- in the namespace named
my-namespace - in at least one of the rooms named
room1,room2androom3, but not inroom4 - except the sender
And expect an acknowledgement in the next 5 seconds.
Between servers
Basic emit
io.serverSideEmit("hello","world");
Receiving side:
io.on("hello",(value)=>{
console.log(value);// "world"
});
Acknowledgements
- Callback
- Promise
io.serverSideEmit("hello","world",(err, responses)=>{
if(err){
// some servers did not acknowledge the event in the given delay
}else{
console.log(responses);// one response per server (except the current one)
}
});
try{
const responses =await io.serverSideEmitWithAck("hello","world");
console.log(responses);// one response per server (except the current one)
}catch(e){
// some servers did not acknowledge the event in the given delay
}
Receiving side:
io.on("hello",(value, callback)=>{
console.log(value);// "world"
callback("hi");
});
Client
Basic emit
socket.emit("hello",1,"2",{3:"4",5:Uint8Array.from([6])});
Acknowledgement
- Callback
- Promise
socket.emit("hello","world",(arg1, arg2, arg3)=>{
// ...
});
const response =await socket.emitWithAck("hello","world");
Acknowledgement and timeout
- Callback
- Promise
socket.timeout(5000).emit("hello","world",(err, arg1, arg2, arg3)=>{
if(err){
// the server did not acknowledge the event in the given delay
}else{
// ...
}
});
try{
const response =await socket.timeout(5000).emitWithAck("hello","world");
}catch(e){
// the server did not acknowledge the event in the given delay
}