@soundworks/core 4.0.0-alpha.21 → 4.0.0-alpha.23

package/types/server/Socket.d.ts

@@ -1,128 +1,164 @@
 export default Socket;
 /**
- * Simple wrapper with simple pubsub system built on top of `ws` sockets.
- * The abstraction contains two different socket:
- * - one configured for string (JSON compatible) messages
- * - one configured with `binaryType=arraybuffer` for streaming data more
- *   efficiently.
+ * The Socket class is a simple publish / subscribe wrapper built on top of the
+ * [ws](https://github.com/websockets/ws) library. An instance of {@link server.Socket}
+ * is automatically created per client when it connects (see {@link server.Client#socket}).
  *
- * @see https://github.com/websockets/ws
+ * _Important: In most cases, you should consider using a {@link client.SharedState}
+ * rather than directly using the sockets._
+ *
+ * The Socket class contains two different WebSockets:
+ * - a socket configured with `binaryType = 'blob'` for JSON compatible data
+ *  types (i.e. string, number, boolean, object, array and null).
+ * - a socket configured with `binaryType= 'arraybuffer'` for efficient streaming
+ *  of binary data.
  *
  * @memberof server
+ * @hideconstructor
  */
 declare class Socket {
-    constructor(ws: any, binaryWs: any, rooms: any, sockets: any, options?: {});
+    constructor(ws: any, binaryWs: any, rooms: any, sockets: any);
+    /**
+     * `ws` socket instance configured with `binaryType=blob` (string)
+     *
+     * @type {object}
+     * @private
+     */
+    private ws;
+    /**
+     * `ws` socket instance configured with `binaryType=arraybuffer` (TypedArray)
+     *
+     * @type {object}
+     * @private
+     */
+    private binaryWs;
     /**
      * Reference to the sockets object, is mainly dedicated to allow
      * broadcasting from a given socket instance.
+     *
      * @type {server.Sockets}
      * @example
      * socket.sockets.broadcast('my-room', this, 'update-value', 1);
      */
     sockets: server.Sockets;
     /**
-     * `ws` socket instance configured with `binaryType=blob` (string)
+     * Reference to the rooms object
+     *
+     * @type {Map}
      * @private
-     * @type {Object}
      */
-    private ws;
+    private rooms;
+    /** @private */
+    private _stringListeners;
+    /** @private */
+    private _binaryListeners;
+    /** @private */
+    private _heartbeatId;
+    /** @private */
+    private _isAlive;
     /**
-     * `ws` socket instance configured with `binaryType=arraybuffer` (TypedArray)
+     * Removes all listeners and immediately close the two sockets. Is automatically
+     * called on `server.stop()`
+     *
      * @private
-     * @type {Object}
      */
-    private binaryWs;
+    private terminate;
     /**
-     * `ws` socket instance configured with `binaryType=arraybuffer` (TypedArray)
+     * @param {boolean} binary - Emit to either the string or binary socket.
+     * @param {string} channel - Channel name.
+     * @param {...*} args - Content of the message.
      * @private
-     * @type {Map}
      */
-    private rooms;
+    private _emit;
     /**
-     * Configuration object
-     * @type {Object}
+     * @param {Function[]} listeners - List of listeners, either for the string or binary socket.
+     * @param {string} channel - Channel name.
+     * @param {Function} callback - The function to be added to the listeners.
+     * @private
      */
-    config: any;
-    _stringListeners: Map<any, any>;
-    _binaryListeners: Map<any, any>;
-    _isAlive: boolean;
-    _intervalId: NodeJS.Timeout;
+    private _addListener;
     /**
-     * Called when the string socket closes (aka client reload).
+     * @param {Function[]} listeners - List of listeners, either for the string or binary socket.
+     * @param {string} channel - Channel name.
+     * @param {Function} callback - The function to be removed from the listeners.
+     * @private
      */
-    /** @private */
-    private terminate;
-    /** @private */
-    private _emit;
-    /** @private */
-    private _addListener;
-    /** @private */
     private _removeListener;
-    /** @private */
+    /**
+     * @param {Function[]} listeners - List of listeners, either for the string or binary socket.
+     * @param {string} [channel=null] - Channel name of the listeners to remove. If null
+     *  all the listeners are cleared.
+     * @private
+     */
     private _removeAllListeners;
     /**
      * Add the socket to a room
-     * @param {String} roomId - Id of the room
+     *
+     * @param {string} roomId - Id of the room.
      */
     addToRoom(roomId: string): void;
     /**
      * Remove the socket from a room
-     * @param {String} roomId - Id of the room
+     *
+     * @param {string} roomId - Id of the room.
      */
     removeFromRoom(roomId: string): void;
     /**
-     * Sends JSON compatible messages on a given channel
+     * Send messages with JSON compatible data types on a given channel.
      *
-     * @param {String} channel - Channel of the message
-     * @param {...*} args - Arguments of the message (as many as needed, of any type)
+     * @param {string} channel - Channel name.
+     * @param {...*} args - Payload of the message. As many arguments as needed, of
+     *  JSON compatible data types (i.e. string, number, boolean, object, array and null).
      */
     send(channel: string, ...args: any[]): void;
     /**
-     * Listen JSON compatible messages on a given channel
+     * Listen messages with JSON compatible data types on a given channel.
      *
-     * @param {String} channel - Channel of the message
-     * @param {Function} callback - Callback to execute when a message is received
+     * @param {string} channel - Channel name.
+     * @param {Function} callback - Callback to execute when a message is received,
+     *  arguments of the callback function will match the arguments sent using the
+     *  {@link server.Socket#send} method.
      */
     addListener(channel: string, callback: Function): void;
     /**
-     * Remove a listener from JSON compatible messages on a given channel
+     * Remove a listener of messages with JSON compatible data types from a given channel.
      *
-     * @param {String} channel - Channel of the message
-     * @param {Function} callback - Callback to cancel
+     * @param {string} channel - Channel name.
+     * @param {Function} callback - Callback to remove.
      */
     removeListener(channel: string, callback: Function): void;
     /**
-     * Remove all listeners from JSON compatible messages on a given channel
+     * Remove all listeners of messages with JSON compatible data types.
      *
-     * @param {String} channel - Channel of the message
+     * @param {string} channel - Channel name.
      */
-    removeAllListeners(channel: string): void;
+    removeAllListeners(channel?: string): void;
     /**
-     * Sends binary messages on a given channel
+     * Send binary messages on a given channel.
      *
-     * @param {String} channel - Channel of the message
-     * @param {TypedArray} typedArray - Data to send
+     * @param {string} channel - Channel name.
+     * @param {TypedArray} typedArray - Binary data to be sent.
      */
     sendBinary(channel: string, typedArray: TypedArray): void;
     /**
      * Listen binary messages on a given channel
      *
-     * @param {String} channel - Channel of the message
-     * @param {Function} callback - Callback to execute when a message is received
+     * @param {string} channel - Channel name.
+     * @param {Function} callback - Callback to execute when a message is received.
      */
     addBinaryListener(channel: string, callback: Function): void;
     /**
-     * Remove a listener from binary compatible messages on a given channel
+     * Remove a listener of binary compatible messages from a given channel
      *
-     * @param {String} channel - Channel of the message
-     * @param {Function} callback - Callback to cancel
+     * @param {string} channel - Channel name.
+     * @param {Function} callback - Callback to remove.
      */
     removeBinaryListener(channel: string, callback: Function): void;
     /**
-     * Remove all listeners from binary compatible messages on a given channel
+     * Remove all listeners of binary compatible messages on a given channel
      *
-     * @param {String} channel - Channel of the message
+     * @param {string} channel - Channel of the message.
      */
-    removeAllBinaryListeners(channel: string): void;
+    removeAllBinaryListeners(channel?: string): void;
 }
 //# sourceMappingURL=Socket.d.ts.map

package/types/server/Socket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Socket.d.ts","sourceRoot":"","sources":["../../src/server/Socket.js"],"names":[],"mappings":";AAcA;;;;;;;;;;GAUG;AACH;IACE,4EA2HC;IAzHC;;;;;;OAMG;IACH,wBAAsB;IAEtB;;;;OAIG;IACH,WAAY;IAEZ;;;;OAIG;IACH,iBAAwB;IAExB;;;;OAIG;IACH,cAAkB;IAElB;;;OAGG;IACH,YAGC;IAED,gCAAiC;IACjC,gCAAiC;IAoDjC,kBAAoB;IAiBpB,4BAW4B;IAG9B;;OAEG;IACH,eAAe;IACf,kBAmCC;IAED,eAAe;IACf,cAOC;IAED,eAAe;IACf,qBAOC;IAED,eAAe;IACf,wBASC;IAED,eAAe;IACf,4BAIC;IAED;;;OAGG;IACH,gCAOC;IAED;;;OAGG;IACH,qCAKC;IAED;;;;;OAKG;IACH,4CAcC;IAED;;;;;OAKG;IACH,uDAEC;IAED;;;;;OAKG;IACH,0DAEC;IAED;;;;OAIG;IACH,0CAEC;IAED;;;;;OAKG;IACH,0DAQC;IAED;;;;;OAKG;IACH,6DAEC;IAED;;;;;OAKG;IACH,gEAEC;IAED;;;;OAIG;IACH,gDAEC;CACF"}
+{"version":3,"file":"Socket.d.ts","sourceRoot":"","sources":["../../src/server/Socket.js"],"names":[],"mappings":";AAqBA;;;;;;;;;;;;;;;;GAgBG;AACH;IACE,8DAiIC;IAhIC;;;;;OAKG;IACH,WAAY;IAEZ;;;;;OAKG;IACH,iBAAwB;IAExB;;;;;;;OAOG;IACH,wBAAsB;IAEtB;;;;;OAKG;IACH,cAAkB;IAElB,eAAe;IACf,yBAAiC;IACjC,eAAe;IACf,yBAAiC;IACjC,eAAe;IACf,qBAAwB;IAIxB,eAAe;IACf,iBAAoB;IAsFtB;;;;;OAKG;IACH,kBAoCC;IAED;;;;;OAKG;IACH,cAOC;IAED;;;;;OAKG;IACH,qBAOC;IAED;;;;;OAKG;IACH,wBASC;IAED;;;;;OAKG;IACH,4BAMC;IAED;;;;OAIG;IACH,kBAFW,MAAM,QAShB;IAED;;;;OAIG;IACH,uBAFW,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,cAJW,MAAM,wBAkBhB;IAED;;;;;;;OAOG;IACH,qBALW,MAAM,4BAOhB;IAED;;;;;OAKG;IACH,wBAHW,MAAM,4BAKhB;IAED;;;;OAIG;IACH,6BAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,oBAHW,MAAM,gCAWhB;IAED;;;;;OAKG;IACH,2BAHW,MAAM,4BAKhB;IAED;;;;;OAKG;IACH,8BAHW,MAAM,4BAKhB;IAED;;;;OAIG;IACH,mCAFW,MAAM,QAIhB;CACF"}

package/types/server/Sockets.d.ts

@@ -1,6 +1,7 @@
 export default Sockets;
 /**
- * Websocket server that creates and host all {@link server.Socket} instance.
+ * Manager all {@link server.Socket} instances.
+ *
  * Most of the time, you shouldn't have to use this class instance directely, but
  * it could be usefull in some situations, for broadcasting messages, creating rooms, etc.
  *
@@ -17,57 +18,63 @@ declare class Sockets {
     private _latencyStatsWorker;
     /** @private */
     private _auditState;
+    /** @private */
+    private _DEBUG_PREVENT_HEARTBEAT;
     /**
-     * Initialize sockets, all sockets are added by default added to two rooms:
+     * Initialize sockets, all sockets are added to two rooms by default:
      * - to the room corresponding to the client `role`
-     * - to the '*' that holds all connected sockets
+     * - to the '*' room that holds all connected sockets
      *
      * @private
      */
     private start;
-    /** @protected */
-    protected terminate(): void;
+    /**
+     * Terminate all existing sockets
+     *
+     * @private
+     */
+    private terminate;
     /** @private */
     private _broadcast;
     /**
      * Add a socket to a room
      *
      * @param {server.Socket} socket - Socket to add to the room.
-     * @param {String} roomId - Id of the room
+     * @param {String} roomId - Id of the room.
      */
     addToRoom(socket: server.Socket, roomId: string): void;
     /**
      * Remove a socket from a room
      *
      * @param {server.Socket} socket - Socket to remove from the room.
-     * @param {String} [roomId=null] - Id of the room
+     * @param {String} roomId - Id of the room.
      */
-    removeFromRoom(socket: server.Socket, roomId?: string): void;
+    removeFromRoom(socket: server.Socket, roomId: string): void;
     /**
-     * Send a string message to all client of given room(s). If no room
-     * not specified, the message is sent to all clients
+     * Send a message of JSON compatible data types to all client of given room(s).
+     * If no room is specified, the message is sent to all clients.
+     *
      *
      * @param {String|Array} roomsIds - Ids of the rooms that must receive
-     *  the message. If null the message is sent to all clients
-     * @param {server.Socket} excludeSocket - Optionnal
-     *  socket to ignore when broadcasting the message, typically the client
-     *  at the origin of the message
-     * @param {String} channel - Channel of the message
-     * @param {...*} args - Arguments of the message (as many as needed, of any type)
+     *  the message. If `null` the message is sent to all clients.
+     * @param {server.Socket} excludeSocket - Optionnal socket to ignore when
+     *  broadcasting the message, typically the client at the origin of the message.
+     * @param {String} channel - Channel name.
+     * @param {...*} args - Payload of the message. As many arguments as needed, of
+     *  JSON compatible data types (i.e. string, number, boolean, object, array and null).
      */
     broadcast(roomIds: any, excludeSocket: server.Socket, channel: string, ...args: any[]): void;
     /**
-     * Send a binary message (TypedArray) to all client of given room(s). If no room
-     * not specified, the message is sent to all clients
+     * Send a binary message to all client of given room(s). If no room is specified
+     * specified, the message is sent to all clients.
      *
      * @param {String|Array} roomsIds - Ids of the rooms that must receive
-     *  the message. If null the message is sent to all clients
-     * @param {server.Socket} excludeSocket - Optionnal
-     *  socket to ignore when broadcasting the message, typically the client
-     *  at the origin of the message
-     * @param {String} channel - Channel of the message
-     * @param {...*} args - Arguments of the message (as many as needed, of any type)
+     *  the message. If `null` the message is sent to all clients.
+     * @param {server.Socket} excludeSocket - Optionnal socket to ignore when
+     *  broadcasting the message, typically the client at the origin of the message.
+     * @param {string} channel - Channel name.
+     * @param {TypedArray} typedArray - Binary data to be sent.
      */
-    broadcastBinary(roomIds: any, excludeSocket: server.Socket, channel: string, typedArray: any): void;
+    broadcastBinary(roomIds: any, excludeSocket: server.Socket, channel: string, typedArray: TypedArray): void;
 }
 //# sourceMappingURL=Sockets.d.ts.map

package/types/server/Sockets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sockets.d.ts","sourceRoot":"","sources":["../../src/server/Sockets.js"],"names":[],"mappings":";AAYA;;;;;;GAMG;AACH;IAEI,eAAe;IACf,aAAgB;IAChB,eAAe;IACf,eAAuB;IAGvB,eAAe;IACf,6BAAqC;IAErC,eAAe;IACf,4BAA+B;IAC/B,eAAe;IACf,oBAAuB;IAIzB;;;;;;OAMG;IACH,cAwDC;IAED,iBAAiB;IACjB,4BAMC;IAED,eAAe;IACf,mBA8BC;IAED;;;;;OAKG;IACH,uDAEC;IAED;;;;;OAKG;IACH,6DAEC;IAED;;;;;;;;;;;OAWG;IACH,6FAEC;IAED;;;;;;;;;;;OAWG;IACH,oGAEC;CACF"}
+{"version":3,"file":"Sockets.d.ts","sourceRoot":"","sources":["../../src/server/Sockets.js"],"names":[],"mappings":";AAUA;;;;;;;GAOG;AACH;IAEI,eAAe;IACf,aAAgB;IAChB,eAAe;IACf,eAAuB;IAGvB,eAAe;IACf,6BAAqC;IAErC,eAAe;IACf,4BAA+B;IAC/B,eAAe;IACf,oBAAuB;IAEvB,eAAe;IACf,iCAAqC;IAGvC;;;;;;OAMG;IACH,cA8EC;IAED;;;;OAIG;IACH,kBAMC;IAED,eAAe;IACf,mBA8BC;IAED;;;;;OAKG;IACH,uDAEC;IAED;;;;;OAKG;IACH,4DAEC;IAED;;;;;;;;;;;;OAYG;IACH,6FAEC;IAED;;;;;;;;;;OAUG;IACH,qEAHW,MAAM,gCAKhB;CACF"}