TinyBase logoTinyBase β

addClientIdsListener

The addClientIdsListener method registers a listener function with the WsServer that will be called whenever there is a change in the clients connected to a path that a WsServer is handling.

addClientIdsListener(
  pathId: IdOrNull,
  listener: ClientIdsListener,
): string
TypeDescription
pathIdIdOrNull

The path to listen to, or null as a wildcard.

listenerClientIdsListener

The function that will be called whenever the client Ids on a path handled by the WsServer change.

returnsstring

A unique Id for the listener that can later be used to remove it.

The provided listener is a ClientIdsListener function, and will be called with a reference to the WsServer, the Id of the path that the client joined or left, and a callback you can use to get information about the change.

You can either listen to a single path (by specifying its Id as the method's first parameter) or changes to any path (by providing a null wildcard).

Examples

This example creates a WsServer, and listens to changes to the clients connecting to and disconnecting from a specific path.

import {WebSocket, WebSocketServer} from 'ws';
import {createMergeableStore} from 'tinybase';
import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';

const server = createWsServer(new WebSocketServer({port: 8047}));
const listenerId = server.addClientIdsListener(
  'roomA',
  (server, pathId) => {
    console.log(
      `${server.getClientIds(pathId).length} client(s) in roomA`,
    );
  },
);

const synchronizer1 = await createWsSynchronizer(
  createMergeableStore(),
  new WebSocket('ws://localhost:8047/roomA'),
);
// -> '1 client(s) in roomA'

const synchronizer2 = await createWsSynchronizer(
  createMergeableStore(),
  new WebSocket('ws://localhost:8047/roomB'),
);
// The listener is not called.

synchronizer1.destroy();
// ...
// -> '0 client(s) in roomA'

synchronizer2.destroy();

server.delListener(listenerId);
server.destroy();

This example creates a WsServer, and listens to changes to the clients connecting to and disconnecting from any path.

import {WebSocket, WebSocketServer} from 'ws';
import {createMergeableStore} from 'tinybase';
import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';

const server = createWsServer(new WebSocketServer({port: 8047}));
const listenerId = server.addClientIdsListener(null, (server, pathId) => {
  console.log(
    `${server.getClientIds(pathId).length} client(s) in ${pathId}`,
  );
});

const synchronizer1 = await createWsSynchronizer(
  createMergeableStore(),
  new WebSocket('ws://localhost:8047/roomA'),
);
// -> '1 client(s) in roomA'

const synchronizer2 = await createWsSynchronizer(
  createMergeableStore(),
  new WebSocket('ws://localhost:8047/roomB'),
);
// -> '1 client(s) in roomB'

synchronizer1.destroy();
// ...
// -> '0 client(s) in roomA'

synchronizer2.destroy();
// ...
// -> '0 client(s) in roomB'

server.delListener(listenerId);
server.destroy();

Since

v5.0.0