chore(release): 4.5.4

Diff: https://github.com/socketio/socket.io/compare/4.5.3...4.5.4
chore: bump engine.io to version 6.2.1
2026-01-11 16:08:24 -05:00 · 2022-11-22 22:45:13 +01:00 · 2022-11-22 22:35:53 +01:00 · 2022-11-22 22:32:09 +01:00 · 2022-11-02 08:40:26 +01:00 · 2022-10-15 07:14:45 +02:00
19 changed files with 1390 additions and 423 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -12,18 +12,25 @@ permissions:
 jobs:
  test-node:
    runs-on: ubuntu-latest
+    timeout-minutes: 10

    strategy:
      matrix:
        node-version: [12, 14, 16]

    steps:
-      - uses: actions/checkout@v2
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
-      - run: npm ci
-      - run: npm test
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
        env:
          CI: true
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,81 @@
+# History
+
+## 2022
+
+- [4.5.4](#454-2022-11-22) (Nov 2022)
+- [4.5.3](#453-2022-10-15) (Oct 2022)
+- [4.5.2](#452-2022-09-02) (Sep 2022)
+- [2.5.0](#250-2022-06-26) (Jun 2022) (from the [2.x](https://github.com/socketio/socket.io/tree/2.x) branch)
+- [4.5.1](#451-2022-05-17) (May 2022)
+- [4.5.0](#450-2022-04-23) (Apr 2022)
+- [4.4.1](#441-2022-01-06) (Jan 2022)
+
+## 2021
+
+- [4.4.0](#440-2021-11-18) (Nov 2021)
+- [4.3.2](#432-2021-11-08) (Nov 2021)
+- [4.3.1](#431-2021-10-16) (Oct 2021)
+- [4.3.0](#430-2021-10-14) (Oct 2021)
+- [4.2.0](#420-2021-08-30) (Aug 2021)
+- [4.1.3](#413-2021-07-10) (Jul 2021)
+- [4.1.2](#412-2021-05-17) (May 2021)
+- [4.1.1](#411-2021-05-11) (May 2021)
+- [4.1.0](#410-2021-05-11) (May 2021)
+- [4.0.2](#402-2021-05-06) (May 2021)
+- [4.0.1](#401-2021-03-31) (Mar 2021)
+- [**4.0.0**](#400-2021-03-10) (Mar 2021)
+- [3.1.2](#312-2021-02-26) (Feb 2021)
+- [3.1.1](#311-2021-02-03) (Feb 2021)
+- [3.1.0](#310-2021-01-15) (Jan 2021)
+- [2.4.1](#241-2021-01-07) (Jan 2021) (from the [2.x](https://github.com/socketio/socket.io/tree/2.x) branch)
+- [3.0.5](#305-2021-01-05) (Jan 2021)
+- [2.4.0](#240-2021-01-04) (Jan 2021) (from the [2.x](https://github.com/socketio/socket.io/tree/2.x) branch)
+
+## 2020
+
+- [3.0.4](#304-2020-12-07) (Dec 2020)
+- [3.0.3](#303-2020-11-19) (Nov 2020)
+- [3.0.2](#302-2020-11-17) (Nov 2020)
+- [3.0.1](#301-2020-11-09) (Nov 2020)
+- [**3.0.0**](#300-2020-11-05) (Nov 2020)
+
+## 2019
+
+- [2.3.0](#230-2019-09-20) (Sep 2019)
+
+## 2018
+
+- [2.2.0](#220-2018-11-29) (Nov 2018)
+- [2.1.1](#211-2018-05-17) (May 2018)
+- [2.1.0](#210-2018-03-29) (Mar 2018)
+
+
+# Release notes
+
+## [4.5.4](https://github.com/socketio/socket.io/compare/4.5.3...4.5.4) (2022-11-22)
+
+This release contains a bump of:
+
+- `engine.io` in order to fix [CVE-2022-41940](https://github.com/socketio/engine.io/security/advisories/GHSA-r7qp-cfhv-p84w)
+- `socket.io-parser` in order to fix [CVE-2022-2421](https://github.com/advisories/GHSA-qm95-pgcg-qqfq).
+
+### Dependencies
+
+- [`engine.io@~6.2.1`](https://github.com/socketio/engine.io-client/tree/6.2.1) ([diff](https://github.com/socketio/engine.io/compare/6.2.0...6.2.1))
+- [`ws@~8.2.3`](https://github.com/websockets/ws/releases/tag/8.2.3)
+
+
+
+## [4.5.3](https://github.com/socketio/socket.io/compare/4.5.2...4.5.3) (2022-10-15)
+
+
+### Bug Fixes
+
+* **typings:** accept an HTTP2 server in the constructor ([d3d0a2d](https://github.com/socketio/socket.io/commit/d3d0a2d5beaff51fd145f810bcaf6914213f8a06))
+* **typings:** apply types to "io.timeout(...).emit()" calls ([e357daf](https://github.com/socketio/socket.io/commit/e357daf5858560bc84e7e50cd36f0278d6721ea1))
+
+
+
 ## [4.5.2](https://github.com/socketio/socket.io/compare/4.5.1...4.5.2) (2022-09-02)


@@ -8,6 +86,18 @@



+# [2.5.0](https://github.com/socketio/socket.io/compare/2.4.1...2.5.0) (2022-06-26)
+
+
+### Bug Fixes
+
+* fix race condition in dynamic namespaces ([05e1278](https://github.com/socketio/socket.io/commit/05e1278cfa99f3ecf3f8f0531ffe57d850e9a05b))
+* ignore packet received after disconnection ([22d4bdf](https://github.com/socketio/socket.io/commit/22d4bdf00d1a03885dc0171125faddfaef730066))
+* only set 'connected' to true after middleware execution ([226cc16](https://github.com/socketio/socket.io/commit/226cc16165f9fe60f16ff4d295fb91c8971cde35))
+* prevent the socket from joining a room after disconnection ([f223178](https://github.com/socketio/socket.io/commit/f223178eb655a7713303b21a78f9ef9e161d6458))
+
+
+
 ## [4.5.1](https://github.com/socketio/socket.io/compare/4.5.0...4.5.1) (2022-05-17)


@@ -244,6 +334,16 @@ we only add a field in the JSON-encoded handshake data:
 * allow integers as event names ([1c220dd](https://github.com/socketio/socket.io-parser/commit/1c220ddbf45ea4b44bc8dbf6f9ae245f672ba1b9))


+
+## [2.4.1](https://github.com/socketio/socket.io/compare/2.4.0...2.4.1) (2021-01-07)
+
+
+### Reverts
+
+* fix(security): do not allow all origins by default ([a169050](https://github.com/socketio/socket.io/commit/a1690509470e9dd5559cec4e60908ca6c23e9ba0))
+
+
+
 ## [3.0.5](https://github.com/socketio/socket.io/compare/3.0.4...3.0.5) (2021-01-05)


@@ -257,6 +357,17 @@ we only add a field in the JSON-encoded handshake data:
 * restore the socket middleware functionality ([bf54327](https://github.com/socketio/socket.io/commit/bf5432742158e4d5ba2722cff4a614967dffa5b9))


+
+# [2.4.0](https://github.com/socketio/socket.io/compare/2.3.0...2.4.0) (2021-01-04)
+
+
+### Bug Fixes
+
+* **security:** do not allow all origins by default ([f78a575](https://github.com/socketio/socket.io/commit/f78a575f66ab693c3ea96ea88429ddb1a44c86c7))
+* properly overwrite the query sent in the handshake ([d33a619](https://github.com/socketio/socket.io/commit/d33a619905a4905c153d4fec337c74da5b533a9e))
+
+
+
 ## [3.0.4](https://github.com/socketio/socket.io/compare/3.0.3...3.0.4) (2020-12-07)


@@ -542,3 +653,78 @@ io.of("/admin").use((socket, next) => {

 This method was kept for backward-compatibility with pre-1.0 versions.

+
+
+# [2.3.0](https://github.com/socketio/socket.io/compare/2.2.0...2.3.0) (2019-09-20)
+
+This release mainly contains a bump of the `engine.io` and `ws` packages, but no additional features.
+
+
+
+# [2.2.0](https://github.com/socketio/socket.io/compare/2.1.1...2.2.0) (2018-11-29)
+
+### Features
+
+- add cache-control header when serving the client source ([#2907](https://github.com/socketio/socket.io/pull/2907)) ([b00ae50](https://github.com/socketio/socket.io/commit/b00ae50be65d1bc88fa95145f1c486a6886a6b76))
+
+### Bug fixes
+
+- throw an error when trying to access the clients of a dynamic namespace ([#3355](https://github.com/socketio/socket.io/pull/3355)) ([a7fbd1a](https://github.com/socketio/socket.io/commit/a7fbd1ac4a47cafd832fc62e371754df924c5903))
+
+
+
+# [2.1.1](https://github.com/socketio/socket.io/compare/2.1.0...2.1.1) (2018-05-17)
+
+### Features
+
+- add local flag to the socket object ([#3129](https://github.com/socketio/socket.io/pull/3219)) ([1decae3](https://github.com/socketio/socket.io/commit/1decae341c80c0417b32d3124ca30c005240b48a))
+
+```js
+socket.local.to('room101').emit(/* */);
+```
+
+
+# [2.1.0](https://github.com/socketio/socket.io/compare/2.1.1...2.2.0) (2018-03-29)
+
+### Features
+
+- add a 'binary' flag ([#3185](https://github.com/socketio/socket.io/pull/3185)) ([f48a06c](https://github.com/socketio/socket.io/commit/f48a06c040280b44f90fd225c888910544fd63b5))
+
+```js
+// by default, the object is recursively scanned to check whether it contains some binary data
+// in the following example, the check is skipped in order to improve performance
+socket.binary(false).emit('plain-object', object);
+
+// it also works at the namespace level
+io.binary(false).emit('plain-object', object);
+```
+
+- add support for dynamic namespaces ([#3195](https://github.com/socketio/socket.io/pull/3195)) ([c0c79f0](https://github.com/socketio/socket.io/commit/c0c79f019e7138194e438339f8192705957c8ec3))
+
+```js
+io.of(/^\/dynamic-\d+$/).on('connect', (socket) => {
+  // socket.nsp.name = '/dynamic-101'
+});
+
+// client-side
+const client = require('socket.io-client')('/dynamic-101');
+```
+
+### Bug fixes
+
+- properly emit 'connect' when using a custom namespace ([#3197](https://github.com/socketio/socket.io/pull/3197)) ([f4fc517](https://github.com/socketio/socket.io/commit/f4fc517e0fe25866c95b584291487b8cbdff889d))
+- include the protocol in the origins check ([#3198](https://github.com/socketio/socket.io/pull/3198)) ([1f1d64b](https://github.com/socketio/socket.io/commit/1f1d64bab61a273712a199591a3f76210d8c0959))
+
+### Important note :warning: from Engine.IO [3.2.0 release](https://github.com/socketio/engine.io/releases/tag/3.2.0)
+
+There are two non-breaking changes that are somehow quite important:
+
+- `ws` was reverted as the default wsEngine (https://github.com/socketio/engine.io/pull/550), as there was several blocking issues with `uws`. You can still use `uws` by running `npm install uws --save` in your project and using the `wsEngine` option:
+```js
+var engine = require('engine.io');
+var server = engine.listen(3000, {
+  wsEngine: 'uws'
+});
+```
+
+- `pingTimeout` now defaults to 5 seconds (instead of 60 seconds): https://github.com/socketio/engine.io/pull/551
--- a/client-dist/socket.io.esm.min.js
+++ b/client-dist/socket.io.esm.min.js
--- a/client-dist/socket.io.esm.min.js.map
+++ b/client-dist/socket.io.esm.min.js.map
--- a/client-dist/socket.io.js
+++ b/client-dist/socket.io.js
@@ -1,5 +1,5 @@
 /*!
- * Socket.IO v4.5.2
+ * Socket.IO v4.5.4
 * (c) 2014-2022 Guillermo Rauch
 * Released under the MIT License.
 */
@@ -1792,11 +1792,11 @@
    var regx = /\/{2,9}/g,
        names = path.replace(regx, "/").split("/");

-    if (path.substr(0, 1) == '/' || path.length === 0) {
+    if (path.slice(0, 1) == '/' || path.length === 0) {
      names.splice(0, 1);
    }

-    if (path.substr(path.length - 1, 1) == '/') {
+    if (path.slice(-1) == '/') {
      names.splice(names.length - 1, 1);
    }

@@ -1896,14 +1896,16 @@
          // Firefox closes the connection when the "beforeunload" event is emitted but not Chrome. This event listener
          // ensures every browser behaves the same (no "disconnect" event at the Socket.IO level when the page is
          // closed/reloaded)
-          addEventListener("beforeunload", function () {
+          _this.beforeunloadEventListener = function () {
            if (_this.transport) {
              // silently close the transport
              _this.transport.removeAllListeners();

              _this.transport.close();
            }
-          }, false);
+          };
+
+          addEventListener("beforeunload", _this.beforeunloadEventListener, false);
        }

        if (_this.hostname !== "localhost") {
@@ -2451,6 +2453,7 @@
          this.transport.removeAllListeners();

          if (typeof removeEventListener === "function") {
+            removeEventListener("beforeunload", this.beforeunloadEventListener, false);
            removeEventListener("offline", this.offlineEventListener, false);
          } // set ready state

@@ -2676,8 +2679,14 @@
  function _reconstructPacket(data, buffers) {
    if (!data) return data;

-    if (data && data._placeholder) {
-      return buffers[data.num]; // appropriate buffer (should be natural order anyway)
+    if (data && data._placeholder === true) {
+      var isIndexValid = typeof data.num === "number" && data.num >= 0 && data.num < buffers.length;
+
+      if (isIndexValid) {
+        return buffers[data.num]; // appropriate buffer (should be natural order anyway)
+      } else {
+        throw new Error("illegal attachments");
+      }
    } else if (Array.isArray(data)) {
      for (var i = 0; i < data.length; i++) {
        data[i] = _reconstructPacket(data[i], buffers);
@@ -2837,6 +2846,10 @@
        var packet;

        if (typeof obj === "string") {
+          if (this.reconstructor) {
+            throw new Error("got plaintext data when reconstructing a packet");
+          }
+
          packet = this.decodeString(obj);

          if (packet.type === PacketType.BINARY_EVENT || packet.type === PacketType.BINARY_ACK) {
@@ -3082,6 +3095,31 @@
    newListener: 1,
    removeListener: 1
  });
+  /**
+   * A Socket is the fundamental class for interacting with the server.
+   *
+   * A Socket belongs to a certain Namespace (by default /) and uses an underlying {@link Manager} to communicate.
+   *
+   * @example
+   * const socket = io();
+   *
+   * socket.on("connect", () => {
+   *   console.log("connected");
+   * });
+   *
+   * // send an event to the server
+   * socket.emit("foo", "bar");
+   *
+   * socket.on("foobar", () => {
+   *   // an event was received from the server
+   * });
+   *
+   * // upon disconnection
+   * socket.on("disconnect", (reason) => {
+   *   console.log(`disconnected due to ${reason}`);
+   * });
+   */
+
  var Socket = /*#__PURE__*/function (_Emitter) {
    _inherits(Socket, _Emitter);

@@ -3089,8 +3127,6 @@

    /**
     * `Socket` constructor.
-     *
-     * @public
     */
    function Socket(io, nsp, opts) {
      var _this;
@@ -3098,8 +3134,31 @@
      _classCallCheck(this, Socket);

      _this = _super.call(this);
+      /**
+       * Whether the socket is currently connected to the server.
+       *
+       * @example
+       * const socket = io();
+       *
+       * socket.on("connect", () => {
+       *   console.log(socket.connected); // true
+       * });
+       *
+       * socket.on("disconnect", () => {
+       *   console.log(socket.connected); // false
+       * });
+       */
+
      _this.connected = false;
+      /**
+       * Buffer for packets received before the CONNECT packet
+       */
+
      _this.receiveBuffer = [];
+      /**
+       * Buffer for packets that will be sent once the socket is connected
+       */
+
      _this.sendBuffer = [];
      _this.ids = 0;
      _this.acks = {};
@@ -3116,6 +3175,17 @@
    }
    /**
     * Whether the socket is currently disconnected
+     *
+     * @example
+     * const socket = io();
+     *
+     * socket.on("connect", () => {
+     *   console.log(socket.disconnected); // false
+     * });
+     *
+     * socket.on("disconnect", () => {
+     *   console.log(socket.disconnected); // true
+     * });
     */


@@ -3138,7 +3208,21 @@
        this.subs = [on(io, "open", this.onopen.bind(this)), on(io, "packet", this.onpacket.bind(this)), on(io, "error", this.onerror.bind(this)), on(io, "close", this.onclose.bind(this))];
      }
      /**
-       * Whether the Socket will try to reconnect when its Manager connects or reconnects
+       * Whether the Socket will try to reconnect when its Manager connects or reconnects.
+       *
+       * @example
+       * const socket = io();
+       *
+       * console.log(socket.active); // true
+       *
+       * socket.on("disconnect", (reason) => {
+       *   if (reason === "io server disconnect") {
+       *     // the disconnection was initiated by the server, you need to manually reconnect
+       *     console.log(socket.active); // false
+       *   }
+       *   // else the socket will automatically try to reconnect
+       *   console.log(socket.active); // true
+       * });
       */

    }, {
@@ -3149,7 +3233,12 @@
      /**
       * "Opens" the socket.
       *
-       * @public
+       * @example
+       * const socket = io({
+       *   autoConnect: false
+       * });
+       *
+       * socket.connect();
       */

    }, {
@@ -3163,7 +3252,7 @@
        return this;
      }
      /**
-       * Alias for connect()
+       * Alias for {@link connect()}.
       */

    }, {
@@ -3174,8 +3263,17 @@
      /**
       * Sends a `message` event.
       *
+       * This method mimics the WebSocket.send() method.
+       *
+       * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
+       *
+       * @example
+       * socket.send("hello");
+       *
+       * // this is equivalent to
+       * socket.emit("message", "hello");
+       *
       * @return self
-       * @public
       */

    }, {
@@ -3193,8 +3291,18 @@
       * Override `emit`.
       * If the event is in `events`, it's emitted normally.
       *
+       * @example
+       * socket.emit("hello", "world");
+       *
+       * // all serializable datastructures are supported (no need to call JSON.stringify)
+       * socket.emit("hello", 1, "2", { 3: ["4"], 5: Uint8Array.from([6]) });
+       *
+       * // with an acknowledgement from the server
+       * socket.emit("hello", "world", (val) => {
+       *   // ...
+       * });
+       *
       * @return self
-       * @public
       */

    }, {
@@ -3552,10 +3660,20 @@
        this.io["_destroy"](this);
      }
      /**
-       * Disconnects the socket manually.
+       * Disconnects the socket manually. In that case, the socket will not try to reconnect.
+       *
+       * If this is the last active Socket instance of the {@link Manager}, the low-level connection will be closed.
+       *
+       * @example
+       * const socket = io();
+       *
+       * socket.on("disconnect", (reason) => {
+       *   // console.log(reason); prints "io client disconnect"
+       * });
+       *
+       * socket.disconnect();
       *
       * @return self
-       * @public
       */

    }, {
@@ -3578,10 +3696,9 @@
        return this;
      }
      /**
-       * Alias for disconnect()
+       * Alias for {@link disconnect()}.
       *
       * @return self
-       * @public
       */

    }, {
@@ -3592,9 +3709,11 @@
      /**
       * Sets the compress flag.
       *
+       * @example
+       * socket.compress(false).emit("hello");
+       *
       * @param compress - if `true`, compresses the sending data
       * @return self
-       * @public
       */

    }, {
@@ -3607,8 +3726,10 @@
       * Sets a modifier for a subsequent event emission that the event message will be dropped when this socket is not
       * ready to send messages.
       *
+       * @example
+       * socket.volatile.emit("hello"); // the server may or may not receive it
+       *
       * @returns self
-       * @public
       */

    }, {
@@ -3621,16 +3742,14 @@
       * Sets a modifier for a subsequent event emission that the callback will be called with an error when the
       * given number of milliseconds have elapsed without an acknowledgement from the server:
       *
-       * ```
+       * @example
       * socket.timeout(5000).emit("my-event", (err) => {
       *   if (err) {
       *     // the server did not acknowledge the event in the given delay
       *   }
       * });
-       * ```
       *
       * @returns self
-       * @public
       */

    }, {
@@ -3643,8 +3762,12 @@
       * Adds a listener that will be fired when any event is emitted. The event name is passed as the first argument to the
       * callback.
       *
+       * @example
+       * socket.onAny((event, ...args) => {
+       *   console.log(`got ${event}`);
+       * });
+       *
       * @param listener
-       * @public
       */

    }, {
@@ -3660,8 +3783,12 @@
       * Adds a listener that will be fired when any event is emitted. The event name is passed as the first argument to the
       * callback. The listener is added to the beginning of the listeners array.
       *
+       * @example
+       * socket.prependAny((event, ...args) => {
+       *   console.log(`got event ${event}`);
+       * });
+       *
       * @param listener
-       * @public
       */

    }, {
@@ -3676,8 +3803,20 @@
      /**
       * Removes the listener that will be fired when any event is emitted.
       *
+       * @example
+       * const catchAllListener = (event, ...args) => {
+       *   console.log(`got event ${event}`);
+       * }
+       *
+       * socket.onAny(catchAllListener);
+       *
+       * // remove a specific listener
+       * socket.offAny(catchAllListener);
+       *
+       * // or remove all listeners
+       * socket.offAny();
+       *
       * @param listener
-       * @public
       */

    }, {
@@ -3705,8 +3844,6 @@
      /**
       * Returns an array of listeners that are listening for any event that is specified. This array can be manipulated,
       * e.g. to remove listeners.
-       *
-       * @public
       */

    }, {
@@ -3718,17 +3855,14 @@
       * Adds a listener that will be fired when any event is emitted. The event name is passed as the first argument to the
       * callback.
       *
-       * @param listener
-       *
-       * <pre><code>
+       * Note: acknowledgements sent to the server are not included.
       *
+       * @example
       * socket.onAnyOutgoing((event, ...args) => {
-       *   console.log(event);
+       *   console.log(`sent event ${event}`);
       * });
       *
-       * </pre></code>
-       *
-       * @public
+       * @param listener
       */

    }, {
@@ -3744,17 +3878,14 @@
       * Adds a listener that will be fired when any event is emitted. The event name is passed as the first argument to the
       * callback. The listener is added to the beginning of the listeners array.
       *
-       * @param listener
-       *
-       * <pre><code>
+       * Note: acknowledgements sent to the server are not included.
       *
+       * @example
       * socket.prependAnyOutgoing((event, ...args) => {
-       *   console.log(event);
+       *   console.log(`sent event ${event}`);
       * });
       *
-       * </pre></code>
-       *
-       * @public
+       * @param listener
       */

    }, {
@@ -3769,22 +3900,20 @@
      /**
       * Removes the listener that will be fired when any event is emitted.
       *
-       * @param listener
-       *
-       * <pre><code>
-       *
-       * const handler = (event, ...args) => {
-       *   console.log(event);
+       * @example
+       * const catchAllListener = (event, ...args) => {
+       *   console.log(`sent event ${event}`);
       * }
       *
-       * socket.onAnyOutgoing(handler);
+       * socket.onAnyOutgoing(catchAllListener);
       *
-       * // then later
-       * socket.offAnyOutgoing(handler);
+       * // remove a specific listener
+       * socket.offAnyOutgoing(catchAllListener);
       *
-       * </pre></code>
+       * // or remove all listeners
+       * socket.offAnyOutgoing();
       *
-       * @public
+       * @param [listener] - the catch-all listener (optional)
       */

    }, {
@@ -3812,8 +3941,6 @@
      /**
       * Returns an array of listeners that are listening for any event that is specified. This array can be manipulated,
       * e.g. to remove listeners.
-       *
-       * @public
       */

    }, {
@@ -4176,7 +4303,7 @@
        try {
          this.decoder.add(data);
        } catch (e) {
-          this.onclose("parse error");
+          this.onclose("parse error", e);
        }
      }
      /**
@@ -4188,7 +4315,12 @@
    }, {
      key: "ondecoded",
      value: function ondecoded(packet) {
-        this.emitReserved("packet", packet);
+        var _this3 = this;
+
+        // the nextTick call prevents an exception in a user-provided event listener from triggering a disconnection due to a "parse error"
+        nextTick(function () {
+          _this3.emitReserved("packet", packet);
+        }, this.setTimeoutFn);
      }
      /**
       * Called upon socket error.
@@ -4326,7 +4458,7 @@
    }, {
      key: "reconnect",
      value: function reconnect() {
-        var _this3 = this;
+        var _this4 = this;

        if (this._reconnecting || this.skipReconnect) return this;
        var self = this;
@@ -4341,7 +4473,7 @@
          var timer = this.setTimeoutFn(function () {
            if (self.skipReconnect) return;

-            _this3.emitReserved("reconnect_attempt", self.backoff.attempts); // check again for the case socket closed in above events
+            _this4.emitReserved("reconnect_attempt", self.backoff.attempts); // check again for the case socket closed in above events


            if (self.skipReconnect) return;
@@ -4350,7 +4482,7 @@
                self._reconnecting = false;
                self.reconnect();

-                _this3.emitReserved("reconnect_error", err);
+                _this4.emitReserved("reconnect_error", err);
              } else {
                self.onreconnect();
              }
--- a/client-dist/socket.io.js.map
+++ b/client-dist/socket.io.js.map
--- a/client-dist/socket.io.min.js
+++ b/client-dist/socket.io.min.js
--- a/client-dist/socket.io.min.js.map
+++ b/client-dist/socket.io.min.js.map
--- a/client-dist/socket.io.msgpack.min.js
+++ b/client-dist/socket.io.msgpack.min.js
--- a/client-dist/socket.io.msgpack.min.js.map
+++ b/client-dist/socket.io.msgpack.min.js.map
--- a/examples/basic-crud-application/server/package.json
+++ b/examples/basic-crud-application/server/package.json
@@ -24,14 +24,14 @@
    "uuid": "^8.3.2"
  },
  "devDependencies": {
-    "@types/mocha": "^8.2.3",
    "@types/chai": "^4.2.16",
+    "@types/mocha": "^10.0.0",
    "@types/uuid": "^8.3.0",
    "chai": "^4.3.4",
-    "mocha": "^8.3.2",
+    "mocha": "^10.0.0",
    "nyc": "^15.1.0",
    "socket.io-client": "^4.0.1",
-    "ts-node": "^9.1.1",
+    "ts-node": "^10.9.1",
    "typescript": "^4.2.4"
  }
 }
--- a/lib/broadcast-operator.ts
+++ b/lib/broadcast-operator.ts
@@ -22,18 +22,27 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
  /**
   * Targets a room when emitting.
   *
-   * @param room
-   * @return a new BroadcastOperator instance
-   * @public
+   * @example
+   * // the “foo” event will be broadcast to all connected clients in the “room-101” room
+   * io.to("room-101").emit("foo", "bar");
+   *
+   * // with an array of rooms (a client will be notified at most once)
+   * io.to(["room-101", "room-102"]).emit("foo", "bar");
+   *
+   * // with multiple chained calls
+   * io.to("room-101").to("room-102").emit("foo", "bar");
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public to(room: Room | Room[]): BroadcastOperator<EmitEvents, SocketData> {
+  public to(room: Room | Room[]) {
    const rooms = new Set(this.rooms);
    if (Array.isArray(room)) {
      room.forEach((r) => rooms.add(r));
    } else {
      rooms.add(room);
    }
-    return new BroadcastOperator(
+    return new BroadcastOperator<EmitEvents, SocketData>(
      this.adapter,
      rooms,
      this.exceptRooms,
@@ -42,33 +51,43 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
  }

  /**
-   * Targets a room when emitting.
+   * Targets a room when emitting. Similar to `to()`, but might feel clearer in some cases:
   *
-   * @param room
-   * @return a new BroadcastOperator instance
-   * @public
+   * @example
+   * // disconnect all clients in the "room-101" room
+   * io.in("room-101").disconnectSockets();
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public in(room: Room | Room[]): BroadcastOperator<EmitEvents, SocketData> {
+  public in(room: Room | Room[]) {
    return this.to(room);
  }

  /**
   * Excludes a room when emitting.
   *
-   * @param room
-   * @return a new BroadcastOperator instance
-   * @public
+   * @example
+   * // the "foo" event will be broadcast to all connected clients, except the ones that are in the "room-101" room
+   * io.except("room-101").emit("foo", "bar");
+   *
+   * // with an array of rooms
+   * io.except(["room-101", "room-102"]).emit("foo", "bar");
+   *
+   * // with multiple chained calls
+   * io.except("room-101").except("room-102").emit("foo", "bar");
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public except(
-    room: Room | Room[]
-  ): BroadcastOperator<EmitEvents, SocketData> {
+  public except(room: Room | Room[]) {
    const exceptRooms = new Set(this.exceptRooms);
    if (Array.isArray(room)) {
      room.forEach((r) => exceptRooms.add(r));
    } else {
      exceptRooms.add(room);
    }
-    return new BroadcastOperator(
+    return new BroadcastOperator<EmitEvents, SocketData>(
      this.adapter,
      this.rooms,
      exceptRooms,
@@ -79,15 +98,15 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
  /**
   * Sets the compress flag.
   *
+   * @example
+   * io.compress(false).emit("hello");
+   *
   * @param compress - if `true`, compresses the sending data
   * @return a new BroadcastOperator instance
-   * @public
   */
-  public compress(
-    compress: boolean
-  ): BroadcastOperator<EmitEvents, SocketData> {
+  public compress(compress: boolean) {
    const flags = Object.assign({}, this.flags, { compress });
-    return new BroadcastOperator(
+    return new BroadcastOperator<EmitEvents, SocketData>(
      this.adapter,
      this.rooms,
      this.exceptRooms,
@@ -100,12 +119,14 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
   * receive messages (because of network slowness or other issues, or because they’re connected through long polling
   * and is in the middle of a request-response cycle).
   *
+   * @example
+   * io.volatile.emit("hello"); // the clients may or may not receive it
+   *
   * @return a new BroadcastOperator instance
-   * @public
   */
-  public get volatile(): BroadcastOperator<EmitEvents, SocketData> {
+  public get volatile() {
    const flags = Object.assign({}, this.flags, { volatile: true });
-    return new BroadcastOperator(
+    return new BroadcastOperator<EmitEvents, SocketData>(
      this.adapter,
      this.rooms,
      this.exceptRooms,
@@ -116,12 +137,15 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
  /**
   * Sets a modifier for a subsequent event emission that the event data will only be broadcast to the current node.
   *
-   * @return a new BroadcastOperator instance
-   * @public
+   * @example
+   * // the “foo” event will be broadcast to all connected clients on this node
+   * io.local.emit("foo", "bar");
+   *
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public get local(): BroadcastOperator<EmitEvents, SocketData> {
+  public get local() {
    const flags = Object.assign({}, this.flags, { local: true });
-    return new BroadcastOperator(
+    return new BroadcastOperator<EmitEvents, SocketData>(
      this.adapter,
      this.rooms,
      this.exceptRooms,
@@ -132,19 +156,20 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
  /**
   * Adds a timeout in milliseconds for the next operation
   *
-   * <pre><code>
-   *
+   * @example
   * io.timeout(1000).emit("some-event", (err, responses) => {
-   *   // ...
+   *   if (err) {
+   *     // some clients did not acknowledge the event in the given delay
+   *   } else {
+   *     console.log(responses); // one response per client
+   *   }
   * });
   *
-   * </pre></code>
-   *
   * @param timeout
   */
  public timeout(timeout: number) {
    const flags = Object.assign({}, this.flags, { timeout });
-    return new BroadcastOperator(
+    return new BroadcastOperator<EmitEvents, SocketData>(
      this.adapter,
      this.rooms,
      this.exceptRooms,
@@ -155,8 +180,23 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
  /**
   * Emits to all clients.
   *
+   * @example
+   * // the “foo” event will be broadcast to all connected clients
+   * io.emit("foo", "bar");
+   *
+   * // the “foo” event will be broadcast to all connected clients in the “room-101” room
+   * io.to("room-101").emit("foo", "bar");
+   *
+   * // with an acknowledgement expected from all connected clients
+   * io.timeout(1000).emit("some-event", (err, responses) => {
+   *   if (err) {
+   *     // some clients did not acknowledge the event in the given delay
+   *   } else {
+   *     console.log(responses); // one response per client
+   *   }
+   * });
+   *
   * @return Always true
-   * @public
   */
  public emit<Ev extends EventNames<EmitEvents>>(
    ev: Ev,
@@ -239,7 +279,8 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
  /**
   * Gets a list of clients.
   *
-   * @public
+   * @deprecated this method will be removed in the next major release, please use {@link Server#serverSideEmit} or
+   * {@link fetchSockets} instead.
   */
  public allSockets(): Promise<Set<SocketId>> {
    if (!this.adapter) {
@@ -251,13 +292,30 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
  }

  /**
-   * Returns the matching socket instances
+   * Returns the matching socket instances. This method works across a cluster of several Socket.IO servers.
   *
-   * @public
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   * // return all Socket instances
+   * const sockets = await io.fetchSockets();
+   *
+   * // return all Socket instances in the "room1" room
+   * const sockets = await io.in("room1").fetchSockets();
+   *
+   * for (const socket of sockets) {
+   *   console.log(socket.id);
+   *   console.log(socket.handshake);
+   *   console.log(socket.rooms);
+   *   console.log(socket.data);
+   *
+   *   socket.emit("hello");
+   *   socket.join("room1");
+   *   socket.leave("room2");
+   *   socket.disconnect();
+   * }
   */
-  public fetchSockets<SocketData = any>(): Promise<
-    RemoteSocket<EmitEvents, SocketData>[]
-  > {
+  public fetchSockets(): Promise<RemoteSocket<EmitEvents, SocketData>[]> {
    return this.adapter
      .fetchSockets({
        rooms: this.rooms,
@@ -280,10 +338,19 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
  }

  /**
-   * Makes the matching socket instances join the specified rooms
+   * Makes the matching socket instances join the specified rooms.
   *
-   * @param room
-   * @public
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   *
+   * // make all socket instances join the "room1" room
+   * io.socketsJoin("room1");
+   *
+   * // make all socket instances in the "room1" room join the "room2" and "room3" rooms
+   * io.in("room1").socketsJoin(["room2", "room3"]);
+   *
+   * @param room - a room, or an array of rooms
   */
  public socketsJoin(room: Room | Room[]): void {
    this.adapter.addSockets(
@@ -297,10 +364,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
  }

  /**
-   * Makes the matching socket instances leave the specified rooms
+   * Makes the matching socket instances leave the specified rooms.
   *
-   * @param room
-   * @public
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   * // make all socket instances leave the "room1" room
+   * io.socketsLeave("room1");
+   *
+   * // make all socket instances in the "room1" room leave the "room2" and "room3" rooms
+   * io.in("room1").socketsLeave(["room2", "room3"]);
+   *
+   * @param room - a room, or an array of rooms
   */
  public socketsLeave(room: Room | Room[]): void {
    this.adapter.delSockets(
@@ -314,10 +389,18 @@ export class BroadcastOperator<EmitEvents extends EventsMap, SocketData>
  }

  /**
-   * Makes the matching socket instances disconnect
+   * Makes the matching socket instances disconnect.
+   *
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   * // make all socket instances disconnect (the connections might be kept alive for other namespaces)
+   * io.disconnectSockets();
+   *
+   * // make all socket instances in the "room1" room disconnect and close the underlying connections
+   * io.in("room1").disconnectSockets(true);
   *
   * @param close - whether to close the underlying connection
-   * @public
   */
  public disconnectSockets(close: boolean = false): void {
    this.adapter.disconnectSockets(
@@ -359,7 +442,10 @@ export class RemoteSocket<EmitEvents extends EventsMap, SocketData>
    this.handshake = details.handshake;
    this.rooms = new Set(details.rooms);
    this.data = details.data;
-    this.operator = new BroadcastOperator(adapter, new Set([this.id]));
+    this.operator = new BroadcastOperator<EmitEvents, SocketData>(
+      adapter,
+      new Set([this.id])
+    );
  }

  public emit<Ev extends EventNames<EmitEvents>>(
@@ -373,7 +459,6 @@ export class RemoteSocket<EmitEvents extends EventsMap, SocketData>
   * Joins a room.
   *
   * @param {String|Array} room - room or array of rooms
-   * @public
   */
  public join(room: Room | Room[]): void {
    return this.operator.socketsJoin(room);
@@ -383,7 +468,6 @@ export class RemoteSocket<EmitEvents extends EventsMap, SocketData>
   * Leaves a room.
   *
   * @param {String} room
-   * @public
   */
  public leave(room: Room): void {
    return this.operator.socketsLeave(room);
@@ -394,8 +478,6 @@ export class RemoteSocket<EmitEvents extends EventsMap, SocketData>
   *
   * @param {Boolean} close - if `true`, closes the underlying connection
   * @return {Socket} self
-   *
-   * @public
   */
  public disconnect(close = false): this {
    this.operator.disconnectSockets(close);
--- a/lib/client.ts
+++ b/lib/client.ts
@@ -18,6 +18,13 @@ interface WriteOptions {
  wsPreEncoded?: string;
 }

+type CloseReason =
+  | "transport error"
+  | "transport close"
+  | "forced close"
+  | "ping timeout"
+  | "parse error";
+
 export class Client<
  ListenEvents extends EventsMap,
  EmitEvents extends EventsMap,
@@ -306,7 +313,7 @@ export class Client<
   * @param reason
   * @private
   */
-  private onclose(reason: string): void {
+  private onclose(reason: CloseReason | "forced server close"): void {
    debug("client close with reason %s", reason);

    // ignore a potential subsequent `close` event
--- a/lib/index.ts
+++ b/lib/index.ts
@@ -1,5 +1,6 @@
 import http = require("http");
 import type { Server as HTTPSServer } from "https";
+import type { Http2SecureServer } from "http2";
 import { createReadStream } from "fs";
 import { createDeflate, createGzip, createBrotliCompress } from "zlib";
 import accepts = require("accepts");
@@ -72,6 +73,32 @@ interface ServerOptions extends EngineOptions, AttachOptions {
  connectTimeout: number;
 }

+/**
+ * Represents a Socket.IO server.
+ *
+ * @example
+ * import { Server } from "socket.io";
+ *
+ * const io = new Server();
+ *
+ * io.on("connection", (socket) => {
+ *   console.log(`socket ${socket.id} connected`);
+ *
+ *   // send an event to the client
+ *   socket.emit("foo", "bar");
+ *
+ *   socket.on("foobar", () => {
+ *     // an event was received from the client
+ *   });
+ *
+ *   // upon disconnection
+ *   socket.on("disconnect", (reason) => {
+ *     console.log(`socket ${socket.id} disconnected due to ${reason}`);
+ *   });
+ * });
+ *
+ * io.listen(3000);
+ */
 export class Server<
  ListenEvents extends EventsMap = DefaultEventsMap,
  EmitEvents extends EventsMap = ListenEvents,
@@ -96,11 +123,8 @@ export class Server<
  /**
   * A reference to the underlying Engine.IO server.
   *
-   * Example:
-   *
-   * <code>
-   *   const clientsCount = io.engine.clientsCount;
-   * </code>
+   * @example
+   * const clientsCount = io.engine.clientsCount;
   *
   */
  public engine: any;
@@ -132,18 +156,17 @@ export class Server<
   * @private
   */
  _connectTimeout: number;
-  private httpServer: http.Server | HTTPSServer;
+  private httpServer: http.Server | HTTPSServer | Http2SecureServer;

  /**
   * Server constructor.
   *
   * @param srv http server, port, or options
   * @param [opts]
-   * @public
   */
  constructor(opts?: Partial<ServerOptions>);
  constructor(
-    srv?: http.Server | HTTPSServer | number,
+    srv?: http.Server | HTTPSServer | Http2SecureServer | number,
    opts?: Partial<ServerOptions>
  );
  constructor(
@@ -152,6 +175,7 @@ export class Server<
      | Partial<ServerOptions>
      | http.Server
      | HTTPSServer
+      | Http2SecureServer
      | number,
    opts?: Partial<ServerOptions>
  );
@@ -161,6 +185,7 @@ export class Server<
      | Partial<ServerOptions>
      | http.Server
      | HTTPSServer
+      | Http2SecureServer
      | number,
    opts: Partial<ServerOptions> = {}
  ) {
@@ -182,7 +207,9 @@ export class Server<
    this.sockets = this.of("/");
    this.opts = opts;
    if (srv || typeof srv == "number")
-      this.attach(srv as http.Server | HTTPSServer | number);
+      this.attach(
+        srv as http.Server | HTTPSServer | Http2SecureServer | number
+      );
  }

  /**
@@ -190,7 +217,6 @@ export class Server<
   *
   * @param v - whether to serve client code
   * @return self when setting or value when getting
-   * @public
   */
  public serveClient(v: boolean): this;
  public serveClient(): boolean;
@@ -253,7 +279,6 @@ export class Server<
   *
   * @param {String} v pathname
   * @return {Server|String} self when setting or value when getting
-   * @public
   */
  public path(v: string): this;
  public path(): string;
@@ -275,7 +300,6 @@ export class Server<
  /**
   * Set the delay after which a client without namespace is closed
   * @param v
-   * @public
   */
  public connectTimeout(v: number): this;
  public connectTimeout(): number;
@@ -291,7 +315,6 @@ export class Server<
   *
   * @param v pathname
   * @return self when setting or value when getting
-   * @public
   */
  public adapter(): AdapterConstructor | undefined;
  public adapter(v: AdapterConstructor): this;
@@ -312,10 +335,9 @@ export class Server<
   * @param srv - server or port
   * @param opts - options passed to engine.io
   * @return self
-   * @public
   */
  public listen(
-    srv: http.Server | HTTPSServer | number,
+    srv: http.Server | HTTPSServer | Http2SecureServer | number,
    opts: Partial<ServerOptions> = {}
  ): this {
    return this.attach(srv, opts);
@@ -327,10 +349,9 @@ export class Server<
   * @param srv - server or port
   * @param opts - options passed to engine.io
   * @return self
-   * @public
   */
  public attach(
-    srv: http.Server | HTTPSServer | number,
+    srv: http.Server | HTTPSServer | Http2SecureServer | number,
    opts: Partial<ServerOptions> = {}
  ): this {
    if ("function" == typeof srv) {
@@ -436,7 +457,7 @@ export class Server<
   * @private
   */
  private initEngine(
-    srv: http.Server | HTTPSServer,
+    srv: http.Server | HTTPSServer | Http2SecureServer,
    opts: EngineOptions & AttachOptions
  ): void {
    // initialize engine
@@ -459,7 +480,9 @@ export class Server<
   * @param srv http server
   * @private
   */
-  private attachServe(srv: http.Server | HTTPSServer): void {
+  private attachServe(
+    srv: http.Server | HTTPSServer | Http2SecureServer
+  ): void {
    debug("attaching client serving req handler");

    const evs = srv.listeners("request").slice(0);
@@ -561,7 +584,6 @@ export class Server<
   *
   * @param {engine.Server} engine engine.io (or compatible) server
   * @return self
-   * @public
   */
  public bind(engine): this {
    this.engine = engine;
@@ -589,9 +611,20 @@ export class Server<
  /**
   * Looks up a namespace.
   *
-   * @param {String|RegExp|Function} name nsp name
+   * @example
+   * // with a simple string
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * // with a regex
+   * const dynamicNsp = io.of(/^\/dynamic-\d+$/).on("connection", (socket) => {
+   *   const namespace = socket.nsp; // newNamespace.name === "/dynamic-101"
+   *
+   *   // broadcast to all clients in the given sub-namespace
+   *   namespace.emit("hello");
+   * });
+   *
+   * @param name - nsp name
   * @param fn optional, nsp `connection` ev handler
-   * @public
   */
  public of(
    name: string | RegExp | ParentNspNameMatchFn,
@@ -637,7 +670,6 @@ export class Server<
   * Closes server connection
   *
   * @param [fn] optional, called as `fn([err])` on error OR all conns closed
-   * @public
   */
  public close(fn?: (err?: Error) => void): void {
    for (const socket of this.sockets.sockets.values()) {
@@ -657,10 +689,15 @@ export class Server<
  }

  /**
-   * Sets up namespace middleware.
+   * Registers a middleware, which is a function that gets executed for every incoming {@link Socket}.
   *
-   * @return self
-   * @public
+   * @example
+   * io.use((socket, next) => {
+   *   // ...
+   *   next();
+   * });
+   *
+   * @param fn - the middleware function
   */
  public use(
    fn: (
@@ -675,43 +712,71 @@ export class Server<
  /**
   * Targets a room when emitting.
   *
-   * @param room
-   * @return self
-   * @public
+   * @example
+   * // the “foo” event will be broadcast to all connected clients in the “room-101” room
+   * io.to("room-101").emit("foo", "bar");
+   *
+   * // with an array of rooms (a client will be notified at most once)
+   * io.to(["room-101", "room-102"]).emit("foo", "bar");
+   *
+   * // with multiple chained calls
+   * io.to("room-101").to("room-102").emit("foo", "bar");
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public to(room: Room | Room[]): BroadcastOperator<EmitEvents, SocketData> {
+  public to(room: Room | Room[]) {
    return this.sockets.to(room);
  }

  /**
-   * Targets a room when emitting.
+   * Targets a room when emitting. Similar to `to()`, but might feel clearer in some cases:
   *
-   * @param room
-   * @return self
-   * @public
+   * @example
+   * // disconnect all clients in the "room-101" room
+   * io.in("room-101").disconnectSockets();
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public in(room: Room | Room[]): BroadcastOperator<EmitEvents, SocketData> {
+  public in(room: Room | Room[]) {
    return this.sockets.in(room);
  }

  /**
   * Excludes a room when emitting.
   *
-   * @param name
-   * @return self
-   * @public
+   * @example
+   * // the "foo" event will be broadcast to all connected clients, except the ones that are in the "room-101" room
+   * io.except("room-101").emit("foo", "bar");
+   *
+   * // with an array of rooms
+   * io.except(["room-101", "room-102"]).emit("foo", "bar");
+   *
+   * // with multiple chained calls
+   * io.except("room-101").except("room-102").emit("foo", "bar");
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public except(
-    name: Room | Room[]
-  ): BroadcastOperator<EmitEvents, SocketData> {
-    return this.sockets.except(name);
+  public except(room: Room | Room[]) {
+    return this.sockets.except(room);
  }

  /**
   * Sends a `message` event to all clients.
   *
+   * This method mimics the WebSocket.send() method.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
+   *
+   * @example
+   * io.send("hello");
+   *
+   * // this is equivalent to
+   * io.emit("message", "hello");
+   *
   * @return self
-   * @public
   */
  public send(...args: EventParams<EmitEvents, "message">): this {
    this.sockets.emit("message", ...args);
@@ -719,10 +784,9 @@ export class Server<
  }

  /**
-   * Sends a `message` event to all clients.
+   * Sends a `message` event to all clients. Alias of {@link send}.
   *
   * @return self
-   * @public
   */
  public write(...args: EventParams<EmitEvents, "message">): this {
    this.sockets.emit("message", ...args);
@@ -730,11 +794,30 @@ export class Server<
  }

  /**
-   * Emit a packet to other Socket.IO servers
+   * Sends a message to the other Socket.IO servers of the cluster.
+   *
+   * @example
+   * io.serverSideEmit("hello", "world");
+   *
+   * io.on("hello", (arg1) => {
+   *   console.log(arg1); // prints "world"
+   * });
+   *
+   * // acknowledgements (without binary content) are supported too:
+   * io.serverSideEmit("ping", (err, responses) => {
+   *  if (err) {
+   *     // some clients did not acknowledge the event in the given delay
+   *   } else {
+   *     console.log(responses); // one response per client
+   *   }
+   * });
+   *
+   * io.on("ping", (cb) => {
+   *   cb("pong");
+   * });
   *
   * @param ev - the event name
   * @param args - an array of arguments, which may include an acknowledgement callback at the end
-   * @public
   */
  public serverSideEmit<Ev extends EventNames<ServerSideEvents>>(
    ev: Ev,
@@ -746,7 +829,8 @@ export class Server<
  /**
   * Gets a list of socket ids.
   *
-   * @public
+   * @deprecated this method will be removed in the next major release, please use {@link Server#serverSideEmit} or
+   * {@link Server#fetchSockets} instead.
   */
  public allSockets(): Promise<Set<SocketId>> {
    return this.sockets.allSockets();
@@ -755,13 +839,13 @@ export class Server<
  /**
   * Sets the compress flag.
   *
+   * @example
+   * io.compress(false).emit("hello");
+   *
   * @param compress - if `true`, compresses the sending data
-   * @return self
-   * @public
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public compress(
-    compress: boolean
-  ): BroadcastOperator<EmitEvents, SocketData> {
+  public compress(compress: boolean) {
    return this.sockets.compress(compress);
  }

@@ -770,34 +854,40 @@ export class Server<
   * receive messages (because of network slowness or other issues, or because they’re connected through long polling
   * and is in the middle of a request-response cycle).
   *
-   * @return self
-   * @public
+   * @example
+   * io.volatile.emit("hello"); // the clients may or may not receive it
+   *
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public get volatile(): BroadcastOperator<EmitEvents, SocketData> {
+  public get volatile() {
    return this.sockets.volatile;
  }

  /**
   * Sets a modifier for a subsequent event emission that the event data will only be broadcast to the current node.
   *
-   * @return self
-   * @public
+   * @example
+   * // the “foo” event will be broadcast to all connected clients on this node
+   * io.local.emit("foo", "bar");
+   *
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public get local(): BroadcastOperator<EmitEvents, SocketData> {
+  public get local() {
    return this.sockets.local;
  }

  /**
-   * Adds a timeout in milliseconds for the next operation
-   *
-   * <pre><code>
+   * Adds a timeout in milliseconds for the next operation.
   *
+   * @example
   * io.timeout(1000).emit("some-event", (err, responses) => {
-   *   // ...
+   *   if (err) {
+   *     // some clients did not acknowledge the event in the given delay
+   *   } else {
+   *     console.log(responses); // one response per client
+   *   }
   * });
   *
-   * </pre></code>
-   *
   * @param timeout
   */
  public timeout(timeout: number) {
@@ -805,41 +895,85 @@ export class Server<
  }

  /**
-   * Returns the matching socket instances
+   * Returns the matching socket instances.
   *
-   * @public
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   * // return all Socket instances
+   * const sockets = await io.fetchSockets();
+   *
+   * // return all Socket instances in the "room1" room
+   * const sockets = await io.in("room1").fetchSockets();
+   *
+   * for (const socket of sockets) {
+   *   console.log(socket.id);
+   *   console.log(socket.handshake);
+   *   console.log(socket.rooms);
+   *   console.log(socket.data);
+   *
+   *   socket.emit("hello");
+   *   socket.join("room1");
+   *   socket.leave("room2");
+   *   socket.disconnect();
+   * }
   */
  public fetchSockets(): Promise<RemoteSocket<EmitEvents, SocketData>[]> {
    return this.sockets.fetchSockets();
  }

  /**
-   * Makes the matching socket instances join the specified rooms
+   * Makes the matching socket instances join the specified rooms.
   *
-   * @param room
-   * @public
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   *
+   * // make all socket instances join the "room1" room
+   * io.socketsJoin("room1");
+   *
+   * // make all socket instances in the "room1" room join the "room2" and "room3" rooms
+   * io.in("room1").socketsJoin(["room2", "room3"]);
+   *
+   * @param room - a room, or an array of rooms
   */
-  public socketsJoin(room: Room | Room[]): void {
+  public socketsJoin(room: Room | Room[]) {
    return this.sockets.socketsJoin(room);
  }

  /**
-   * Makes the matching socket instances leave the specified rooms
+   * Makes the matching socket instances leave the specified rooms.
   *
-   * @param room
-   * @public
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   * // make all socket instances leave the "room1" room
+   * io.socketsLeave("room1");
+   *
+   * // make all socket instances in the "room1" room leave the "room2" and "room3" rooms
+   * io.in("room1").socketsLeave(["room2", "room3"]);
+   *
+   * @param room - a room, or an array of rooms
   */
-  public socketsLeave(room: Room | Room[]): void {
+  public socketsLeave(room: Room | Room[]) {
    return this.sockets.socketsLeave(room);
  }

  /**
-   * Makes the matching socket instances disconnect
+   * Makes the matching socket instances disconnect.
+   *
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   * // make all socket instances disconnect (the connections might be kept alive for other namespaces)
+   * io.disconnectSockets();
+   *
+   * // make all socket instances in the "room1" room disconnect and close the underlying connections
+   * io.in("room1").disconnectSockets(true);
   *
   * @param close - whether to close the underlying connection
-   * @public
   */
-  public disconnectSockets(close: boolean = false): void {
+  public disconnectSockets(close: boolean = false) {
    return this.sockets.disconnectSockets(close);
  }
 }
--- a/lib/namespace.ts
+++ b/lib/namespace.ts
@@ -52,6 +52,59 @@ export const RESERVED_EVENTS: ReadonlySet<string | Symbol> = new Set<
  keyof ServerReservedEventsMap<never, never, never, never>
 >(<const>["connect", "connection", "new_namespace"]);

+/**
+ * A Namespace is a communication channel that allows you to split the logic of your application over a single shared
+ * connection.
+ *
+ * Each namespace has its own:
+ *
+ * - event handlers
+ *
+ * ```
+ * io.of("/orders").on("connection", (socket) => {
+ *   socket.on("order:list", () => {});
+ *   socket.on("order:create", () => {});
+ * });
+ *
+ * io.of("/users").on("connection", (socket) => {
+ *   socket.on("user:list", () => {});
+ * });
+ * ```
+ *
+ * - rooms
+ *
+ * ```
+ * const orderNamespace = io.of("/orders");
+ *
+ * orderNamespace.on("connection", (socket) => {
+ *   socket.join("room1");
+ *   orderNamespace.to("room1").emit("hello");
+ * });
+ *
+ * const userNamespace = io.of("/users");
+ *
+ * userNamespace.on("connection", (socket) => {
+ *   socket.join("room1"); // distinct from the room in the "orders" namespace
+ *   userNamespace.to("room1").emit("holà");
+ * });
+ * ```
+ *
+ * - middlewares
+ *
+ * ```
+ * const orderNamespace = io.of("/orders");
+ *
+ * orderNamespace.use((socket, next) => {
+ *   // ensure the socket has access to the "orders" namespace
+ * });
+ *
+ * const userNamespace = io.of("/users");
+ *
+ * userNamespace.use((socket, next) => {
+ *   // ensure the socket has access to the "users" namespace
+ * });
+ * ```
+ */
 export class Namespace<
  ListenEvents extends EventsMap = DefaultEventsMap,
  EmitEvents extends EventsMap = ListenEvents,
@@ -123,10 +176,17 @@ export class Namespace<
  }

  /**
-   * Sets up namespace middleware.
+   * Registers a middleware, which is a function that gets executed for every incoming {@link Socket}.
   *
-   * @return self
-   * @public
+   * @example
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * myNamespace.use((socket, next) => {
+   *   // ...
+   *   next();
+   * });
+   *
+   * @param fn - the middleware function
   */
  public use(
    fn: (
@@ -171,36 +231,63 @@ export class Namespace<
  /**
   * Targets a room when emitting.
   *
-   * @param room
-   * @return self
-   * @public
+   * @example
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * // the “foo” event will be broadcast to all connected clients in the “room-101” room
+   * myNamespace.to("room-101").emit("foo", "bar");
+   *
+   * // with an array of rooms (a client will be notified at most once)
+   * myNamespace.to(["room-101", "room-102"]).emit("foo", "bar");
+   *
+   * // with multiple chained calls
+   * myNamespace.to("room-101").to("room-102").emit("foo", "bar");
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public to(room: Room | Room[]): BroadcastOperator<EmitEvents, SocketData> {
-    return new BroadcastOperator(this.adapter).to(room);
+  public to(room: Room | Room[]) {
+    return new BroadcastOperator<EmitEvents, SocketData>(this.adapter).to(room);
  }

  /**
-   * Targets a room when emitting.
+   * Targets a room when emitting. Similar to `to()`, but might feel clearer in some cases:
   *
-   * @param room
-   * @return self
-   * @public
+   * @example
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * // disconnect all clients in the "room-101" room
+   * myNamespace.in("room-101").disconnectSockets();
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public in(room: Room | Room[]): BroadcastOperator<EmitEvents, SocketData> {
-    return new BroadcastOperator(this.adapter).in(room);
+  public in(room: Room | Room[]) {
+    return new BroadcastOperator<EmitEvents, SocketData>(this.adapter).in(room);
  }

  /**
   * Excludes a room when emitting.
   *
-   * @param room
-   * @return self
-   * @public
+   * @example
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * // the "foo" event will be broadcast to all connected clients, except the ones that are in the "room-101" room
+   * myNamespace.except("room-101").emit("foo", "bar");
+   *
+   * // with an array of rooms
+   * myNamespace.except(["room-101", "room-102"]).emit("foo", "bar");
+   *
+   * // with multiple chained calls
+   * myNamespace.except("room-101").except("room-102").emit("foo", "bar");
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public except(
-    room: Room | Room[]
-  ): BroadcastOperator<EmitEvents, SocketData> {
-    return new BroadcastOperator(this.adapter).except(room);
+  public except(room: Room | Room[]) {
+    return new BroadcastOperator<EmitEvents, SocketData>(this.adapter).except(
+      room
+    );
  }

  /**
@@ -271,10 +358,26 @@ export class Namespace<
  }

  /**
-   * Emits to all clients.
+   * Emits to all connected clients.
+   *
+   * @example
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * myNamespace.emit("hello", "world");
+   *
+   * // all serializable datastructures are supported (no need to call JSON.stringify)
+   * myNamespace.emit("hello", 1, "2", { 3: ["4"], 5: Uint8Array.from([6]) });
+   *
+   * // with an acknowledgement from the clients
+   * myNamespace.timeout(1000).emit("some-event", (err, responses) => {
+   *   if (err) {
+   *     // some clients did not acknowledge the event in the given delay
+   *   } else {
+   *     console.log(responses); // one response per client
+   *   }
+   * });
   *
   * @return Always true
-   * @public
   */
  public emit<Ev extends EventNames<EmitEvents>>(
    ev: Ev,
@@ -289,8 +392,19 @@ export class Namespace<
  /**
   * Sends a `message` event to all clients.
   *
+   * This method mimics the WebSocket.send() method.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
+   *
+   * @example
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * myNamespace.send("hello");
+   *
+   * // this is equivalent to
+   * myNamespace.emit("message", "hello");
+   *
   * @return self
-   * @public
   */
  public send(...args: EventParams<EmitEvents, "message">): this {
    this.emit("message", ...args);
@@ -298,10 +412,9 @@ export class Namespace<
  }

  /**
-   * Sends a `message` event to all clients.
+   * Sends a `message` event to all clients. Sends a `message` event. Alias of {@link send}.
   *
   * @return self
-   * @public
   */
  public write(...args: EventParams<EmitEvents, "message">): this {
    this.emit("message", ...args);
@@ -309,11 +422,32 @@ export class Namespace<
  }

  /**
-   * Emit a packet to other Socket.IO servers
+   * Sends a message to the other Socket.IO servers of the cluster.
+   *
+   * @example
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * myNamespace.serverSideEmit("hello", "world");
+   *
+   * myNamespace.on("hello", (arg1) => {
+   *   console.log(arg1); // prints "world"
+   * });
+   *
+   * // acknowledgements (without binary content) are supported too:
+   * myNamespace.serverSideEmit("ping", (err, responses) => {
+   *  if (err) {
+   *     // some clients did not acknowledge the event in the given delay
+   *   } else {
+   *     console.log(responses); // one response per client
+   *   }
+   * });
+   *
+   * myNamespace.on("ping", (cb) => {
+   *   cb("pong");
+   * });
   *
   * @param ev - the event name
   * @param args - an array of arguments, which may include an acknowledgement callback at the end
-   * @public
   */
  public serverSideEmit<Ev extends EventNames<ServerSideEvents>>(
    ev: Ev,
@@ -341,24 +475,30 @@ export class Namespace<
  /**
   * Gets a list of clients.
   *
-   * @return self
-   * @public
+   * @deprecated this method will be removed in the next major release, please use {@link Namespace#serverSideEmit} or
+   * {@link Namespace#fetchSockets} instead.
   */
  public allSockets(): Promise<Set<SocketId>> {
-    return new BroadcastOperator(this.adapter).allSockets();
+    return new BroadcastOperator<EmitEvents, SocketData>(
+      this.adapter
+    ).allSockets();
  }

  /**
   * Sets the compress flag.
   *
+   * @example
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * myNamespace.compress(false).emit("hello");
+   *
   * @param compress - if `true`, compresses the sending data
   * @return self
-   * @public
   */
-  public compress(
-    compress: boolean
-  ): BroadcastOperator<EmitEvents, SocketData> {
-    return new BroadcastOperator(this.adapter).compress(compress);
+  public compress(compress: boolean) {
+    return new BroadcastOperator<EmitEvents, SocketData>(this.adapter).compress(
+      compress
+    );
  }

  /**
@@ -366,76 +506,149 @@ export class Namespace<
   * receive messages (because of network slowness or other issues, or because they’re connected through long polling
   * and is in the middle of a request-response cycle).
   *
+   * @example
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * myNamespace.volatile.emit("hello"); // the clients may or may not receive it
+   *
   * @return self
-   * @public
   */
-  public get volatile(): BroadcastOperator<EmitEvents, SocketData> {
-    return new BroadcastOperator(this.adapter).volatile;
+  public get volatile() {
+    return new BroadcastOperator<EmitEvents, SocketData>(this.adapter).volatile;
  }

  /**
   * Sets a modifier for a subsequent event emission that the event data will only be broadcast to the current node.
   *
-   * @return self
-   * @public
+   * @example
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * // the “foo” event will be broadcast to all connected clients on this node
+   * myNamespace.local.emit("foo", "bar");
+   *
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public get local(): BroadcastOperator<EmitEvents, SocketData> {
-    return new BroadcastOperator(this.adapter).local;
+  public get local() {
+    return new BroadcastOperator<EmitEvents, SocketData>(this.adapter).local;
  }

  /**
-   * Adds a timeout in milliseconds for the next operation
+   * Adds a timeout in milliseconds for the next operation.
   *
-   * <pre><code>
+   * @example
+   * const myNamespace = io.of("/my-namespace");
   *
-   * io.timeout(1000).emit("some-event", (err, responses) => {
-   *   // ...
+   * myNamespace.timeout(1000).emit("some-event", (err, responses) => {
+   *   if (err) {
+   *     // some clients did not acknowledge the event in the given delay
+   *   } else {
+   *     console.log(responses); // one response per client
+   *   }
   * });
   *
-   * </pre></code>
-   *
   * @param timeout
   */
  public timeout(timeout: number) {
-    return new BroadcastOperator(this.adapter).timeout(timeout);
+    return new BroadcastOperator<EmitEvents, SocketData>(this.adapter).timeout(
+      timeout
+    );
  }

  /**
-   * Returns the matching socket instances
+   * Returns the matching socket instances.
   *
-   * @public
-   */
-  public fetchSockets(): Promise<RemoteSocket<EmitEvents, SocketData>[]> {
-    return new BroadcastOperator(this.adapter).fetchSockets();
-  }
-
-  /**
-   * Makes the matching socket instances join the specified rooms
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
   *
-   * @param room
-   * @public
-   */
-  public socketsJoin(room: Room | Room[]): void {
-    return new BroadcastOperator(this.adapter).socketsJoin(room);
-  }
-
-  /**
-   * Makes the matching socket instances leave the specified rooms
+   * @example
+   * const myNamespace = io.of("/my-namespace");
   *
-   * @param room
-   * @public
+   * // return all Socket instances
+   * const sockets = await myNamespace.fetchSockets();
+   *
+   * // return all Socket instances in the "room1" room
+   * const sockets = await myNamespace.in("room1").fetchSockets();
+   *
+   * for (const socket of sockets) {
+   *   console.log(socket.id);
+   *   console.log(socket.handshake);
+   *   console.log(socket.rooms);
+   *   console.log(socket.data);
+   *
+   *   socket.emit("hello");
+   *   socket.join("room1");
+   *   socket.leave("room2");
+   *   socket.disconnect();
+   * }
   */
-  public socketsLeave(room: Room | Room[]): void {
-    return new BroadcastOperator(this.adapter).socketsLeave(room);
+  public fetchSockets() {
+    return new BroadcastOperator<EmitEvents, SocketData>(
+      this.adapter
+    ).fetchSockets();
  }

  /**
-   * Makes the matching socket instances disconnect
+   * Makes the matching socket instances join the specified rooms.
+   *
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * // make all socket instances join the "room1" room
+   * myNamespace.socketsJoin("room1");
+   *
+   * // make all socket instances in the "room1" room join the "room2" and "room3" rooms
+   * myNamespace.in("room1").socketsJoin(["room2", "room3"]);
+   *
+   * @param room - a room, or an array of rooms
+   */
+  public socketsJoin(room: Room | Room[]) {
+    return new BroadcastOperator<EmitEvents, SocketData>(
+      this.adapter
+    ).socketsJoin(room);
+  }
+
+  /**
+   * Makes the matching socket instances leave the specified rooms.
+   *
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * // make all socket instances leave the "room1" room
+   * myNamespace.socketsLeave("room1");
+   *
+   * // make all socket instances in the "room1" room leave the "room2" and "room3" rooms
+   * myNamespace.in("room1").socketsLeave(["room2", "room3"]);
+   *
+   * @param room - a room, or an array of rooms
+   */
+  public socketsLeave(room: Room | Room[]) {
+    return new BroadcastOperator<EmitEvents, SocketData>(
+      this.adapter
+    ).socketsLeave(room);
+  }
+
+  /**
+   * Makes the matching socket instances disconnect.
+   *
+   * Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible {@link Adapter}.
+   *
+   * @example
+   * const myNamespace = io.of("/my-namespace");
+   *
+   * // make all socket instances disconnect (the connections might be kept alive for other namespaces)
+   * myNamespace.disconnectSockets();
+   *
+   * // make all socket instances in the "room1" room disconnect and close the underlying connections
+   * myNamespace.in("room1").disconnectSockets(true);
   *
   * @param close - whether to close the underlying connection
-   * @public
   */
-  public disconnectSockets(close: boolean = false): void {
-    return new BroadcastOperator(this.adapter).disconnectSockets(close);
+  public disconnectSockets(close: boolean = false) {
+    return new BroadcastOperator<EmitEvents, SocketData>(
+      this.adapter
+    ).disconnectSockets(close);
  }
 }
--- a/lib/socket.ts
+++ b/lib/socket.ts
@@ -25,9 +25,23 @@ const debug = debugModule("socket.io:socket");

 type ClientReservedEvents = "connect_error";

+// TODO for next major release: cleanup disconnect reasons
+export type DisconnectReason =
+  // Engine.IO close reasons
+  | "transport error"
+  | "transport close"
+  | "forced close"
+  | "ping timeout"
+  | "parse error"
+  // Socket.IO disconnect reasons
+  | "server shutting down"
+  | "forced server close"
+  | "client namespace disconnect"
+  | "server namespace disconnect";
+
 export interface SocketReservedEventsMap {
-  disconnect: (reason: string) => void;
-  disconnecting: (reason: string) => void;
+  disconnect: (reason: DisconnectReason) => void;
+  disconnecting: (reason: DisconnectReason) => void;
  error: (err: Error) => void;
 }

@@ -114,6 +128,37 @@ export type Event = [string, ...any[]];

 function noop() {}

+/**
+ * This is the main object for interacting with a client.
+ *
+ * A Socket belongs to a given {@link Namespace} and uses an underlying {@link Client} to communicate.
+ *
+ * Within each {@link Namespace}, you can also define arbitrary channels (called "rooms") that the {@link Socket} can
+ * join and leave. That provides a convenient way to broadcast to a group of socket instances.
+ *
+ * @example
+ * io.on("connection", (socket) => {
+ *   console.log(`socket ${socket.id} connected`);
+ *
+ *   // send an event to the client
+ *   socket.emit("foo", "bar");
+ *
+ *   socket.on("foobar", () => {
+ *     // an event was received from the client
+ *   });
+ *
+ *   // join the room named "room1"
+ *   socket.join("room1");
+ *
+ *   // broadcast to everyone in the room named "room1"
+ *   io.to("room1").emit("hello");
+ *
+ *   // upon disconnection
+ *   socket.on("disconnect", (reason) => {
+ *     console.log(`socket ${socket.id} disconnected due to ${reason}`);
+ *   });
+ * });
+ */
 export class Socket<
  ListenEvents extends EventsMap = DefaultEventsMap,
  EmitEvents extends EventsMap = ListenEvents,
@@ -124,13 +169,32 @@ export class Socket<
  EmitEvents,
  SocketReservedEventsMap
 > {
+  /**
+   * An unique identifier for the session.
+   */
  public readonly id: SocketId;
+  /**
+   * The handshake details.
+   */
  public readonly handshake: Handshake;
  /**
-   * Additional information that can be attached to the Socket instance and which will be used in the fetchSockets method
+   * Additional information that can be attached to the Socket instance and which will be used in the
+   * {@link Server.fetchSockets()} method.
   */
  public data: Partial<SocketData> = {};
-
+  /**
+   * Whether the socket is currently connected or not.
+   *
+   * @example
+   * io.use((socket, next) => {
+   *   console.log(socket.connected); // false
+   *   next();
+   * });
+   *
+   * io.on("connection", (socket) => {
+   *   console.log(socket.connected); // true
+   * });
+   */
  public connected: boolean = false;

  private readonly server: Server<
@@ -195,8 +259,20 @@ export class Socket<
  /**
   * Emits to this client.
   *
+   * @example
+   * io.on("connection", (socket) => {
+   *   socket.emit("hello", "world");
+   *
+   *   // all serializable datastructures are supported (no need to call JSON.stringify)
+   *   socket.emit("hello", 1, "2", { 3: ["4"], 5: Buffer.from([6]) });
+   *
+   *   // with an acknowledgement from the client
+   *   socket.emit("hello", "world", (val) => {
+   *     // ...
+   *   });
+   * });
+   *
   * @return Always returns `true`.
-   * @public
   */
  public emit<Ev extends EventNames<EmitEvents>>(
    ev: Ev,
@@ -254,43 +330,83 @@ export class Socket<
  /**
   * Targets a room when broadcasting.
   *
-   * @param room
-   * @return self
-   * @public
+   * @example
+   * io.on("connection", (socket) => {
+   *   // the “foo” event will be broadcast to all connected clients in the “room-101” room, except this socket
+   *   socket.to("room-101").emit("foo", "bar");
+   *
+   *   // the code above is equivalent to:
+   *   io.to("room-101").except(socket.id).emit("foo", "bar");
+   *
+   *   // with an array of rooms (a client will be notified at most once)
+   *   socket.to(["room-101", "room-102"]).emit("foo", "bar");
+   *
+   *   // with multiple chained calls
+   *   socket.to("room-101").to("room-102").emit("foo", "bar");
+   * });
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public to(room: Room | Room[]): BroadcastOperator<EmitEvents, SocketData> {
+  public to(room: Room | Room[]) {
    return this.newBroadcastOperator().to(room);
  }

  /**
-   * Targets a room when broadcasting.
+   * Targets a room when broadcasting. Similar to `to()`, but might feel clearer in some cases:
   *
-   * @param room
-   * @return self
-   * @public
+   * @example
+   * io.on("connection", (socket) => {
+   *   // disconnect all clients in the "room-101" room, except this socket
+   *   socket.in("room-101").disconnectSockets();
+   * });
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public in(room: Room | Room[]): BroadcastOperator<EmitEvents, SocketData> {
+  public in(room: Room | Room[]) {
    return this.newBroadcastOperator().in(room);
  }

  /**
   * Excludes a room when broadcasting.
   *
-   * @param room
-   * @return self
-   * @public
+   * @example
+   * io.on("connection", (socket) => {
+   *   // the "foo" event will be broadcast to all connected clients, except the ones that are in the "room-101" room
+   *   // and this socket
+   *   socket.except("room-101").emit("foo", "bar");
+   *
+   *   // with an array of rooms
+   *   socket.except(["room-101", "room-102"]).emit("foo", "bar");
+   *
+   *   // with multiple chained calls
+   *   socket.except("room-101").except("room-102").emit("foo", "bar");
+   * });
+   *
+   * @param room - a room, or an array of rooms
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public except(
-    room: Room | Room[]
-  ): BroadcastOperator<EmitEvents, SocketData> {
+  public except(room: Room | Room[]) {
    return this.newBroadcastOperator().except(room);
  }

  /**
   * Sends a `message` event.
   *
+   * This method mimics the WebSocket.send() method.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
+   *
+   * @example
+   * io.on("connection", (socket) => {
+   *   socket.send("hello");
+   *
+   *   // this is equivalent to
+   *   socket.emit("message", "hello");
+   * });
+   *
   * @return self
-   * @public
   */
  public send(...args: EventParams<EmitEvents, "message">): this {
    this.emit("message", ...args);
@@ -298,10 +414,9 @@ export class Socket<
  }

  /**
-   * Sends a `message` event.
+   * Sends a `message` event. Alias of {@link send}.
   *
   * @return self
-   * @public
   */
  public write(...args: EventParams<EmitEvents, "message">): this {
    this.emit("message", ...args);
@@ -327,9 +442,17 @@ export class Socket<
  /**
   * Joins a room.
   *
+   * @example
+   * io.on("connection", (socket) => {
+   *   // join a single room
+   *   socket.join("room1");
+   *
+   *   // join multiple rooms
+   *   socket.join(["room1", "room2"]);
+   * });
+   *
   * @param {String|Array} rooms - room or array of rooms
   * @return a Promise or nothing, depending on the adapter
-   * @public
   */
  public join(rooms: Room | Array<Room>): Promise<void> | void {
    debug("join room %s", rooms);
@@ -343,9 +466,17 @@ export class Socket<
  /**
   * Leaves a room.
   *
+   * @example
+   * io.on("connection", (socket) => {
+   *   // leave a single room
+   *   socket.leave("room1");
+   *
+   *   // leave multiple rooms
+   *   socket.leave("room1").leave("room2");
+   * });
+   *
   * @param {String} room
   * @return a Promise or nothing, depending on the adapter
-   * @public
   */
  public leave(room: string): Promise<void> | void {
    debug("leave room %s", room);
@@ -509,7 +640,7 @@ export class Socket<
   *
   * @private
   */
-  _onclose(reason: string): this | undefined {
+  _onclose(reason: DisconnectReason): this | undefined {
    if (!this.connected) return this;
    debug("closing socket - reason %s", reason);
    this.emitReserved("disconnecting", reason);
@@ -545,10 +676,17 @@ export class Socket<
  /**
   * Disconnects this client.
   *
-   * @param {Boolean} close - if `true`, closes the underlying connection
-   * @return {Socket} self
+   * @example
+   * io.on("connection", (socket) => {
+   *   // disconnect this socket (the connection might be kept alive for other namespaces)
+   *   socket.disconnect();
   *
-   * @public
+   *   // disconnect this socket and close the underlying connection
+   *   socket.disconnect(true);
+   * })
+   *
+   * @param {Boolean} close - if `true`, closes the underlying connection
+   * @return self
   */
  public disconnect(close = false): this {
    if (!this.connected) return this;
@@ -564,9 +702,13 @@ export class Socket<
  /**
   * Sets the compress flag.
   *
+   * @example
+   * io.on("connection", (socket) => {
+   *   socket.compress(false).emit("hello");
+   * });
+   *
   * @param {Boolean} compress - if `true`, compresses the sending data
   * @return {Socket} self
-   * @public
   */
  public compress(compress: boolean): this {
    this.flags.compress = compress;
@@ -578,8 +720,12 @@ export class Socket<
   * receive messages (because of network slowness or other issues, or because they’re connected through long polling
   * and is in the middle of a request-response cycle).
   *
+   * @example
+   * io.on("connection", (socket) => {
+   *   socket.volatile.emit("hello"); // the client may or may not receive it
+   * });
+   *
   * @return {Socket} self
-   * @public
   */
  public get volatile(): this {
    this.flags.volatile = true;
@@ -590,20 +736,30 @@ export class Socket<
   * Sets a modifier for a subsequent event emission that the event data will only be broadcast to every sockets but the
   * sender.
   *
-   * @return {Socket} self
-   * @public
+   * @example
+   * io.on("connection", (socket) => {
+   *   // the “foo” event will be broadcast to all connected clients, except this socket
+   *   socket.broadcast.emit("foo", "bar");
+   * });
+   *
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public get broadcast(): BroadcastOperator<EmitEvents, SocketData> {
+  public get broadcast() {
    return this.newBroadcastOperator();
  }

  /**
   * Sets a modifier for a subsequent event emission that the event data will only be broadcast to the current node.
   *
-   * @return {Socket} self
-   * @public
+   * @example
+   * io.on("connection", (socket) => {
+   *   // the “foo” event will be broadcast to all connected clients on this node, except this socket
+   *   socket.local.emit("foo", "bar");
+   * });
+   *
+   * @return a new {@link BroadcastOperator} instance for chaining
   */
-  public get local(): BroadcastOperator<EmitEvents, SocketData> {
+  public get local() {
    return this.newBroadcastOperator().local;
  }

@@ -611,16 +767,16 @@ export class Socket<
   * Sets a modifier for a subsequent event emission that the callback will be called with an error when the
   * given number of milliseconds have elapsed without an acknowledgement from the client:
   *
-   * ```
-   * socket.timeout(5000).emit("my-event", (err) => {
-   *   if (err) {
-   *     // the client did not acknowledge the event in the given delay
-   *   }
+   * @example
+   * io.on("connection", (socket) => {
+   *   socket.timeout(5000).emit("my-event", (err) => {
+   *     if (err) {
+   *       // the client did not acknowledge the event in the given delay
+   *     }
+   *   });
   * });
-   * ```
   *
   * @returns self
-   * @public
   */
  public timeout(timeout: number): this {
    this.flags.timeout = timeout;
@@ -652,9 +808,25 @@ export class Socket<
  /**
   * Sets up socket middleware.
   *
+   * @example
+   * io.on("connection", (socket) => {
+   *   socket.use(([event, ...args], next) => {
+   *     if (isUnauthorized(event)) {
+   *       return next(new Error("unauthorized event"));
+   *     }
+   *     // do not forget to call next
+   *     next();
+   *   });
+   *
+   *   socket.on("error", (err) => {
+   *     if (err && err.message === "unauthorized event") {
+   *       socket.disconnect();
+   *     }
+   *   });
+   * });
+   *
   * @param {Function} fn - middleware function (event, next)
   * @return {Socket} self
-   * @public
   */
  public use(fn: (event: Event, next: (err?: Error) => void) => void): this {
    this.fns.push(fn);
@@ -697,8 +869,6 @@ export class Socket<

  /**
   * A reference to the request that originated the underlying Engine.IO Socket.
-   *
-   * @public
   */
  public get request(): IncomingMessage {
    return this.client.request;
@@ -707,14 +877,30 @@ export class Socket<
  /**
   * A reference to the underlying Client transport connection (Engine.IO Socket object).
   *
-   * @public
+   * @example
+   * io.on("connection", (socket) => {
+   *   console.log(socket.conn.transport.name); // prints "polling" or "websocket"
+   *
+   *   socket.conn.once("upgrade", () => {
+   *     console.log(socket.conn.transport.name); // prints "websocket"
+   *   });
+   * });
   */
  public get conn() {
    return this.client.conn;
  }

  /**
-   * @public
+   * Returns the rooms the socket is currently in.
+   *
+   * @example
+   * io.on("connection", (socket) => {
+   *   console.log(socket.rooms); // Set { <socket.id> }
+   *
+   *   socket.join("room1");
+   *
+   *   console.log(socket.rooms); // Set { <socket.id>, "room1" }
+   * });
   */
  public get rooms(): Set<Room> {
    return this.adapter.socketRooms(this.id) || new Set();
@@ -724,8 +910,14 @@ export class Socket<
   * Adds a listener that will be fired when any event is received. The event name is passed as the first argument to
   * the callback.
   *
+   * @example
+   * io.on("connection", (socket) => {
+   *   socket.onAny((event, ...args) => {
+   *     console.log(`got event ${event}`);
+   *   });
+   * });
+   *
   * @param listener
-   * @public
   */
  public onAny(listener: (...args: any[]) => void): this {
    this._anyListeners = this._anyListeners || [];
@@ -738,7 +930,6 @@ export class Socket<
   * the callback. The listener is added to the beginning of the listeners array.
   *
   * @param listener
-   * @public
   */
  public prependAny(listener: (...args: any[]) => void): this {
    this._anyListeners = this._anyListeners || [];
@@ -749,8 +940,22 @@ export class Socket<
  /**
   * Removes the listener that will be fired when any event is received.
   *
+   * @example
+   * io.on("connection", (socket) => {
+   *   const catchAllListener = (event, ...args) => {
+   *     console.log(`got event ${event}`);
+   *   }
+   *
+   *   socket.onAny(catchAllListener);
+   *
+   *   // remove a specific listener
+   *   socket.offAny(catchAllListener);
+   *
+   *   // or remove all listeners
+   *   socket.offAny();
+   * });
+   *
   * @param listener
-   * @public
   */
  public offAny(listener?: (...args: any[]) => void): this {
    if (!this._anyListeners) {
@@ -773,28 +978,25 @@ export class Socket<
  /**
   * Returns an array of listeners that are listening for any event that is specified. This array can be manipulated,
   * e.g. to remove listeners.
-   *
-   * @public
   */
  public listenersAny() {
    return this._anyListeners || [];
  }

  /**
-   * Adds a listener that will be fired when any event is emitted. The event name is passed as the first argument to the
-   * callback.
+   * Adds a listener that will be fired when any event is sent. The event name is passed as the first argument to
+   * the callback.
   *
-   * @param listener
+   * Note: acknowledgements sent to the client are not included.
   *
-   * <pre><code>
-   *
-   * socket.onAnyOutgoing((event, ...args) => {
-   *   console.log(event);
+   * @example
+   * io.on("connection", (socket) => {
+   *   socket.onAnyOutgoing((event, ...args) => {
+   *     console.log(`sent event ${event}`);
+   *   });
   * });
   *
-   * </pre></code>
-   *
-   * @public
+   * @param listener
   */
  public onAnyOutgoing(listener: (...args: any[]) => void): this {
    this._anyOutgoingListeners = this._anyOutgoingListeners || [];
@@ -806,17 +1008,14 @@ export class Socket<
   * Adds a listener that will be fired when any event is emitted. The event name is passed as the first argument to the
   * callback. The listener is added to the beginning of the listeners array.
   *
-   * @param listener
-   *
-   * <pre><code>
-   *
-   * socket.prependAnyOutgoing((event, ...args) => {
-   *   console.log(event);
+   * @example
+   * io.on("connection", (socket) => {
+   *   socket.prependAnyOutgoing((event, ...args) => {
+   *     console.log(`sent event ${event}`);
+   *   });
   * });
   *
-   * </pre></code>
-   *
-   * @public
+   * @param listener
   */
  public prependAnyOutgoing(listener: (...args: any[]) => void): this {
    this._anyOutgoingListeners = this._anyOutgoingListeners || [];
@@ -825,24 +1024,24 @@ export class Socket<
  }

  /**
-   * Removes the listener that will be fired when any event is emitted.
+   * Removes the listener that will be fired when any event is sent.
   *
-   * @param listener
+   * @example
+   * io.on("connection", (socket) => {
+   *   const catchAllListener = (event, ...args) => {
+   *     console.log(`sent event ${event}`);
+   *   }
   *
-   * <pre><code>
+   *   socket.onAnyOutgoing(catchAllListener);
   *
-   * const handler = (event, ...args) => {
-   *   console.log(event);
-   * }
+   *   // remove a specific listener
+   *   socket.offAnyOutgoing(catchAllListener);
   *
-   * socket.onAnyOutgoing(handler);
+   *   // or remove all listeners
+   *   socket.offAnyOutgoing();
+   * });
   *
-   * // then later
-   * socket.offAnyOutgoing(handler);
-   *
-   * </pre></code>
-   *
-   * @public
+   * @param listener - the catch-all listener
   */
  public offAnyOutgoing(listener?: (...args: any[]) => void): this {
    if (!this._anyOutgoingListeners) {
@@ -865,8 +1064,6 @@ export class Socket<
  /**
   * Returns an array of listeners that are listening for any event that is specified. This array can be manipulated,
   * e.g. to remove listeners.
-   *
-   * @public
   */
  public listenersAnyOutgoing() {
    return this._anyOutgoingListeners || [];
@@ -888,10 +1085,10 @@ export class Socket<
    }
  }

-  private newBroadcastOperator(): BroadcastOperator<EmitEvents, SocketData> {
+  private newBroadcastOperator() {
    const flags = Object.assign({}, this.flags);
    this.flags = {};
-    return new BroadcastOperator(
+    return new BroadcastOperator<EmitEvents, SocketData>(
      this.adapter,
      new Set<Room>(),
      new Set<Room>([this.id]),
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,20 +1,20 @@
 {
  "name": "socket.io",
-  "version": "4.5.2",
+  "version": "4.5.3",
  "lockfileVersion": 2,
  "requires": true,
  "packages": {
    "": {
      "name": "socket.io",
-      "version": "4.5.2",
+      "version": "4.5.3",
      "license": "MIT",
      "dependencies": {
        "accepts": "~1.3.4",
        "base64id": "~2.0.0",
        "debug": "~4.3.2",
-        "engine.io": "~6.2.0",
+        "engine.io": "~6.2.1",
        "socket.io-adapter": "~2.4.0",
-        "socket.io-parser": "~4.2.0"
+        "socket.io-parser": "~4.2.1"
      },
      "devDependencies": {
        "@types/mocha": "^9.0.0",
@@ -23,7 +23,7 @@
        "nyc": "^15.1.0",
        "prettier": "^2.3.2",
        "rimraf": "^3.0.2",
-        "socket.io-client": "4.5.2",
+        "socket.io-client": "4.5.4",
        "socket.io-client-v2": "npm:socket.io-client@^2.4.0",
        "superagent": "^8.0.0",
        "supertest": "^6.1.6",
@@ -1377,9 +1377,9 @@
      "dev": true
    },
    "node_modules/engine.io": {
-      "version": "6.2.0",
-      "resolved": "https://registry.npmjs.org/engine.io/-/engine.io-6.2.0.tgz",
-      "integrity": "sha512-4KzwW3F3bk+KlzSOY57fj/Jx6LyRQ1nbcyIadehl+AnXjKT7gDO0ORdRi/84ixvMKTym6ZKuxvbzN62HDDU1Lg==",
+      "version": "6.2.1",
+      "resolved": "https://registry.npmjs.org/engine.io/-/engine.io-6.2.1.tgz",
+      "integrity": "sha512-ECceEFcAaNRybd3lsGQKas3ZlMVjN3cyWwMP25D2i0zWfyiytVbTpRPa34qrr+FHddtpBVOmq4H/DCv1O0lZRA==",
      "dependencies": {
        "@types/cookie": "^0.4.1",
        "@types/cors": "^2.8.12",
@@ -1397,9 +1397,9 @@
      }
    },
    "node_modules/engine.io-client": {
-      "version": "6.2.2",
-      "resolved": "https://registry.npmjs.org/engine.io-client/-/engine.io-client-6.2.2.tgz",
-      "integrity": "sha512-8ZQmx0LQGRTYkHuogVZuGSpDqYZtCM/nv8zQ68VZ+JkOpazJ7ICdsSpaO6iXwvaU30oFg5QJOJWj8zWqhbKjkQ==",
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/engine.io-client/-/engine.io-client-6.2.3.tgz",
+      "integrity": "sha512-aXPtgF1JS3RuuKcpSrBtimSjYvrbhKW9froICH4s0F3XQWLxsKNxqzG39nnvQZQnva4CMvUK63T7shevxRyYHw==",
      "dev": true,
      "dependencies": {
        "@socket.io/component-emitter": "~3.1.0",
@@ -3472,15 +3472,15 @@
      "integrity": "sha512-W4N+o69rkMEGVuk2D/cvca3uYsvGlMwsySWV447y99gUPghxq42BxqLNMndb+a1mm/5/7NeXVQS7RLa2XyXvYg=="
    },
    "node_modules/socket.io-client": {
-      "version": "4.5.2",
-      "resolved": "https://registry.npmjs.org/socket.io-client/-/socket.io-client-4.5.2.tgz",
-      "integrity": "sha512-naqYfFu7CLDiQ1B7AlLhRXKX3gdeaIMfgigwavDzgJoIUYulc1qHH5+2XflTsXTPY7BlPH5rppJyUjhjrKQKLg==",
+      "version": "4.5.4",
+      "resolved": "https://registry.npmjs.org/socket.io-client/-/socket.io-client-4.5.4.tgz",
+      "integrity": "sha512-ZpKteoA06RzkD32IbqILZ+Cnst4xewU7ZYK12aS1mzHftFFjpoMz69IuhP/nL25pJfao/amoPI527KnuhFm01g==",
      "dev": true,
      "dependencies": {
        "@socket.io/component-emitter": "~3.1.0",
        "debug": "~4.3.2",
-        "engine.io-client": "~6.2.1",
-        "socket.io-parser": "~4.2.0"
+        "engine.io-client": "~6.2.3",
+        "socket.io-parser": "~4.2.1"
      },
      "engines": {
        "node": ">=10.0.0"
@@ -3554,9 +3554,9 @@
      "dev": true
    },
    "node_modules/socket.io-client-v2/node_modules/socket.io-parser": {
-      "version": "3.3.2",
-      "resolved": "https://registry.npmjs.org/socket.io-parser/-/socket.io-parser-3.3.2.tgz",
-      "integrity": "sha512-FJvDBuOALxdCI9qwRrO/Rfp9yfndRtc1jSgVgV8FDraihmSP/MLGD5PEuJrNfjALvcQ+vMDM/33AWOYP/JSjDg==",
+      "version": "3.3.3",
+      "resolved": "https://registry.npmjs.org/socket.io-parser/-/socket.io-parser-3.3.3.tgz",
+      "integrity": "sha512-qOg87q1PMWWTeO01768Yh9ogn7chB9zkKtQnya41Y355S0UmpXgpcrFwAgjYJxu9BdKug5r5e9YtVSeWhKBUZg==",
      "dev": true,
      "dependencies": {
        "component-emitter": "~1.3.0",
@@ -3595,9 +3595,9 @@
      }
    },
    "node_modules/socket.io-parser": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/socket.io-parser/-/socket.io-parser-4.2.0.tgz",
-      "integrity": "sha512-tLfmEwcEwnlQTxFB7jibL/q2+q8dlVQzj4JdRLJ/W/G1+Fu9VSxCx1Lo+n1HvXxKnM//dUuD0xgiA7tQf57Vng==",
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/socket.io-parser/-/socket.io-parser-4.2.1.tgz",
+      "integrity": "sha512-V4GrkLy+HeF1F/en3SpUaM+7XxYXpuMUWLGde1kSSh5nQMN4hLrbPIkD+otwh6q9R6NOQBN4AMaOZ2zVjui82g==",
      "dependencies": {
        "@socket.io/component-emitter": "~3.1.0",
        "debug": "~4.3.1"
@@ -5396,9 +5396,9 @@
      "dev": true
    },
    "engine.io": {
-      "version": "6.2.0",
-      "resolved": "https://registry.npmjs.org/engine.io/-/engine.io-6.2.0.tgz",
-      "integrity": "sha512-4KzwW3F3bk+KlzSOY57fj/Jx6LyRQ1nbcyIadehl+AnXjKT7gDO0ORdRi/84ixvMKTym6ZKuxvbzN62HDDU1Lg==",
+      "version": "6.2.1",
+      "resolved": "https://registry.npmjs.org/engine.io/-/engine.io-6.2.1.tgz",
+      "integrity": "sha512-ECceEFcAaNRybd3lsGQKas3ZlMVjN3cyWwMP25D2i0zWfyiytVbTpRPa34qrr+FHddtpBVOmq4H/DCv1O0lZRA==",
      "requires": {
        "@types/cookie": "^0.4.1",
        "@types/cors": "^2.8.12",
@@ -5413,9 +5413,9 @@
      }
    },
    "engine.io-client": {
-      "version": "6.2.2",
-      "resolved": "https://registry.npmjs.org/engine.io-client/-/engine.io-client-6.2.2.tgz",
-      "integrity": "sha512-8ZQmx0LQGRTYkHuogVZuGSpDqYZtCM/nv8zQ68VZ+JkOpazJ7ICdsSpaO6iXwvaU30oFg5QJOJWj8zWqhbKjkQ==",
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/engine.io-client/-/engine.io-client-6.2.3.tgz",
+      "integrity": "sha512-aXPtgF1JS3RuuKcpSrBtimSjYvrbhKW9froICH4s0F3XQWLxsKNxqzG39nnvQZQnva4CMvUK63T7shevxRyYHw==",
      "dev": true,
      "requires": {
        "@socket.io/component-emitter": "~3.1.0",
@@ -6936,15 +6936,15 @@
      "integrity": "sha512-W4N+o69rkMEGVuk2D/cvca3uYsvGlMwsySWV447y99gUPghxq42BxqLNMndb+a1mm/5/7NeXVQS7RLa2XyXvYg=="
    },
    "socket.io-client": {
-      "version": "4.5.2",
-      "resolved": "https://registry.npmjs.org/socket.io-client/-/socket.io-client-4.5.2.tgz",
-      "integrity": "sha512-naqYfFu7CLDiQ1B7AlLhRXKX3gdeaIMfgigwavDzgJoIUYulc1qHH5+2XflTsXTPY7BlPH5rppJyUjhjrKQKLg==",
+      "version": "4.5.4",
+      "resolved": "https://registry.npmjs.org/socket.io-client/-/socket.io-client-4.5.4.tgz",
+      "integrity": "sha512-ZpKteoA06RzkD32IbqILZ+Cnst4xewU7ZYK12aS1mzHftFFjpoMz69IuhP/nL25pJfao/amoPI527KnuhFm01g==",
      "dev": true,
      "requires": {
        "@socket.io/component-emitter": "~3.1.0",
        "debug": "~4.3.2",
-        "engine.io-client": "~6.2.1",
-        "socket.io-parser": "~4.2.0"
+        "engine.io-client": "~6.2.3",
+        "socket.io-parser": "~4.2.1"
      }
    },
    "socket.io-client-v2": {
@@ -7014,9 +7014,9 @@
          "dev": true
        },
        "socket.io-parser": {
-          "version": "3.3.2",
-          "resolved": "https://registry.npmjs.org/socket.io-parser/-/socket.io-parser-3.3.2.tgz",
-          "integrity": "sha512-FJvDBuOALxdCI9qwRrO/Rfp9yfndRtc1jSgVgV8FDraihmSP/MLGD5PEuJrNfjALvcQ+vMDM/33AWOYP/JSjDg==",
+          "version": "3.3.3",
+          "resolved": "https://registry.npmjs.org/socket.io-parser/-/socket.io-parser-3.3.3.tgz",
+          "integrity": "sha512-qOg87q1PMWWTeO01768Yh9ogn7chB9zkKtQnya41Y355S0UmpXgpcrFwAgjYJxu9BdKug5r5e9YtVSeWhKBUZg==",
          "dev": true,
          "requires": {
            "component-emitter": "~1.3.0",
@@ -7040,9 +7040,9 @@
      }
    },
    "socket.io-parser": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/socket.io-parser/-/socket.io-parser-4.2.0.tgz",
-      "integrity": "sha512-tLfmEwcEwnlQTxFB7jibL/q2+q8dlVQzj4JdRLJ/W/G1+Fu9VSxCx1Lo+n1HvXxKnM//dUuD0xgiA7tQf57Vng==",
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/socket.io-parser/-/socket.io-parser-4.2.1.tgz",
+      "integrity": "sha512-V4GrkLy+HeF1F/en3SpUaM+7XxYXpuMUWLGde1kSSh5nQMN4hLrbPIkD+otwh6q9R6NOQBN4AMaOZ2zVjui82g==",
      "requires": {
        "@socket.io/component-emitter": "~3.1.0",
        "debug": "~4.3.1"
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "socket.io",
-  "version": "4.5.2",
+  "version": "4.5.4",
  "description": "node.js realtime framework server",
  "keywords": [
    "realtime",
@@ -49,9 +49,9 @@
    "accepts": "~1.3.4",
    "base64id": "~2.0.0",
    "debug": "~4.3.2",
-    "engine.io": "~6.2.0",
+    "engine.io": "~6.2.1",
    "socket.io-adapter": "~2.4.0",
-    "socket.io-parser": "~4.2.0"
+    "socket.io-parser": "~4.2.1"
  },
  "devDependencies": {
    "@types/mocha": "^9.0.0",
@@ -60,7 +60,7 @@
    "nyc": "^15.1.0",
    "prettier": "^2.3.2",
    "rimraf": "^3.0.2",
-    "socket.io-client": "4.5.2",
+    "socket.io-client": "4.5.4",
    "socket.io-client-v2": "npm:socket.io-client@^2.4.0",
    "superagent": "^8.0.0",
    "supertest": "^6.1.6",
--- a/test/socket.io.test-d.ts
+++ b/test/socket.io.test-d.ts
@@ -4,6 +4,7 @@ import type { DefaultEventsMap } from "../lib/typed-events";
 import { createServer } from "http";
 import { expectError, expectType } from "tsd";
 import { Adapter } from "socket.io-adapter";
+import type { DisconnectReason } from "../lib/socket";

 // This file is run by tsd, not mocha.

@@ -17,10 +18,10 @@ describe("server", () => {
          sio.on("connection", (s) => {
            expectType<Socket<DefaultEventsMap, DefaultEventsMap>>(s);
            s.on("disconnect", (reason) => {
-              expectType<string>(reason);
+              expectType<DisconnectReason>(reason);
            });
            s.on("disconnecting", (reason) => {
-              expectType<string>(reason);
+              expectType<DisconnectReason>(reason);
            });
          });
          sio.on("connect", (s) => {
@@ -208,6 +209,10 @@ describe("server", () => {
        const srv = createServer();
        const sio = new Server<ClientToServerEvents, ServerToClientEvents>(srv);
        srv.listen(() => {
+          sio.emit("helloFromServer", "hi", 1);
+          sio.to("room").emit("helloFromServer", "hi", 1);
+          sio.timeout(1000).emit("helloFromServer", "hi", 1);
+
          sio.on("connection", (s) => {
            s.emit("helloFromServer", "hi", 10);
            done();
@@ -219,6 +224,10 @@ describe("server", () => {
        const srv = createServer();
        const sio = new Server<ClientToServerEvents, ServerToClientEvents>(srv);
        srv.listen(() => {
+          expectError(sio.emit("helloFromClient"));
+          expectError(sio.to("room").emit("helloFromClient"));
+          expectError(sio.timeout(1000).to("room").emit("helloFromClient"));
+
          sio.on("connection", (s) => {
            expectError(s.emit("helloFromClient", "hi"));
            expectError(s.emit("helloFromServer", "hi", 10, "10"));
@@ -233,7 +242,7 @@ describe("server", () => {
    });
  });

-  describe("listen and emit event maps", () => {
+  describe("listen and emit event maps for the serverSideEmit method", () => {
    interface ClientToServerEvents {
      helloFromClient: (message: string) => void;
    }
Author	SHA1	Message	Date
Damien Arrachequesne	3b7ced7af7	chore(release): 4.5.4 Diff: https://github.com/socketio/socket.io/compare/4.5.3...4.5.4	2022-11-22 22:45:13 +01:00
Damien Arrachequesne	c00bb9564c	chore: bump engine.io to version 6.2.1 In order to fix CVE-2022-41940. See also: https://github.com/socketio/engine.io/security/advisories/GHSA-r7qp-cfhv-p84w	2022-11-22 22:35:53 +01:00
Damien Arrachequesne	57e5f25e26	chore: bump socket.io-parser to version 4.2.1 In order to fix CVE-2022-2421. See also: https://github.com/advisories/GHSA-qm95-pgcg-qqfq	2022-11-22 22:32:09 +01:00
Damien Arrachequesne	f4b698418a	docs: add missing versions in the changelog	2022-11-02 08:40:26 +01:00
Damien Arrachequesne	945c84be47	chore(release): 4.5.3 Diff: https://github.com/socketio/socket.io/compare/4.5.2...4.5.3	2022-10-15 07:14:45 +02:00
Damien Arrachequesne	d3d0a2d5be	fix(typings): accept an HTTP2 server in the constructor Related: - https://github.com/socketio/socket.io/issues/4434 - https://github.com/socketio/socket.io/issues/4494	2022-10-14 11:24:36 +02:00
Damien Arrachequesne	19b225b0c8	docs(examples): update dependencies of the basic CRUD example Related: https://github.com/socketio/socket.io/issues/4409	2022-10-14 10:39:40 +02:00
Damien Arrachequesne	8fae95dd18	docs: add jsdoc for each public method	2022-10-14 10:30:08 +02:00
Damien Arrachequesne	e6f6b906db	docs: add deprecation notice for the allSockets() method	2022-10-13 15:02:23 +02:00
Damien Arrachequesne	596eb88af7	ci: upgrade to actions/checkout@3 and actions/setup-node@3 Reference: https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/	2022-10-13 14:50:09 +02:00
Damien Arrachequesne	e357daf585	fix(typings): apply types to "io.timeout(...).emit()" calls Typed events were not applied when calling "io.timeout(...).emit()". Related: https://github.com/socketio/socket.io-client/issues/1555#issuecomment-1277289733 Reference: https://socket.io/docs/v4/typescript/	2022-10-13 14:50:09 +02:00
Damien Arrachequesne	10fa4a2690	refactor: add list of possible disconnection reasons Note: some disconnection reasons could be merged in the next major release, i.e. the Deno impl does not have "forced server close" and "server shutting down" Related: https://github.com/socketio/socket.io/issues/4387	2022-09-13 08:25:13 +02:00