Socket.IO Client API

https://socket.io/docs/v4/client-api/
Admin
The Socket.IO Client API provides methods and classes for establishing and managing real-time,...
Tokens:10,887
Snippets:96
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Get All Catch-all Listeners

Source: https://socket.io/docs/v4/client-api

Returns an array of all registered catch-all listeners that listen for any event.

```javascript
const listeners = socket.listenersAny();  
```

--------------------------------

### Manager Reconnection Settings

Source: https://socket.io/docs/v4/client-api

Provides methods to set or get reconnection-related options for the manager.

```APIDOC
## Manager Reconnection Settings

### Description
These methods allow you to configure or retrieve the reconnection behavior of the Socket.IO manager.

### Methods
#### manager.reconnection([value])
* `value` (boolean) - Sets the reconnection option.
* **Returns** (Manager | boolean) - The Manager instance or the current reconnection status.

#### manager.reconnectionAttempts([value])
* `value` (number) - Sets the number of reconnection attempts.
* **Returns** (Manager | number) - The Manager instance or the current number of reconnection attempts.

#### manager.reconnectionDelay([value])
* `value` (number) - Sets the initial delay before the first reconnection attempt.
* **Returns** (Manager | number) - The Manager instance or the current reconnection delay.

#### manager.reconnectionDelayMax([value])
* `value` (number) - Sets the maximum delay between reconnection attempts.
* **Returns** (Manager | number) - The Manager instance or the current maximum reconnection delay.
```

--------------------------------

### Get All Outgoing Catch-all Listeners

Source: https://socket.io/docs/v4/client-api

Returns an array of all registered catch-all listeners for outgoing packets.

```javascript
const listeners = socket.listenersAnyOutgoing();  
```

--------------------------------

### Get Event Listeners

Source: https://socket.io/docs/v4/client-api

Retrieves an array of all registered listener functions for a specific event name.

```javascript
socket.on("my-event", () => {
  // ...
});

console.log(socket.listeners("my-event")); // prints [ [Function] ]  
```

--------------------------------

### Get Socket Session ID

Source: https://socket.io/docs/v4/client-api

socket.id provides a unique identifier for the socket session. This ID is set after the 'connect' event and is regenerated upon reconnection. It is primarily for debugging and not recommended for application logic.

```javascript
const socket = io();

console.log(socket.id); // undefined

socket.on("connect", () => {
  console.log(socket.id); // "G5p5..."
});
```

--------------------------------

### Client Connection with io()

Source: https://socket.io/docs/v4/client-api

Demonstrates how to establish a Socket.IO connection using the `io()` method in different environments (standalone script, ESM, Node.js).

```APIDOC
## Client Connection with io()

### Description
This section shows how to initialize a Socket.IO client connection using the global `io()` function or by importing it from the `socket.io-client` package.

### Usage Examples

**Standalone Build:**
```html
<script src="/socket.io/socket.io.js"></script>
<script>
  const socket = io();
</script>
```

**ESM Bundle:**
```html
<script type="module">
  import { io } from "https://cdn.socket.io/4.8.3/socket.io.esm.min.js";
  const socket = io();
</script>
```

**With Import Map:**
```html
<script type="importmap">
  {
    "imports": {
      "socket.io-client": "https://cdn.socket.io/4.8.3/socket.io.esm.min.js"
    }
  }
</script>
<script type="module">
  import { io } from "socket.io-client";
  const socket = io();
</script>
```

**Node.js / CommonJS / ES Modules:**
```javascript
// ES modules
import { io } from "socket.io-client";

// CommonJS
const { io } = require("socket.io-client");

const socket = io();

```

--------------------------------

### Establish Socket.IO Connection with Options

Source: https://socket.io/docs/v4/client-api

Create a Socket.IO connection to a specific namespace with custom reconnection, authentication, and query parameters.

```javascript
import { io } from "socket.io-client";  
  
const socket = io("ws://example.com/my-namespace", {  
  reconnectionDelayMax: 10000,  
  auth: {  
    token: "123"  
  },  
  query: {  
    "my-key": "my-value"  
  }  
});  

```

--------------------------------

### Open a connection with a callback

Source: https://socket.io/docs/v4/client-api

Use this to initiate a connection when autoConnect is false. The callback is invoked upon connection success or failure.

```javascript
import { Manager } from "socket.io-client";  
  
const manager = new Manager("https://example.com", {  
  autoConnect: false  
});  
  
const socket = manager.socket("/");  
  
manager.open((err) => {  
  if (err) {  
    // an error has occurred  
  } else {  
    // the connection was successfully established  
  }  
});  
```

--------------------------------

### io([url][, options])

Source: https://socket.io/docs/v4/client-api

Initializes a new Socket.IO connection or reuses an existing manager. Allows specifying connection URL, namespace, and various options.

```APIDOC
## io([url][, options])

### Description
Creates a new `Manager` for the given URL and attempts to reuse an existing `Manager` unless `multiplex` is `false`. Returns a `Socket` instance for the specified namespace (defaults to `/`). Query parameters can be included in the URL or via the `query` option.

### Parameters

*   **url** (`<string>`) - The connection URL. Defaults to `window.location.host`.
*   **options** (`<Object>`) - Configuration options for the connection.
    *   **forceNew** (`<boolean>`) - Whether to create a new connection. Equivalent to `{"force new connection": true}`.
    *   **query** (`<Object>`) - Custom query parameters to send with the connection.
    *   **auth** (`<Object>`) - Authentication credentials.
    *   **reconnectionDelayMax** (`<number>`) - Maximum delay for reconnection attempts.

### Returns
*   `<Socket>` - A new Socket instance.

### Example
```javascript
import { io } from "socket.io-client";

const socket = io("ws://example.com/my-namespace", {
  reconnectionDelayMax: 10000,
  auth: {
    token: "123"
  },
  query: {
    "my-key": "my-value"
  }
});
```

### Equivalent to using Manager:
```javascript
import { Manager } from "socket.io-client";

const manager = new Manager("ws://example.com", {
  query: {
    "my-key": "my-value"
  }
});

const socket = manager.socket("/my-namespace", {
  auth: {
    token: "123"
  }
});
```
```

--------------------------------

### Register Catch-All Listener at Beginning

Source: https://socket.io/docs/v4/client-api

Use `prependAny` to register a listener for all incoming events. The listener is added to the beginning of the listeners array.

```javascript
socket.prependAny((event, ...args) => {
  console.log(`got ${event}`);
});

```

--------------------------------

### Include Socket.IO via Import Map

Source: https://socket.io/docs/v4/client-api

Configure Socket.IO inclusion using an import map for managing module dependencies in the browser.

```html
<script type="importmap">  
  {"imports": {  
      "socket.io-client": "https://cdn.socket.io/4.8.3/socket.io.esm.min.js"  
    }  
  }  
</script>  
  
<script type="module">  
  import { io } from "socket.io-client";  
  
  const socket = io();  
</script>  

```

--------------------------------

### Emit and listen for events

Source: https://socket.io/docs/v4/client-api

Basic usage for sending data to the server and receiving data from it using emit and on.

```javascript
socket.emit("hello", { a: "b", c: [] });  
  
socket.on("hey", (...args) => {  
  // ...  
});  
```

--------------------------------

### Create Socket.IO Connection via Manager

Source: https://socket.io/docs/v4/client-api

Manually create a Manager instance and then obtain Socket instances for different namespaces.

```javascript
import { Manager } from "socket.io-client";  
  
const manager = new Manager("https://example.com");  
  
const socket = manager.socket("/"); // main namespace  
const adminSocket = manager.socket("/admin"); // admin namespace  

```

--------------------------------

### socket.prependAny(callback)

Source: https://socket.io/docs/v4/client-api

Registers a catch-all listener for any event, adding it to the beginning of the listeners array. This ensures the listener is called before any other listeners for the same event.

```APIDOC
## socket.prependAny(callback)

### Description
Registers a new catch-all listener. The listener is added to the beginning of the listeners array.

### Parameters
#### Path Parameters
* `callback` (Function) - The function to be called when any event is received.

### Request Example
```javascript
socket.prependAny((event, ...args) => {
  console.log(`got ${event}`);
});
```
```

--------------------------------

### Register Outgoing Catch-All Listener at Beginning

Source: https://socket.io/docs/v4/client-api

Use `prependAnyOutgoing` to register a listener for all outgoing packets. The listener is added to the beginning of the listeners array.

```javascript
socket.prependAnyOutgoing((event, ...args) => {
  console.log(`got ${event}`);
});

```

--------------------------------

### Emit Event with Timeout and Callback (Equivalent)

Source: https://socket.io/docs/v4/client-api

Demonstrates the equivalent of emitWithAck using the timeout method and a traditional callback for acknowledgements.

```javascript
// without timeout  
socket.emit("hello", "world", (val) => {
  // ...
});  

```

```javascript
// with a specific timeout  
socket.timeout(10000).emit("hello", "world", (err, val) => {
  // ...
});  
```

--------------------------------

### socket.open()

Source: https://socket.io/docs/v4/client-api

Opens the connection to the Socket.IO server. This method is a synonym for socket.connect().

```APIDOC
## socket.open()

### Description
Opens the connection to the Socket.IO server. This is a synonym for `socket.connect()`.

### Method
`open()`

### Endpoint
N/A (Client-side method)

### Request Example
```javascript
socket.open();
```
```

--------------------------------

### Socket Class Overview

Source: https://socket.io/docs/v4/client-api

Overview of the Socket class, its purpose, and basic usage.

```APIDOC
## Socket

A `Socket` is the fundamental class for interacting with the server. A `Socket` belongs to a certain Namespace (by default `/`) and uses an underlying Manager to communicate.

A `Socket` is basically an EventEmitter which sends events to — and receive events from — the server over the network.

### Basic Usage
```javascript
socket.emit("hello", { a: "b", c: [] });

socket.on("hey", (...args) => {
  // ...
});
```

More information can be found [here](link_to_more_info).
```

--------------------------------

### Manager Methods

Source: https://socket.io/docs/v4/client-api

Provides methods to control the manager, such as initiating a connection.

```APIDOC
## Manager Methods

### manager.connect([callback])

*   **callback** (`<function>`) - Optional callback function.

Synonym for `manager.open([callback])`. Initiates or resumes the connection.

### manager.open([callback])

*   **callback** (`<function>`) - Optional callback function.

Opens the connection to the server.
```

--------------------------------

### socket.on

Source: https://socket.io/docs/v4/client-api

Registers a new event listener.

```APIDOC
## socket.on(eventName, callback)

### Description
Register a new handler for the given event. This method is inherited from the `EventEmitter` class.

### Method
`socket.on`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **eventName** (string | symbol) - The name of the event to listen for.
- **callback** (Function) - The function to be executed when the event is received.

### Request Example
```javascript
socket.on("news", (data) => {
  console.log(data);
});

// with multiple arguments
socket.on("news", (arg1, arg2, arg3, arg4) => {
  // ...
});

// with callback for acknowledgement
socket.on("news", (cb) => {
  cb(0);
});
```

### Response
#### Success Response (200)
- **Returns** (Socket) - The Socket instance for chaining.

#### Response Example
(Returns the Socket instance)
```

--------------------------------

### Include Socket.IO via Script Tag

Source: https://socket.io/docs/v4/client-api

Include the Socket.IO client library using a script tag for use in a browser environment.

```html
<script src="/socket.io/socket.io.js"></script>  
<script>  
  const socket = io();  
</script>  

```

--------------------------------

### Manager Socket Creation

Source: https://socket.io/docs/v4/client-api

Creates a new Socket instance for a given namespace.

```APIDOC
## manager.socket(nsp, options)

### Description
Creates a new `Socket` for the given namespace. Only `auth` (`{ auth: {key: "value"} }`) is read from the `options` object. Other keys will be ignored and should be passed when instancing a `new Manager(nsp, options)`.

### Parameters
#### Path Parameters
* `nsp` (string) - The namespace for the socket.
* `options` (Object) - Options for the socket, primarily used for authentication.

### Returns
* `<Socket>` - The newly created Socket instance.
```

--------------------------------

### Include Socket.IO via ESM CDN

Source: https://socket.io/docs/v4/client-api

Include the Socket.IO client library using an ESM bundle from a CDN for modern JavaScript environments.

```html
<script type="module">  
  import { io } from "https://cdn.socket.io/4.8.3/socket.io.esm.min.js";  
  
  const socket = io();  
</script>  

```

--------------------------------

### socket.prependAnyOutgoing(callback)

Source: https://socket.io/docs/v4/client-api

Registers a catch-all listener for outgoing packets at the beginning of the listeners array. This listener is invoked for any event being sent from the client, before other listeners.

```APIDOC
## socket.prependAnyOutgoing(callback)

### Description
Registers a new catch-all listener for outgoing packets. The listener is added to the beginning of the listeners array.

### Parameters
#### Path Parameters
* `callback` (Function) - The function to be called when any outgoing event is detected.

### Request Example
```javascript
socket.prependAnyOutgoing((event, ...args) => {
  console.log(`got ${event}`);
});
```
```

--------------------------------

### Server-side Acknowledgement Handler

Source: https://socket.io/docs/v4/client-api

Handles an incoming 'hello' event and sends back an acknowledgement. The callback function is used for the acknowledgement.

```javascript
io.on("connection", (socket) => {
  socket.on("hello", (arg, callback) => {
    console.log(arg); // "world"
    callback("got it");
  });
});  
```

--------------------------------

### Manager Open

Source: https://socket.io/docs/v4/client-api

Opens a new connection attempt if the manager was initiated with autoConnect set to false. The callback is optional and is invoked upon connection success or failure.

```APIDOC
## manager.open([callback])

### Description
If the manager was initiated with `autoConnect` to `false`, launch a new connection attempt. The `callback` argument is optional and will be called once the attempt fails/succeeds.

### Parameters
#### Path Parameters
* `callback` (Function) - Optional - The callback function to be executed upon connection attempt completion.

### Request Example
```javascript
import { Manager } from "socket.io-client";

const manager = new Manager("https://example.com", {
  autoConnect: false
});

const socket = manager.socket("/");

manager.open((err) => {
  if (err) {
    // an error has occurred
  } else {
    // the connection was successfully established
  }
});
```
```

--------------------------------

### Socket Methods

Source: https://socket.io/docs/v4/client-api

Details the methods available on a Socket.IO client instance for managing the connection, including closing, compressing data, manually connecting, and disconnecting.

```APIDOC
## Socket Methods

### socket.close()

Synonym of `socket.disconnect()`.

### socket.compress(value)

* `value` `<boolean>`
* **Returns** `<Socket>`

Sets a modifier for a subsequent event emission that the event data will only be _compressed_ if the value is `true`. Defaults to `true` when you don't call the method.

### socket.connect()

* **Returns** `Socket`

Manually connects the socket. It can also be used to manually reconnect.

### socket.disconnect()

* **Returns** `<Socket>`

Manually disconnects the socket. In that case, the socket will not try to reconnect. If this is the last active Socket instance of the Manager, the low-level connection will be closed.
```

--------------------------------

### Import Socket.IO Client

Source: https://socket.io/docs/v4/client-api

Import the io function from the socket.io-client package for use in ES modules or CommonJS environments.

```javascript
// ES modules  
import { io } from "socket.io-client";  

// CommonJS  
const { io } = require("socket.io-client");  

```

--------------------------------

### Emit Event with Data

Source: https://socket.io/docs/v4/client-api

Emits an event with optional string, any, or Buffer arguments. All serializable data structures are supported.

```javascript
socket.emit("hello", "world");
```

```javascript
socket.emit("with-binary", 1, "2", { 3: "4", 5: Buffer.from([6, 7, 8]) });
```

--------------------------------

### socket.onAny

Source: https://socket.io/docs/v4/client-api

Registers a new catch-all listener for any event.

```APIDOC
## socket.onAny(callback)

### Description
Register a new catch-all listener that will be invoked for any event. Added in v3.0.0.

### Method
`socket.onAny`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **callback** (Function) - The function to be executed when any event is received. It receives the event name as the first argument, followed by any additional arguments.

### Request Example
```javascript
socket.onAny((event, ...args) => {
  console.log(`got ${event}`);
});
```

### Response
#### Success Response (200)
(No specific return value mentioned, typically implies operation success)

#### Response Example
(No specific response body example)

### Caution
Acknowledgements are not caught in the catch-all listener.
```

--------------------------------

### Register Catch-All Listener for Outgoing Packets

Source: https://socket.io/docs/v4/client-api

Use `onAnyOutgoing` to register a listener for all outgoing packets. Acknowledgements are not caught by this listener.

```javascript
socket.onAnyOutgoing((event, ...args) => {
  console.log(`got ${event}`);
});

```

```javascript
socket.on("foo", (value, callback) => {
  callback("OK");
});

socket.onAny(() => {
  // triggered when the event is received
});

socket.onAnyOutgoing(() => {
  // not triggered when the acknowledgement is sent
});

```

--------------------------------

### Manually Connect Socket

Source: https://socket.io/docs/v4/client-api

Call socket.connect() to manually establish a connection. This is useful when autoConnect is set to false or for manual reconnection after a disconnection.

```javascript
const socket = io({
  autoConnect: false
});

// ...
socket.connect();
```

```javascript
socket.on("disconnect", () => {
  socket.connect();
});
```

--------------------------------

### socket.emitWithAck

Source: https://socket.io/docs/v4/client-api

A promised-based version of emitting an event and waiting for an acknowledgement from the server. Supports timeouts.

```APIDOC
## socket.emitWithAck(eventName[, ...args])

### Description
Promised-based version of emitting and expecting an acknowledgement from the server. This method is available starting from v4.6.0.

### Method
`socket.emitWithAck`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **eventName** (string | symbol) - The name of the event to emit.
- **args** (any[]) - Any serializable data to send with the event.

### Request Example
```javascript
// without timeout
const response = await socket.emitWithAck("hello", "world");

// with a specific timeout
try {
  const response = await socket.timeout(10000).emitWithAck("hello", "world");
} catch (err) {
  // the server did not acknowledge the event in the given delay
}
```

### Response
#### Success Response (200)
- **Returns** (Promise<any>) - A Promise that resolves with the acknowledgement from the server.

#### Response Example
(Response is the value passed in the callback from the server. Example: `"got it"`)
```

--------------------------------

### socket.listenersAny

Source: https://socket.io/docs/v4/client-api

Retrieves all registered catch-all listeners.

```APIDOC
## socket.listenersAny()

### Description
Returns the list of registered catch-all listeners. Added in v3.0.0.

### Method
`socket.listenersAny`

### Parameters
None

### Request Example
```javascript
const listeners = socket.listenersAny();
```

### Response
#### Success Response (200)
- **Returns** (Function[]) - An array of catch-all listener functions.

#### Response Example
`[ [Function], [Function] ]`
```

--------------------------------

### Server-side Handler for Promise-based Acknowledgement

Source: https://socket.io/docs/v4/client-api

Handles an incoming event and provides a callback for acknowledgement. Only one argument is expected by the callback.

```javascript
io.on("connection", (socket) => {
  socket.on("hello", (arg1, callback) => {
    callback("got it"); // only one argument is expected  
  });
});  
```

--------------------------------

### Socket Events

Source: https://socket.io/docs/v4/client-api

Details on the various events emitted by a Socket instance.

```APIDOC
## Socket Events

### Event: 'connect'

This event is fired by the Socket instance upon connection **and** reconnection.

```javascript
socket.on("connect", () => {
  // ...
});
```

**Caution**: Event handlers shouldn't be registered in the `connect` handler itself, as a new handler will be registered every time the socket instance reconnects:

BAD ⚠️
```javascript
socket.on("connect", () => {
  socket.on("data", () => { /* ... */ });
});
```

GOOD 👍
```javascript
socket.on("connect", () => {
  // ...
});

socket.on("data", () => { /* ... */ });
```

### Event: 'connect_error'

* `error` (Error) - The error object detailing the connection failure.

This event is fired upon connection failure.

| Reason                                                              | Automatic reconnection? |
| ------------------------------------------------------------------- | ----------------------- |
| The low-level connection cannot be established (temporary failure)    | ✅ YES                  |
| The connection was denied by the server in a middleware function    | ❌ NO                   |

The `socket.active` attribute indicates whether the socket will automatically try to reconnect after a small randomized delay:

```javascript
socket.on("connect_error", (error) => {
  if (socket.active) {
    // temporary failure, the socket will automatically try to reconnect
  } else {
    // the connection was denied by the server
    // in that case, `socket.connect()` must be manually called in order to reconnect
  }
});
```

### Event: 'disconnect'

* `reason` (string) - The reason for the disconnection.
* `details` (DisconnectDetails) - Additional details about the disconnection.

This event is fired upon disconnection.

```javascript
socket.on("disconnect", (reason, details) => {
  // ...
});
```

Here is the list of possible reasons:

| Reason                | Description                                                                     | Automatic reconnection? |
| --------------------- | ------------------------------------------------------------------------------- | ----------------------- |
| `io server disconnect`| The server has forcefully disconnected the socket with socket.disconnect()      | ❌ NO                   |
| `io client disconnect`| The socket was manually disconnected using socket.disconnect()                  | ❌ NO                   |
| `ping timeout`        | The server did not send a PING within the `pingInterval + pingTimeout` range    | ✅ YES                  |
| `transport close`     | The connection was closed (example: the user has lost connection, or the network was changed from WiFi to 4G) | ✅ YES                  |
| `transport error`     | The connection has encountered an error (example: the server was killed during a HTTP long-polling cycle) | ✅ YES                  |

The `socket.active` attribute indicates whether the socket will automatically try to reconnect after a small randomized delay:

```javascript
socket.on("disconnect", (reason) => {
  if (socket.active) {
    // temporary disconnection, the socket will automatically try to reconnect
  } else {
    // the connection was forcefully closed by the server or the client itself
    // in that case, `socket.connect()` must be manually called in order to reconnect
    console.log(reason);
  }
});
```
```

--------------------------------

### Emit Event with Acknowledgement Callback

Source: https://socket.io/docs/v4/client-api

Emits an event and expects a callback response from the server. The callback is invoked with the server's answer.

```javascript
socket.emit("hello", "world", (response) => {
  console.log(response); // "got it"
});  
```

--------------------------------

### socket.send([...args][, ack])

Source: https://socket.io/docs/v4/client-api

Sends a 'message' event with the provided arguments. This is a shorthand for socket.emit('message', [...args][, ack]).

```APIDOC
## socket.send([...args][, ack])

### Description
Sends a `message` event. See `socket.emit(eventName[, ...args][, ack])`.

### Parameters
#### Path Parameters
* `args` (any[]) - An array of arguments to send with the message.
* `ack` (Function) - An optional acknowledgment callback function.

### Returns
* `<Socket>` - The socket instance for chaining.

### Request Example
```javascript
socket.send('hello', 'world', () => {
  console.log('Message acknowledged');
});
```
```

--------------------------------

### Manager Class

Source: https://socket.io/docs/v4/client-api

Manages the Engine.IO client instance and handles connection logic, including reconnections. A single Manager can be used by multiple Sockets.

```APIDOC
## Manager

### Description
The `Manager` class manages the underlying Engine.IO client, which handles the actual connection to the server using transports like WebSockets or HTTP long-polling. It is responsible for reconnection logic and can be shared across multiple Socket instances for multiplexing.

### Constructor

#### new Manager(url[, options])

*   **url** (`<string>`) - The server URL to connect to.
*   **options** (`<Object>`) - Configuration options for the manager.

*   **Returns** (`<Manager>`) - A new Manager instance.

### Example
```javascript
import { Manager } from "socket.io-client";

const manager = new Manager("https://example.com");

const socket = manager.socket("/"); // Main namespace
const adminSocket = manager.socket("/admin"); // Admin namespace
```
```

--------------------------------

### io.protocol

Source: https://socket.io/docs/v4/client-api

Information about the protocol revision number used for communication between client and server.

```APIDOC
## io.protocol

### Description
This property holds the protocol revision number (currently: 5). It defines the format of packets exchanged between the client and server. Both sides must use the same revision for successful communication.

### Type
`<number>`

### Value
`5` (as of current documentation)
```

--------------------------------

### Register Catch-all Listener

Source: https://socket.io/docs/v4/client-api

Registers a new listener that will be called for any event. Acknowledgements are not caught by this listener.

```javascript
socket.onAny((event, ...args) => {
  console.log(`got ${event}`);
});  
```

--------------------------------

### Emit Event with Promise-based Acknowledgement

Source: https://socket.io/docs/v4/client-api

Emits an event and returns a Promise that resolves with the server's acknowledgement. Supports optional timeouts.

```javascript
// without timeout  
const response = await socket.emitWithAck("hello", "world");  
```

```javascript
// with a specific timeout  
try {
  const response = await socket.timeout(10000).emitWithAck("hello", "world");
} catch (err) {
  // the server did not acknowledge the event in the given delay  
}
```

--------------------------------

### Handle Socket.IO Reconnection Success

Source: https://socket.io/docs/v4/client-api

Listen for the 'reconnect' event to know when the client has successfully re-established a connection.

```javascript
socket.io.on("reconnect", (attempt) => {  
  // ...  
});  

```

--------------------------------

### Handle Socket.IO Reconnection Attempt

Source: https://socket.io/docs/v4/client-api

Listen for the 'reconnect_attempt' event to track when the client is trying to reconnect.

```javascript
socket.io.on("reconnect_attempt", (attempt) => {  
  // ...  
});  

```

--------------------------------

### socket.emit

Source: https://socket.io/docs/v4/client-api

Emits an event to the server. Supports arbitrary serializable data and optional acknowledgements.

```APIDOC
## socket.emit(eventName[, ...args][, ack])

### Description
Emits an event to the socket identified by the string name. Any other parameters can be included. All serializable data structures are supported, including `Buffer`.

### Method
`socket.emit`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **eventName** (string | symbol) - The name of the event to emit.
- **args** (any[]) - Any serializable data to send with the event.
- **ack** (Function) - An optional callback function to receive an acknowledgement from the server.

### Request Example
```javascript
socket.emit("hello", "world");
socket.emit("with-binary", 1, "2", { 3: "4", 5: Buffer.from([6, 7, 8]) });

// With acknowledgement
socket.emit("hello", "world", (response) => {
  console.log(response); // "got it"
});
```

### Response
#### Success Response (200)
- **Returns** (boolean) - `true` if the event was sent successfully.

#### Response Example
(No specific response body example, returns a boolean indicating success)
```

--------------------------------

### socket.offAny

Source: https://socket.io/docs/v4/client-api

Removes catch-all listeners.

```APIDOC
## socket.offAny([listener])

### Description
Removes the previously registered catch-all listener. If no listener is provided, all catch-all listeners are removed. Added in v3.0.0.

### Method
`socket.offAny`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **listener** (Function) - Optional. The specific catch-all listener function to remove. If omitted, all catch-all listeners are removed.

### Request Example
```javascript
const myListener = () => { /* ... */ };

socket.onAny(myListener);

// then, later
socket.offAny(myListener);

socket.offAny();
```

### Response
#### Success Response (200)
(No specific return value mentioned, typically implies operation success)

#### Response Example
(No specific response body example)
```

--------------------------------

### Handle Socket.IO Connection Errors

Source: https://socket.io/docs/v4/client-api

Listen for the 'error' event on the Socket.IO client to handle any connection-related errors.

```javascript
socket.io.on("error", (error) => {  
  // ...  
});  

```

--------------------------------

### socket.onAnyOutgoing(callback)

Source: https://socket.io/docs/v4/client-api

Registers a catch-all listener for outgoing packets. This listener is invoked for any event being sent from the client. Note that acknowledgements are not caught by this listener.

```APIDOC
## socket.onAnyOutgoing(callback)

### Description
Registers a new catch-all listener for outgoing packets.

### Parameters
#### Path Parameters
* `callback` (Function) - The function to be called when any outgoing event is detected.

### Request Example
```javascript
socket.onAnyOutgoing((event, ...args) => {
  console.log(`got ${event}`);
});
```

### Caution
Acknowledgements are not caught in the catch-all listener.
```javascript
socket.on("foo", (value, callback) => {
  callback("OK");
});

socket.onAny(() => {
  // triggered when the event is received
});

socket.onAnyOutgoing(() => {
  // not triggered when the acknowledgement is sent
});
```
```

--------------------------------

### socket.listenersAnyOutgoing

Source: https://socket.io/docs/v4/client-api

Retrieves all registered catch-all listeners for outgoing packets.

```APIDOC
## socket.listenersAnyOutgoing()

### Description
Returns the list of registered catch-all listeners for outgoing packets. Added in v4.5.0.

### Method
`socket.listenersAnyOutgoing`

### Parameters
None

### Request Example
```javascript
const listeners = socket.listenersAnyOutgoing();
```

### Response
#### Success Response (200)
- **Returns** (Function[]) - An array of catch-all listener functions for outgoing packets.

#### Response Example
`[ [Function], [Function] ]`
```

--------------------------------

### Manager Timeout Setting

Source: https://socket.io/docs/v4/client-api

Sets or retrieves the connection timeout for the manager.

```APIDOC
## manager.timeout([value])

### Description
Sets the `timeout` option, or returns it if no parameters are passed.

### Parameters
#### Path Parameters
* `value` (number) - The timeout value in milliseconds.

### Returns
* `<Manager>` | `<number>` - The Manager instance or the current timeout value.
```

--------------------------------

### Compress Event Data

Source: https://socket.io/docs/v4/client-api

Use socket.compress(false) before emitting an event to disable data compression for that specific emission. Compression is enabled by default.

```javascript
socket.compress(false).emit("an event", { some: "data" });
```

--------------------------------

### Access Underlying Manager and Engine

Source: https://socket.io/docs/v4/client-api

socket.io provides access to the underlying Manager, from which the engine can be accessed. This allows monitoring transport status, packet events, and connection lifecycle.

```javascript
socket.on("connect", () => {
  const engine = socket.io.engine;
  console.log(engine.transport.name); // in most cases, prints "polling"

  engine.once("upgrade", () => {
    // called when the transport is upgraded (i.e. from HTTP long-polling to WebSocket)
    console.log(engine.transport.name); // in most cases, prints "websocket"
  });

  engine.on("packet", ({ type, data }) => {
    // called for each packet received
  });

  engine.on("packetCreate", ({ type, data }) => {
    // called for each packet sent
  });

  engine.on("drain", () => {
    // called when the write buffer is drained
  });

  engine.on("close", (reason) => {
    // called when the underlying connection is closed
  });
});

```

--------------------------------

### Socket Attributes

Source: https://socket.io/docs/v4/client-api

Explains the various boolean and string attributes available on a Socket.IO client instance, providing insights into connection status, reconnection behavior, and socket identification.

```APIDOC
## Socket Attributes

### socket.active

* `<boolean>`

Whether the socket will automatically try to reconnect.
This attribute can be used after a connection failure or disconnection to determine if a reconnection attempt will be made automatically.

### socket.connected

* `<boolean>`

Whether the socket is currently connected to the server.

### socket.disconnected

* `<boolean>`

Whether the socket is currently disconnected from the server.

### socket.id

* `<string>`

A unique identifier for the socket session. Set after the `connect` event is triggered, and updated after the `reconnect` event.

**Caution**: The `id` attribute is an ephemeral ID that is not meant to be used in your application (or only for debugging purposes) because it is regenerated after each reconnection and two different browser tabs will have different IDs. There is no message queue stored for a given ID on the server. Please use a regular session ID instead.

### socket.io

* `<Manager>`

A reference to the underlying Manager.

### socket.recovered

* `<boolean>`

Whether the connection state was successfully recovered during the last reconnection. This attribute is available starting from v4.6.0.
```

--------------------------------

### Handle Socket.IO Failed Reconnection

Source: https://socket.io/docs/v4/client-api

Listen for the 'reconnect_failed' event when the client is unable to reconnect within the configured number of attempts.

```javascript
socket.io.on("reconnect_failed", () => {  
  // ...  
});  

```

--------------------------------

### Register Event Listener

Source: https://socket.io/docs/v4/client-api

Registers a new handler function for a given event name. Supports multiple arguments and callbacks.

```javascript
socket.on("news", (data) => {
  console.log(data);
});

// with multiple arguments  
socket.on("news", (arg1, arg2, arg3, arg4) => {
  // ...
});
// with callback  
socket.on("news", (cb) => {
  cb(0);
});  
```

--------------------------------

### Add One-Time Event Listener

Source: https://socket.io/docs/v4/client-api

Use `once` to add a listener that will be invoked only the next time the event is triggered. The listener is automatically removed afterward.

```javascript
socket.once("my-event", () => {
  // ...
});

```

--------------------------------

### Handle Socket.IO Ping Event

Source: https://socket.io/docs/v4/client-api

Listen for the 'ping' event to be notified when a ping packet is received from the server.

```javascript
socket.io.on("ping", () => {  
  // ...  
});  

```

--------------------------------

### Emit Volatile Event

Source: https://socket.io/docs/v4/client-api

Use the `volatile` flag before `emit` to indicate that the packet may be dropped if the socket is not connected or the transport is not writable.

```javascript
socket.volatile.emit(/* ... */); // the server may or may not receive it

```

--------------------------------

### Manager Events

Source: https://socket.io/docs/v4/client-api

Listens for various events emitted by the Manager, such as connection errors, ping acknowledgments, and reconnection status.

```APIDOC
## Manager Events

### Event: 'error'

*   **error** (`<Error>`) - The error object.

Fired upon a connection error.
```javascript
manager.io.on("error", (error) => {
  console.error("Connection error:", error);
});
```

### Event: 'ping'

Fired when a ping packet is received from the server.
```javascript
manager.io.on("ping", () => {
  console.log("Ping received from server.");
});
```

### Event: 'reconnect'

*   **attempt** (`<number>`) - The reconnection attempt number.

Fired upon a successful reconnection.
```javascript
manager.io.on("reconnect", (attempt) => {
  console.log(`Reconnected after attempt: ${attempt}`);
});
```

### Event: 'reconnect_attempt'

*   **attempt** (`<number>`) - The reconnection attempt number.

Fired upon an attempt to reconnect.
```javascript
manager.io.on("reconnect_attempt", (attempt) => {
  console.log(`Attempting to reconnect: ${attempt}`);
});
```

### Event: 'reconnect_error'

*   **error** (`<Error>`) - The error object.

Fired upon a reconnection attempt error.
```javascript
manager.io.on("reconnect_error", (error) => {
  console.error("Reconnection error:", error);
});
```

### Event: 'reconnect_failed'

Fired when the client could not reconnect within the configured `reconnectionAttempts`.
```javascript
manager.io.on("reconnect_failed", () => {
  console.error("Failed to reconnect after multiple attempts.");
});
```
```

--------------------------------

### Handle Socket.IO Reconnection Errors

Source: https://socket.io/docs/v4/client-api

Listen for the 'reconnect_error' event to handle errors that occur during a reconnection attempt.

```javascript
socket.io.on("reconnect_error", (error) => {  
  // ...  
});  

```

--------------------------------

### Handle disconnection event

Source: https://socket.io/docs/v4/client-api

Triggered when the socket disconnects. The 'reason' parameter indicates why the disconnection occurred. Check socket.active to see if reconnection is automatic.

```javascript
socket.on("disconnect", (reason, details) => {  
  // ...  
});  
```

```javascript
socket.on("disconnect", (reason) => {  
  if (socket.active) {  
    // temporary disconnection, the socket will automatically try to reconnect  
  } else {  
    // the connection was forcefully closed by the server or the client itself  
    // in that case, `socket.connect()` must be manually called in order to reconnect  
    console.log(reason);  
  }  
});  
```

--------------------------------

### socket.listeners

Source: https://socket.io/docs/v4/client-api

Retrieves all listeners registered for a specific event.

```APIDOC
## socket.listeners(eventName)

### Description
Returns the array of listeners for the event named `eventName`. This method is inherited from the `EventEmitter` class.

### Method
`socket.listeners`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **eventName** (string | symbol) - The name of the event to get listeners for.

### Request Example
```javascript
socket.on("my-event", () => {
  // ...
});

console.log(socket.listeners("my-event")); // prints [ [Function] ]
```

### Response
#### Success Response (200)
- **Returns** (Function[]) - An array of listener functions.

#### Response Example
`[ [Function], [Function] ]`
```

--------------------------------

### Set Event Emission Timeout

Source: https://socket.io/docs/v4/client-api

Use `timeout` to set a delay for event acknowledgements. If the server does not acknowledge the event within the specified milliseconds, the callback will be invoked with an error.

```javascript
socket.timeout(5000).emit("my-event", (err) => {
  if (err) {
    // the server did not acknowledge the event in the given delay
  }
});

```

--------------------------------

### Check Socket Connection Status

Source: https://socket.io/docs/v4/client-api

socket.connected indicates if the socket is currently connected to the server. It is true when connected and false otherwise. The initial state is false before the 'connect' event.

```javascript
const socket = io();

console.log(socket.connected); // false

socket.on("connect", () => {
  console.log(socket.connected); // true
});
```

--------------------------------

### socket.once(eventName, callback)

Source: https://socket.io/docs/v4/client-api

Adds a listener function that will be invoked only once for the specified event. After the event is triggered, the listener is automatically removed.

```APIDOC
## socket.once(eventName, callback)

### Description
Adds a one-time listener function for the event named `eventName`. The next time `eventName` is triggered, this listener is removed and then invoked.

### Parameters
#### Path Parameters
* `eventName` (string | symbol) - The name of the event to listen for.
* `listener` (Function) - The callback function to execute once.

### Returns
* `<Socket>` - The socket instance for chaining.

### Request Example
```javascript
socket.once("my-event", () => {
  // ...
});
```
```

--------------------------------

### Flag: 'volatile'

Source: https://socket.io/docs/v4/client-api

Applies the 'volatile' flag to the next event emission. This indicates that the packet may be dropped if the socket is not connected or the transport is not writable.

```APIDOC
## Flag: 'volatile'

### Description
Sets a modifier for the subsequent event emission indicating that the packet may be dropped if:
  * the socket is not connected
  * the low-level transport is not writable (for example, when a `POST` request is already running in HTTP long-polling mode)

### Request Example
```javascript
socket.volatile.emit(/* ... */); // the server may or may not receive it
```
```

--------------------------------

### socket.timeout(value)

Source: https://socket.io/docs/v4/client-api

Sets a timeout for event emissions. If the server does not acknowledge the event within the specified milliseconds, the callback will be invoked with an error.

```APIDOC
## socket.timeout(value)

### Description
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.

### Parameters
#### Path Parameters
* `value` (number) - The timeout duration in milliseconds.

### Returns
* `<Socket>` - The socket instance for chaining.

### Request Example
```javascript
socket.timeout(5000).emit("my-event", (err) => {
  if (err) {
    // the server did not acknowledge the event in the given delay
  }
});
```
```

--------------------------------

### socket.off

Source: https://socket.io/docs/v4/client-api

Removes specified event listeners.

```APIDOC
## socket.off([eventName][, listener])

### Description
Removes the specified `listener` from the listener array for the event named `eventName`. This method is inherited from the `EventEmitter` class.

### Method
`socket.off`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **eventName** (string | symbol) - Optional. The name of the event to remove listeners from. If omitted, all listeners for all events are removed.
- **listener** (Function) - Optional. The specific listener function to remove. If omitted, all listeners for the specified `eventName` are removed.

### Request Example
```javascript
const myListener = () => {
  // ...
}

socket.on("my-event", myListener);

// then later
socket.off("my-event", myListener);

// remove all listeners for that event
socket.off("my-event");

// remove all listeners for all events
socket.off();
```

### Response
#### Success Response (200)
- **Returns** (Socket) - The Socket instance for chaining.

#### Response Example
(Returns the Socket instance)
```

--------------------------------

### socket.offAnyOutgoing

Source: https://socket.io/docs/v4/client-api

Removes catch-all listeners for outgoing packets.

```APIDOC
## socket.offAnyOutgoing([listener])

### Description
Removes the previously registered catch-all listener for outgoing packets. If no listener is provided, all catch-all listeners are removed. Added in v4.5.0.

### Method
`socket.offAnyOutgoing`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **listener** (Function) - Optional. The specific catch-all listener function to remove. If omitted, all catch-all listeners for outgoing packets are removed.

### Request Example
```javascript
const myListener = () => { /* ... */ };

socket.onAnyOutgoing(myListener);

// remove a single listener
socket.offAnyOutgoing(myListener);

// remove all listeners
socket.offAnyOutgoing();
```

### Response
#### Success Response (200)
(No specific return value mentioned, typically implies operation success)

#### Response Example
(No specific response body example)
```

--------------------------------

### Check Connection Recovery Status

Source: https://socket.io/docs/v4/client-api

socket.recovered indicates whether the connection state was successfully recovered during the last reconnection attempt. Use this to differentiate between a new session and a recovered one.

```javascript
socket.on("connect", () => {
  if (socket.recovered) {
    // any event missed during the disconnection period will be received now
  } else {
    // new or unrecoverable session
  }
});
```

--------------------------------

### Catch-all Listener Caveat

Source: https://socket.io/docs/v4/client-api

Illustrates that acknowledgements sent via socket.emit are not caught by socket.onAny, but socket.onAnyOutgoing will be triggered when the event is sent.

```javascript
socket.emit("foo", (value) => {
  // ...
});  

socket.onAnyOutgoing(() => {
  // triggered when the event is sent  
});  

socket.onAny(() => {
  // not triggered when the acknowledgement is received  
});  
```

--------------------------------

### Check Socket Reconnection Status

Source: https://socket.io/docs/v4/client-api

Use socket.active to determine if the socket will automatically attempt to reconnect after a connection failure or disconnection. If socket.active is false, manual reconnection via socket.connect() is required.

```javascript
socket.on("connect_error", (error) => {
  if (socket.active) {
    // temporary failure, the socket will automatically try to reconnect
  } else {
    // the connection was denied by the server
    // in that case, `socket.connect()` must be manually called in order to reconnect
    console.log(error.message);
  }
});
```

```javascript
socket.on("disconnect", (reason) => {
  if (socket.active) {
    // temporary disconnection, the socket will automatically try to reconnect
  } else {
    // the connection was forcefully closed by the server or the client itself
    // in that case, `socket.connect()` must be manually called in order to reconnect
    console.log(reason);
  }
});
```

--------------------------------

### Check Socket Disconnection Status

Source: https://socket.io/docs/v4/client-api

socket.disconnected indicates if the socket is currently disconnected from the server. It is true when disconnected and false otherwise. The initial state is true before the 'connect' event.

```javascript
const socket = io();

console.log(socket.disconnected); // true

socket.on("connect", () => {
  console.log(socket.disconnected); // false
});
```

--------------------------------

### Remove Catch-all Listener

Source: https://socket.io/docs/v4/client-api

Removes a previously registered catch-all listener. If no listener is provided, all catch-all listeners are removed.

```javascript
const myListener = () => { /* ... */ };

socket.onAny(myListener);

// then, later
socket.offAny(myListener);

socket.offAny();  
```

--------------------------------

### Manually Disconnect Socket

Source: https://socket.io/docs/v4/client-api

socket.disconnect() manually disconnects the socket and prevents automatic reconnection attempts. This method returns the Socket instance for chaining.

```javascript
socket.disconnect();
```
Tokens:
Raw