`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

Type Description

	Type	Description
`pathId`	`IdOrNull`	The path to listen to, or `null` as a wildcard.
`listener`	`ClientIdsListener`	The function that will be called whenever the client `Ids` on a path handled by the `WsServer` change.
returns	`string`	A unique `Id` for the listener that can later be used to remove it.

pathId

IdOrNull

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

listener

ClientIdsListener

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

returns

string

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