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
Installation:
npm i @socket.io/redis-emitter redis
CommonJS
const { Emitter } = require("@socket.io/redis-emitter");
const { createClient } = require("redis"); // not included, needs to be explicitly installed
const redisClient = createClient();
redisClient.connect().then(() => {
const io = new Emitter(redisClient);
setInterval(() => {
io.emit("time", new Date);
}, 5000);
})With redis@3, calling connect() is not needed:
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
import { Emitter } from "@socket.io/redis-emitter";
import { createClient } from "redis";
const redisClient = createClient();
redisClient.connect().then(() => {
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();
redisClient.connect().then(() => {
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)parser: parser to use for encoding messages to Redis (`notepack.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();Migrating from socket.io-emitter
The package was renamed from socket.io-emitter to @socket.io/redis-emitter in v4, in order to better reflect the relationship with Redis.
To migrate to the new package, you'll need to make sure to provide your own Redis clients, as the package will no longer create Redis clients on behalf of the user.
Before:
const io = require("socket.io-emitter")({ host: "127.0.0.1", port: 6379 });After:
const { Emitter } = require("@socket.io/redis-emitter");
const { createClient } = require("redis");
const redisClient = createClient();
const io = new Emitter(redisClient);License
MIT