@socket.io/mongo-emitter

Socket.IO MongoDB emitter

The @socket.io/mongo-emitter package allows you to easily communicate with a group of Socket.IO servers from another Node.js process (server-side).

It must be used in conjunction with @socket.io/mongo-adapter.

Supported features:

• broadcasting
• utility methods
  • socketsJoin
  • socketsLeave
  • disconnectSockets
  • serverSideEmit

Related packages:

• MongoDB adapter: https://github.com/socketio/socket.io-mongo-adapter/
• Redis adapter: https://github.com/socketio/socket.io-redis-adapter/
• Redis emitter: https://github.com/socketio/socket.io-redis-emitter/
• Postgres adapter: https://github.com/socketio/socket.io-postgres-adapter/
• Postgres emitter: https://github.com/socketio/socket.io-postgres-emitter/

Table of contents

• Installation
• Usage
• API
• Known errors
• License

Installation

npm install @socket.io/mongo-emitter mongodb

For TypeScript users, you might also need @types/mongodb.

Usage

const { Emitter } = require("@socket.io/mongo-emitter");
const { MongoClient } = require("mongodb");

const DB = "mydb";
const COLLECTION = "socket.io-adapter-events";

const mongoClient = new MongoClient("mongodb://localhost:27017/?replicaSet=rs0", {
  useUnifiedTopology: true,
});

const main = async () => {
  await mongoClient.connect();

  const mongoCollection = mongoClient.db(DB).collection(COLLECTION);
  const io = new Emitter(mongoCollection);

  setInterval(() => {
    io.emit("ping", new Date());
  }, 1000);
}

main();

API

Emitter(mongoCollection[, nsp])

const io = new Emitter(mongoCollection);

The mongoCollection argument is a MongoDB collection object from the mongodb package.

Emitter#to(room:string):BroadcastOperator

Emitter#in(room:string):BroadcastOperator

Specifies a specific room that you want to emit to.

io.to("room1").emit("hello");

Emitter#except(room:string):BroadcastOperator

Specifies a specific room that you want to exclude from broadcasting.

io.except("room2").emit("hello");

Emitter#of(namespace:string):Emitter

Specifies a specific namespace that you want to emit to.

const customNamespace = io.of("/custom");

customNamespace.emit("hello");

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

Emitter#serverSideEmit(ev:string[,...args:any[]])

Emits an event that will be received by each Socket.IO server of the cluster.

io.serverSideEmit("ping");

Known errors

• TypeError: this.mongoCollection.insertOne is not a function

You probably passed a MongoDB client instead of a MongoDB collection to the Emitter constructor.

License

MIT

Changelog

0.2.0 (2023-06-27)

Features

• add an option to use a TTL index (3b6d5a9)