[major] Rename the allowMultipleEventsPerMicrotask option

lpinca · lpinca · commit 4ed7fe58b42a · 2023-12-12T19:00:08.000+01:00
Rename the `allowMultipleEventsPerMicrotask` option to
`allowSynchronousEvents`.
diff --git a/doc/ws.md b/doc/ws.md
@@ -72,10 +72,10 @@ This class represents a WebSocket server. It extends the `EventEmitter`.
 ### new WebSocketServer(options[, callback])
 
 - `options` {Object}
-  - `allowMultipleEventsPerMicrotask` {Boolean} Specifies whether or not to
-    process more than one of the `'message'`, `'ping'`, and `'pong'` events per
-    microtask. To improve compatibility with the WHATWG standard, the default
-    value is `false`. Setting it to `true` improves performance slightly.
+  - `allowSynchronousEvents` {Boolean} Specifies whether any of the `'message'`,
+    `'ping'`, and `'pong'` events can be emitted multiple times in the same
+    tick. To improve compatibility with the WHATWG standard, the default value
+    is `false`. Setting it to `true` improves performance slightly.
   - `backlog` {Number} The maximum length of the queue of pending connections.
   - `clientTracking` {Boolean} Specifies whether or not to track clients.
   - `handleProtocols` {Function} A function which can be used to handle the
@@ -296,10 +296,10 @@ This class represents a WebSocket. It extends the `EventEmitter`.
 - `address` {String|url.URL} The URL to which to connect.
 - `protocols` {String|Array} The list of subprotocols.
 - `options` {Object}
-  - `allowMultipleEventsPerMicrotask` {Boolean} Specifies whether or not to
-    process more than one of the `'message'`, `'ping'`, and `'pong'` events per
-    microtask. To improve compatibility with the WHATWG standard, the default
-    value is `false`. Setting it to `true` improves performance slightly.
+  - `allowSynchronousEvents` {Boolean} Specifies whether any of the `'message'`,
+    `'ping'`, and `'pong'` events can be emitted multiple times in the same
+    tick. To improve compatibility with the WHATWG standard, the default value
+    is `false`. Setting it to `true` improves performance slightly.
   - `finishRequest` {Function} A function which can be used to customize the
     headers of each http request before it is sent. See description below.
   - `followRedirects` {Boolean} Whether or not to follow redirects. Defaults to
diff --git a/lib/receiver.js b/lib/receiver.js
@@ -39,9 +39,9 @@ class Receiver extends Writable {
    * Creates a Receiver instance.
    *
    * @param {Object} [options] Options object
-   * @param {Boolean} [options.allowMultipleEventsPerMicrotask=false] Specifies
-   *     whether or not to process more than one of the `'message'`, `'ping'`,
-   *     and `'pong'` events per microtask
+   * @param {Boolean} [options.allowSynchronousEvents=false] Specifies whether
+   *     any of the `'message'`, `'ping'`, and `'pong'` events can be emitted
+   *     multiple times in the same tick
    * @param {String} [options.binaryType=nodebuffer] The type for binary data
    * @param {Object} [options.extensions] An object containing the negotiated
    *     extensions
@@ -54,8 +54,7 @@ class Receiver extends Writable {
   constructor(options = {}) {
     super();
 
-    this._allowMultipleEventsPerMicrotask =
-      !!options.allowMultipleEventsPerMicrotask;
+    this._allowSynchronousEvents = !!options.allowSynchronousEvents;
     this._binaryType = options.binaryType || BINARY_TYPES[0];
     this._extensions = options.extensions || {};
     this._isServer = !!options.isServer;
@@ -573,7 +572,7 @@ class Receiver extends Writable {
       // decompressed asynchronously, so there is no need to defer the event
       // as it will be emitted asynchronously anyway.
       //
-      if (this._state === INFLATING || this._allowMultipleEventsPerMicrotask) {
+      if (this._state === INFLATING || this._allowSynchronousEvents) {
         this.emit('message', data, true);
         this._state = GET_INFO;
       } else {
@@ -600,7 +599,7 @@ class Receiver extends Writable {
         return;
       }
 
-      if (this._state === INFLATING || this._allowMultipleEventsPerMicrotask) {
+      if (this._state === INFLATING || this._allowSynchronousEvents) {
         this.emit('message', buf, false);
         this._state = GET_INFO;
       } else {
@@ -671,7 +670,7 @@ class Receiver extends Writable {
       return;
     }
 
-    if (this._allowMultipleEventsPerMicrotask) {
+    if (this._allowSynchronousEvents) {
       this.emit(this._opcode === 0x09 ? 'ping' : 'pong', data);
       this._state = GET_INFO;
     } else {
diff --git a/lib/websocket-server.js b/lib/websocket-server.js
@@ -29,9 +29,9 @@ class WebSocketServer extends EventEmitter {
    * Create a `WebSocketServer` instance.
    *
    * @param {Object} options Configuration options
-   * @param {Boolean} [options.allowMultipleEventsPerMicrotask=false] Specifies
-   *     whether or not to process more than one of the `'message'`, `'ping'`,
-   *     and `'pong'` events per microtask
+   * @param {Boolean} [options.allowSynchronousEvents=false] Specifies whether
+   *     any of the `'message'`, `'ping'`, and `'pong'` events can be emitted
+   *     multiple times in the same tick
    * @param {Number} [options.backlog=511] The maximum length of the queue of
    *     pending connections
    * @param {Boolean} [options.clientTracking=true] Specifies whether or not to
@@ -58,7 +58,7 @@ class WebSocketServer extends EventEmitter {
     super();
 
     options = {
-      allowMultipleEventsPerMicrotask: false,
+      allowSynchronousEvents: false,
       maxPayload: 100 * 1024 * 1024,
       skipUTF8Validation: false,
       perMessageDeflate: false,
@@ -413,8 +413,7 @@ class WebSocketServer extends EventEmitter {
     socket.removeListener('error', socketOnError);
 
     ws.setSocket(socket, head, {
-      allowMultipleEventsPerMicrotask:
-        this.options.allowMultipleEventsPerMicrotask,
+      allowSynchronousEvents: this.options.allowSynchronousEvents,
       maxPayload: this.options.maxPayload,
       skipUTF8Validation: this.options.skipUTF8Validation
     });
diff --git a/lib/websocket.js b/lib/websocket.js
@@ -192,9 +192,9 @@ class WebSocket extends EventEmitter {
    * @param {Duplex} socket The network socket between the server and client
    * @param {Buffer} head The first packet of the upgraded stream
    * @param {Object} options Options object
-   * @param {Boolean} [options.allowMultipleEventsPerMicrotask=false] Specifies
-   *     whether or not to process more than one of the `'message'`, `'ping'`,
-   *     and `'pong'` events per microtask
+   * @param {Boolean} [options.allowSynchronousEvents=false] Specifies whether
+   *     any of the `'message'`, `'ping'`, and `'pong'` events can be emitted
+   *     multiple times in the same tick
    * @param {Function} [options.generateMask] The function used to generate the
    *     masking key
    * @param {Number} [options.maxPayload=0] The maximum allowed message size
@@ -204,7 +204,7 @@ class WebSocket extends EventEmitter {
    */
   setSocket(socket, head, options) {
     const receiver = new Receiver({
-      allowMultipleEventsPerMicrotask: options.allowMultipleEventsPerMicrotask,
+      allowSynchronousEvents: options.allowSynchronousEvents,
       binaryType: this.binaryType,
       extensions: this._extensions,
       isServer: this._isServer,
@@ -622,9 +622,9 @@ module.exports = WebSocket;
  * @param {(String|URL)} address The URL to which to connect
  * @param {Array} protocols The subprotocols
  * @param {Object} [options] Connection options
- * @param {Boolean} [options.allowMultipleEventsPerMicrotask=false] Specifies
- *     whether or not to process more than one of the `'message'`, `'ping'`,
- *     and `'pong'` events per microtask
+ * @param {Boolean} [options.allowSynchronousEvents=false] Specifies whether any
+ *     of the `'message'`, `'ping'`, and `'pong'` events can be emitted multiple
+ *     times in the same tick
  * @param {Function} [options.finishRequest] A function which can be used to
  *     customize the headers of each http request before it is sent
  * @param {Boolean} [options.followRedirects=false] Whether or not to follow
@@ -649,7 +649,7 @@ module.exports = WebSocket;
  */
 function initAsClient(websocket, address, protocols, options) {
   const opts = {
-    allowMultipleEventsPerMicrotask: false,
+    allowSynchronousEvents: false,
     protocolVersion: protocolVersions[1],
     maxPayload: 100 * 1024 * 1024,
     skipUTF8Validation: false,
@@ -1001,7 +1001,7 @@ function initAsClient(websocket, address, protocols, options) {
     }
 
     websocket.setSocket(socket, head, {
-      allowMultipleEventsPerMicrotask: opts.allowMultipleEventsPerMicrotask,
+      allowSynchronousEvents: opts.allowSynchronousEvents,
       generateMask: opts.generateMask,
       maxPayload: opts.maxPayload,
       skipUTF8Validation: opts.skipUTF8Validation
diff --git a/test/receiver.test.js b/test/receiver.test.js
@@ -443,7 +443,7 @@ describe('Receiver', () => {
       buf[i + 1] = 0x00;
     }
 
-    const receiver = new Receiver();
+    const receiver = new Receiver({ allowSynchronousEvents: true });
     let counter = 0;
 
     receiver.on('message', (data, isBinary) => {
@@ -1151,7 +1151,7 @@ describe('Receiver', () => {
     receiver.write(Buffer.from('82008200', 'hex'));
   });
 
-  it('honors the `allowMultipleEventsPerMicrotask` option', (done) => {
+  it('honors the `allowSynchronousEvents` option', (done) => {
     const actual = [];
     const expected = [
       '1',
@@ -1179,7 +1179,7 @@ describe('Receiver', () => {
       });
     }
 
-    const receiver = new Receiver({ allowMultipleEventsPerMicrotask: true });
+    const receiver = new Receiver({ allowSynchronousEvents: true });
 
     receiver.on('message', listener);
     receiver.on('ping', listener);
