[ws] Adjust server listener API

Author: jamesgpearce

src/@types/synchronizers/synchronizer-ws-server/docs.js

@@ -14,19 +14,19 @@
  *
  * A WsServer listens to any path, allowing an app to have the concept of
  * distinct 'rooms' that only certain clients are participating in. As soon as a
- * single client connects to a new path, this listener will be called with a
- * GetIdChanges callback that you can use to determine its Id.
+ * single client connects to a new path, this listener will be called with the
+ * Id of the new path and an `addedOrRemoved` value of `1`.
  *
- * When the final client disconnects from a path, it will be called again with a
- * GetIdChanges callback that you can again use to determine its Id.
+ * When the final client disconnects from a path, it will be called again with
+ * the Id of the deactivated path and an `addedOrRemoved` value of `-1`.
  *
  * A PathIdsListener is provided when using the addPathIdsListener method. See
  * that method for specific examples.
  * @param wsServer A reference to the WsServer.
- * @param getIdChanges A function that returns information about the path Id
- * change.
+ * @param pathId The Id of the path being added or removed.
+ * @param addedOrRemoved Whether the path was added (`1`) or removed (`-1`).
  * @category Listener
- * @since v5.0.0
+ * @since v5.0.3
  */
 /// PathIdsListener
 /**
@@ -35,20 +35,21 @@
  *
  * A WsServer listens to any path, allowing an app to have the concept of
  * distinct 'rooms' that only certain clients are participating in. As soon as a
- * new client connects to a path, this listener will be called with a
- * GetIdChanges callback that you can use to determine its Id.
+ * new client connects to a path, this listener will be called with the Id of
+ * the path, the Id of the new client, and an `addedOrRemoved` value of `1`.
  *
- * When the client disconnects from a path, it will be called again with a
- * GetIdChanges callback that you can again use to determine its Id.
+ * When the client disconnects from a path, it will be called again with the Id
+ * of the path, the Id of the leaving client, and an `addedOrRemoved` value of
+ * `-1`.
  *
  * A ClientIdsListener is provided when using the addClientIdsListener method.
  * See that method for specific examples.
  * @param wsServer A reference to the WsServer.
  * @param pathId The path that the client joined or left.
- * @param getIdChanges A function that returns information about the client Id
- * change.
+ * @param clientId The Id of the client being added or removed.
+ * @param addedOrRemoved Whether the client was added (`1`) or removed (`-1`).
  * @category Listener
- * @since v5.0.0
+ * @since v5.0.3
  */
 /// ClientIdsListener
 /**
@@ -228,33 +229,35 @@
    * import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
    *
    * const server = createWsServer(new WebSocketServer({port: 8047}));
-   * const listenerId = server.addPathIdsListener((server, getIdChanges) => {
-   *   console.log(getIdChanges());
-   *   console.log(server.getPathIds());
-   * });
+   * const listenerId = server.addPathIdsListener(
+   *   (server, pathId, addedOrRemoved) => {
+   *     console.log(pathId + (addedOrRemoved == 1 ? ' added' : ' removed'));
+   *     console.log(server.getPathIds());
+   *   },
+   * );
    *
    * const synchronizer1 = await createWsSynchronizer(
    *   createMergeableStore(),
    *   new WebSocket('ws://localhost:8047/roomA'),
    * );
-   * // -> {'roomA': 1}
+   * // -> 'roomA added'
    * // -> ['roomA']
    *
    * const synchronizer2 = await createWsSynchronizer(
    *   createMergeableStore(),
    *   new WebSocket('ws://localhost:8047/roomB'),
    * );
-   * // -> {'roomB': 1}
+   * // -> 'roomB added'
    * // -> ['roomA', 'roomB']
    *
    * synchronizer1.destroy();
    * // ...
-   * // -> {'roomA': -1}
+   * // -> 'roomA removed'
    * // -> ['roomB']
    *
    * synchronizer2.destroy();
    * // ...
-   * // -> {'roomB': -1}
+   * // -> 'roomB removed'
    * // -> []
    *
    * server.delListener(listenerId);

src/@types/synchronizers/synchronizer-ws-server/index.d.ts

@@ -1,20 +1,22 @@
 /// synchronizer-ws-server
 
 import type {Id, IdOrNull, Ids} from '../../common/index.d.ts';
-import type {GetIdChanges} from '../../store/index.d.ts';
+import type {IdAddedOrRemoved} from '../../store/index.d.ts';
 import type {WebSocketServer} from 'ws';
 
 /// PathIdsListener
-export type PathIdsListener<> = (
+export type PathIdsListener = (
   wsServer: WsServer,
-  getIdChanges: GetIdChanges,
+  pathId: Id,
+  addedOrRemoved: IdAddedOrRemoved,
 ) => void;
 
 /// ClientIdsListener
-export type ClientIdsListener<> = (
+export type ClientIdsListener = (
   wsServer: WsServer,
   pathId: Id,
-  getIdChanges: GetIdChanges,
+  clientId: Id,
+  addedOrRemoved: IdAddedOrRemoved,
 ) => void;
 
 /// WsServerStats

src/@types/synchronizers/synchronizer-ws-server/with-schemas/index.d.ts

@@ -1,20 +1,22 @@
 /// synchronizer-ws-server
 
 import type {Id, IdOrNull, Ids} from '../../../common/with-schemas/index.d.ts';
-import type {GetIdChanges} from '../../../store/with-schemas/index.d.ts';
+import type {IdAddedOrRemoved} from '../../../store/with-schemas/index.d.ts';
 import type {WebSocketServer} from 'ws';
 
 /// PathIdsListener
-export type PathIdsListener<> = (
+export type PathIdsListener = (
   wsServer: WsServer,
-  getIdChanges: GetIdChanges<Id>,
+  pathId: Id,
+  addedOrRemoved: IdAddedOrRemoved,
 ) => void;
 
 /// ClientIdsListener
-export type ClientIdsListener<> = (
+export type ClientIdsListener = (
   wsServer: WsServer,
   pathId: Id,
-  getIdChanges: GetIdChanges<Id>,
+  clientId: Id,
+  addedOrRemoved: IdAddedOrRemoved,
 ) => void;
 
 /// WsServerStats

src/synchronizers/synchronizer-ws-server/index.ts

@@ -48,9 +48,9 @@ export const createWsServer = ((webSocketServer: WebSocketServer) => {
         mapSet(clients, clientId, webSocket);
 
         if (clients.size == 1) {
-          callListeners(pathIdListeners, undefined, () => ({[pathId]: 1}));
+          callListeners(pathIdListeners, undefined, pathId, 1);
         }
-        callListeners(clientIdListeners, [pathId], () => ({[clientId]: 1}));
+        callListeners(clientIdListeners, [pathId], clientId, 1);
 
         webSocket.on('message', (data) => {
           const payload = data.toString(UTF8);
@@ -74,10 +74,10 @@ export const createWsServer = ((webSocketServer: WebSocketServer) => {
 
         webSocket.on('close', () => {
           collDel(clients, clientId);
-          callListeners(clientIdListeners, [pathId], () => ({[clientId]: -1}));
+          callListeners(clientIdListeners, [pathId], clientId, -1);
           if (collIsEmpty(clients)) {
             collDel(clientsByPath, pathId);
-            callListeners(pathIdListeners, undefined, () => ({[pathId]: -1}));
+            callListeners(pathIdListeners, undefined, pathId, -1);
           }
         });
       }),

test/unit/other/synchronizer-ws-server.test.ts

@@ -89,32 +89,38 @@ describe('Multiple connections', () => {
 
   test('Listeners', async () => {
     const pathIdsLog: {[pathId: string]: -1 | 1}[] = [];
-    wsServer.addPathIdsListener((server, getIdChanges) => {
+    wsServer.addPathIdsListener((server, pathId, addedOrRemoved) => {
       expect(server).toEqual(wsServer);
-      pathIdsLog.push(getIdChanges());
+      pathIdsLog.push({[pathId]: addedOrRemoved});
     });
 
     const allClientIdsLog: {[pathId: string]: {[clientId: string]: -1 | 1}}[] =
       [];
-    wsServer.addClientIdsListener(null, (server, pathId, getIdChanges) => {
-      expect(server).toEqual(wsServer);
-      allClientIdsLog.push({[pathId]: getIdChanges()});
-    });
+    wsServer.addClientIdsListener(
+      null,
+      (server, pathId, clientId, addedOrRemoved) => {
+        expect(server).toEqual(wsServer);
+        allClientIdsLog.push({[pathId]: {[clientId]: addedOrRemoved}});
+      },
+    );
 
     const clientIdsLog1: {[pathId: string]: {[clientId: string]: -1 | 1}}[] =
       [];
-    wsServer.addClientIdsListener('p1', (server, pathId, getIdChanges) => {
-      expect(server).toEqual(wsServer);
-      clientIdsLog1.push({[pathId]: getIdChanges()});
-    });
+    wsServer.addClientIdsListener(
+      'p1',
+      (server, pathId, clientId, addedOrRemoved) => {
+        expect(server).toEqual(wsServer);
+        clientIdsLog1.push({[pathId]: {[clientId]: addedOrRemoved}});
+      },
+    );
 
     const clientIdsLog2: {[pathId: string]: {[clientId: string]: -1 | 1}}[] =
       [];
     const listenerId = wsServer.addClientIdsListener(
       'p2',
-      (server, pathId, getIdChanges) => {
+      (server, pathId, clientId, addedOrRemoved) => {
         expect(server).toEqual(wsServer);
-        clientIdsLog2.push({[pathId]: getIdChanges()});
+        clientIdsLog2.push({[pathId]: {[clientId]: addedOrRemoved}});
       },
     );