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

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

• TypeScript
• Emit cheatsheet
• API

• [Emitter(client[, opts])](#emitterclient-opts)

• Emitter#to(room)

• Emitter#in(room)

• Emitter#except(room)

• Emitter#of(namespace)

• Emitter#socketsJoin()

• Emitter#socketsLeave()

• Emitter#disconnectSockets()
• Migrating from socket.io-emitter
• License

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 noderedis compatible client that has been initialized with the return_buffers option set to true.

const io = require("socket.io-emitter")({ host: "127.0.0.1", port: 6379 });

const { Emitter } = require("@socket.io/redis-emitter");
const { createClient } = require("redis");

const redisClient = createClient();
const io = new Emitter(redisClient);