The Socket.IO Redis emitter
The @socket.io/redis-emitter package allows you to easily communicate with a group of Socket.IO servers from another Node.js process (server-side).
The emitter is also available in other programming languages:
- Java: https://github.com/sunsus/socket.io-java-emitter
- Python: https://pypi.org/project/socket.io-emitter/
- PHP: https://github.com/rase-/socket.io-php-emitter
- Golang: https://github.com/yosuke-furukawa/socket.io-go-emitter
- Perl: https://metacpan.org/pod/SocketIO::Emitter
- Rust: https://github.com/epli2/socketio-rust-emitter
It must be used in conjunction with @socket.io/redis-adapter.
The current version is compatible with both:
socket.io-redis@5(socket.io@2)socket.io-redis@6(socket.io@3&socket.io@4)
Table of content
How to use
CommonJS
Installation: npm i @socket.io/redis-emitter redis
const { Emitter } = require("@socket.io/redis-emitter");
const { createClient } = require("redis"); // not included, needs to be explicitly installed
const redisClient = createClient();
const io = new Emitter(redisClient);
setInterval(() => {
io.emit("time", new Date);
}, 5000);TypeScript
Installation: npm i @socket.io/redis-emitter redis @types/redis
import { Emitter } from "@socket.io/redis-emitter";
import { createClient } from "redis";
const redisClient = createClient();
const io = new Emitter(redisClient);
setInterval(() => {
io.emit("time", new Date);
}, 5000);With typed events:
import { Emitter } from ".";
import { createClient } from "redis";
interface Events {
basicEmit: (a: number, b: string, c: number[]) => void;
}
const redisClient = createClient();
const io = new Emitter<Events>(redisClient);
io.emit("basicEmit", 1, "2", [3]);Emit cheatsheet
const { Emitter } = require("@socket.io/redis-emitter");
const { createClient } = require("redis"); // not included, needs to be explicitly installed
const redisClient = createClient();
const io = new Emitter(redisClient);
// sending to all clients
io.emit(/* ... */);
// sending to all clients in 'room1' room
io.to("room1").emit(/* ... */);
// sending to all clients in 'room1' except those in 'room2'
io.to("room1").except("room2").emit(/* ... */);
// sending to individual socketid (private message)
io.to(socketId).emit(/* ... */);
const nsp = io.of("/admin");
// sending to all clients in 'admin' namespace
nsp.emit(/* ... */);
// sending to all clients in 'admin' namespace and in 'notifications' room
nsp.to("notifications").emit(/* ... */);Note: acknowledgements are not supported
API
Emitter(client[, opts])
client is a node_redis
compatible client that has been initialized with the return_buffers
option set to true.
The following options are allowed:
key: the name of the key to pub/sub events on as prefix (socket.io)
Emitter#to(room:String):BroadcastOperator
Emitter#in(room:String):BroadcastOperator
Specifies a specific room that you want to emit to.
Emitter#except(room:String):BroadcastOperator
Specifies a specific room that you want to exclude from broadcasting.
Emitter#of(namespace:String):Emitter
Specifies a specific namespace that you want to emit to.
Emitter#socketsJoin(rooms:String|String[])
Makes the matching socket instances join the specified rooms:
// make all Socket instances join the "room1" room
io.socketsJoin("room1");
// make all Socket instances of the "admin" namespace in the "room1" room join the "room2" room
io.of("/admin").in("room1").socketsJoin("room2");Emitter#socketsLeave(rooms:String|String[])
Makes the matching socket instances leave the specified rooms:
// make all Socket instances leave the "room1" room
io.socketsLeave("room1");
// make all Socket instances of the "admin" namespace in the "room1" room leave the "room2" room
io.of("/admin").in("room1").socketsLeave("room2");Emitter#disconnectSockets(close:boolean)
Makes the matching socket instances disconnect:
// make all Socket instances disconnect
io.disconnectSockets();
// make all Socket instances of the "admin" namespace in the "room1" room disconnect
io.of("/admin").in("room1").disconnectSockets();
// this also works with a single socket ID
io.of("/admin").in(theSocketId).disconnectSockets();License
MIT
