@stomp/stompjs 7.1.1 → 7.2.0

package/esm6/client.js

@@ -5,16 +5,52 @@ import { Versions } from './versions.js';
  * STOMP Client Class.
  *
  * Part of `@stomp/stompjs`.
+ *
+ * This class provides a robust implementation for connecting to and interacting with a
+ * STOMP-compliant messaging broker over WebSocket. It supports STOMP versions 1.2, 1.1, and 1.0.
+ *
+ * Features:
+ * - Handles automatic reconnections.
+ * - Supports heartbeat mechanisms to detect and report communication failures.
+ * - Allows customization of connection and WebSocket behaviors through configurations.
+ * - Compatible with both browser environments and Node.js with polyfill support for WebSocket.
  */
 export class Client {
     /**
-     * Underlying WebSocket instance, READONLY.
+     * Provides access to the underlying WebSocket instance.
+     * This property is **read-only**.
+     *
+     * Example:
+     * ```javascript
+     * const webSocket = client.webSocket;
+     * if (webSocket) {
+     *   console.log('WebSocket is connected:', webSocket.readyState === WebSocket.OPEN);
+     * }
+     * ```
+     *
+     * **Caution:**
+     * Directly interacting with the WebSocket instance (e.g., sending or receiving frames)
+     * can interfere with the proper functioning of this library. Such actions may cause
+     * unexpected behavior, disconnections, or invalid state in the library's internal mechanisms.
+     *
+     * Instead, use the library's provided methods to manage STOMP communication.
+     *
+     * @returns The WebSocket instance used by the STOMP handler, or `undefined` if not connected.
      */
     get webSocket() {
         return this._stompHandler?._webSocket;
     }
     /**
-     * Disconnection headers.
+     * Allows customization of the disconnection headers.
+     *
+     * Any changes made during an active session will also be applied immediately.
+     *
+     * Example:
+     * ```javascript
+     * client.disconnectHeaders = {
+     *   receipt: 'custom-receipt-id'
+     * };
+     * ```
      */
     get disconnectHeaders() {
         return this._disconnectHeaders;
@@ -26,19 +62,53 @@ export class Client {
         }
     }
     /**
-     * `true` if there is an active connection to STOMP Broker
+     * Indicates whether there is an active connection to the STOMP broker.
+     *
+     * Usage:
+     * ```javascript
+     * if (client.connected) {
+     *   console.log('Client is connected to the broker.');
+     * } else {
+     *   console.log('No connection to the broker.');
+     * }
+     * ```
+     *
+     * @returns `true` if the client is currently connected, `false` otherwise.
      */
     get connected() {
         return !!this._stompHandler && this._stompHandler.connected;
     }
     /**
-     * version of STOMP protocol negotiated with the server, READONLY
+     * The version of the STOMP protocol negotiated with the server during connection.
+     *
+     * This is a **read-only** property and reflects the negotiated protocol version after
+     * a successful connection.
+     *
+     * Example:
+     * ```javascript
+     * console.log('Connected STOMP version:', client.connectedVersion);
+     * ```
+     *
+     * @returns The negotiated STOMP protocol version or `undefined` if not connected.
      */
     get connectedVersion() {
         return this._stompHandler ? this._stompHandler.connectedVersion : undefined;
     }
     /**
-     * if the client is active (connected or going to reconnect)
+     * Indicates whether the client is currently active.
+     *
+     * A client is considered active if it is connected or actively attempting to reconnect.
+     *
+     * Example:
+     * ```javascript
+     * if (client.active) {
+     *   console.log('The client is active.');
+     * } else {
+     *   console.log('The client is inactive.');
+     * }
+     * ```
+     *
+     * @returns `true` if the client is active, otherwise `false`.
      */
     get active() {
         return this.state === ActivationState.ACTIVE;
@@ -48,129 +118,217 @@ export class Client {
         this.onChangeState(state);
     }
     /**
-     * Create an instance.
+     * Constructs a new STOMP client instance.
+     *
+     * The constructor initializes default values and sets up no-op callbacks for all events.
+     * Configuration can be passed during construction, or updated later using `configure`.
+     *
+     * Example:
+     * ```javascript
+     * const client = new Client({
+     *   brokerURL: 'wss://broker.example.com',
+     *   reconnectDelay: 5000
+     * });
+     * ```
+     *
+     * @param conf Optional configuration object to initialize the client with.
      */
     constructor(conf = {}) {
         /**
-         * STOMP versions to attempt during STOMP handshake. By default, versions `1.2`, `1.1`, and `1.0` are attempted.
+         * STOMP protocol versions to use during the handshake. By default, the client will attempt
+         * versions `1.2`, `1.1`, and `1.0` in descending order of preference.
          *
          * Example:
          * ```javascript
-         *        // Try only versions 1.1 and 1.0
-         *        client.stompVersions = new Versions(['1.1', '1.0'])
+         * // Configure the client to only use versions 1.1 and 1.0
+         * client.stompVersions = new Versions(['1.1', '1.0']);
          * ```
          */
         this.stompVersions = Versions.default;
         /**
-         * Will retry if Stomp connection is not established in specified milliseconds.
-         * Default 0, which switches off automatic reconnection.
+         * Timeout for establishing STOMP connection, in milliseconds.
+         *
+         * If the connection is not established within this period, the attempt will fail.
+         * The default is `0`, meaning no timeout is set for connection attempts.
+         *
+         * Example:
+         * ```javascript
+         * client.connectionTimeout = 5000; // Fail connection if not established in 5 seconds
+         * ```
          */
         this.connectionTimeout = 0;
         /**
-         *  automatically reconnect with delay in milliseconds, set to 0 to disable.
+         * Delay (in milliseconds) between reconnection attempts if the connection drops.
+         *
+         * Set to `0` to disable automatic reconnections. The default value is `5000` ms (5 seconds).
+         *
+         * Example:
+         * ```javascript
+         * client.reconnectDelay = 3000; // Attempt reconnection every 3 seconds
+         * client.reconnectDelay = 0; // Disable automatic reconnection
+         * ```
          */
         this.reconnectDelay = 5000;
         /**
-         * tracking the time to the next reconnection. Initialized to [Client#reconnectDelay]{@link Client#reconnectDelay}'s value and it may
-         * change depending on the [Client#reconnectTimeMode]{@link Client#reconnectTimeMode} setting
+         * The next reconnection delay, used internally.
+         * Initialized to the value of [Client#reconnectDelay]{@link Client#reconnectDelay}, and it may
+         * dynamically change based on [Client#reconnectTimeMode]{@link Client#reconnectTimeMode}.
          */
         this._nextReconnectDelay = 0;
         /**
-         * Maximum time to wait between reconnects, in milliseconds. Defaults to 15 minutes.
-         * Only relevant when [Client#reconnectTimeMode]{@link Client#reconnectTimeMode} not LINEAR (e.g., EXPONENTIAL).
-         * Set to 0 for no limit on wait time.
+         * Maximum delay (in milliseconds) between reconnection attempts when using exponential backoff.
+         *
+         * Default is 15 minutes (`15 * 60 * 1000` milliseconds). If `0`, there will be no upper limit.
+         *
+         * Example:
+         * ```javascript
+         * client.maxReconnectDelay = 10000; // Maximum wait time is 10 seconds
+         * ```
          */
-        this.maxReconnectDelay = 15 * 60 * 1000; // 15 minutes in ms
+        this.maxReconnectDelay = 15 * 60 * 1000;
         /**
-         * Reconnection wait time mode, either linear (default) or exponential.
-         * Note: See [Client#maxReconnectDelay]{@link Client#maxReconnectDelay} for setting the maximum delay when exponential
+         * Mode for determining the time interval between reconnection attempts.
+         *
+         * Available modes:
+         * - `ReconnectionTimeMode.LINEAR` (default): Fixed delays between reconnection attempts.
+         * - `ReconnectionTimeMode.EXPONENTIAL`: Delay doubles after each attempt, capped by [maxReconnectDelay]{@link Client#maxReconnectDelay}.
          *
+         * Example:
          * ```javascript
-         * client.configure({
-         *   reconnectTimeMode: ReconnectionTimeMode.EXPONENTIAL,
-         *   reconnectDelay: 200, // It will wait 200, 400, 800 ms...
-         *   maxReconnectDelay: 10000, // Optional, when provided, it will not wait more that these ms
-         * })
+         * client.reconnectTimeMode = ReconnectionTimeMode.EXPONENTIAL;
+         * client.reconnectDelay = 200; // Initial delay of 200 ms, doubles with each attempt
+         * client.maxReconnectDelay = 2 * 60 * 1000; // Cap delay at 10 minutes
          * ```
          */
         this.reconnectTimeMode = ReconnectionTimeMode.LINEAR;
         /**
-         * Incoming heartbeat interval in milliseconds. Set to 0 to disable.
+         * Interval (in milliseconds) for receiving heartbeat signals from the server.
+         *
+         * Specifies the expected frequency of heartbeats sent by the server. Set to `0` to disable.
+         *
+         * Example:
+         * ```javascript
+         * client.heartbeatIncoming = 10000; // Expect a heartbeat every 10 seconds
+         * ```
          */
         this.heartbeatIncoming = 10000;
         /**
-         * Outgoing heartbeat interval in milliseconds. Set to 0 to disable.
+         * Multiplier for adjusting tolerance when processing heartbeat signals.
+         *
+         * Tolerance level is calculated using the multiplier:
+         * `tolerance = heartbeatIncoming * heartbeatToleranceMultiplier`.
+         * This helps account for delays in network communication or variations in timings.
+         *
+         * Default value is `2`.
+         *
+         * Example:
+         * ```javascript
+         * client.heartbeatToleranceMultiplier = 2.5; // Tolerates longer delays
+         * ```
+         */
+        this.heartbeatToleranceMultiplier = 2;
+        /**
+         * Interval (in milliseconds) for sending heartbeat signals to the server.
+         *
+         * Specifies how frequently heartbeats should be sent to the server. Set to `0` to disable.
+         *
+         * Example:
+         * ```javascript
+         * client.heartbeatOutgoing = 5000; // Send a heartbeat every 5 seconds
+         * ```
          */
         this.heartbeatOutgoing = 10000;
         /**
-         * Outgoing heartbeat strategy.
-         * See https://github.com/stomp-js/stompjs/pull/579
-         *
-         * Can be worker or interval strategy, but will always use `interval`
-         * if web workers are unavailable, for example, in a non-browser environment.
+         * Strategy for sending outgoing heartbeats.
          *
-         * Using Web Workers may work better on long-running pages
-         * and mobile apps, as the browser may suspend Timers in the main page.
-         * Try the `Worker` mode if you discover disconnects when the browser tab is in the background.
+         * Options:
+         * - `TickerStrategy.Worker`: Uses Web Workers for sending heartbeats (recommended for long-running or background sessions).
+         * - `TickerStrategy.Interval`: Uses standard JavaScript `setInterval` (default).
          *
-         * When used in a JS environment, use 'worker' or 'interval' as valid values.
+         * Note:
+         * - If Web Workers are unavailable (e.g., in Node.js), the `Interval` strategy is used automatically.
+         * - Web Workers are preferable in browsers for reducing disconnects when tabs are in the background.
          *
-         * Defaults to `interval` strategy.
+         * Example:
+         * ```javascript
+         * client.heartbeatStrategy = TickerStrategy.Worker;
+         * ```
          */
         this.heartbeatStrategy = TickerStrategy.Interval;
         /**
-         * This switches on a non-standard behavior while sending WebSocket packets.
-         * It splits larger (text) packets into chunks of [maxWebSocketChunkSize]{@link Client#maxWebSocketChunkSize}.
-         * Only Java Spring brokers seem to support this mode.
+         * Enables splitting of large text WebSocket frames into smaller chunks.
          *
-         * WebSockets, by itself, split large (text) packets,
-         * so it is not needed with a truly compliant STOMP/WebSocket broker.
-         * Setting it for such a broker will cause large messages to fail.
+         * This setting is enabled for brokers that support only chunked messages (e.g., Java Spring-based brokers).
+         * Default is `false`.
          *
-         * `false` by default.
+         * Warning:
+         * - Should not be used with WebSocket-compliant brokers, as chunking may cause large message failures.
+         * - Binary WebSocket frames are never split.
          *
-         * Binary frames are never split.
+         * Example:
+         * ```javascript
+         * client.splitLargeFrames = true;
+         * client.maxWebSocketChunkSize = 4096; // Allow chunks of 4 KB
+         * ```
          */
         this.splitLargeFrames = false;
         /**
-         * See [splitLargeFrames]{@link Client#splitLargeFrames}.
-         * This has no effect if [splitLargeFrames]{@link Client#splitLargeFrames} is `false`.
+         * Maximum size (in bytes) for individual WebSocket chunks if [splitLargeFrames]{@link Client#splitLargeFrames} is enabled.
+         *
+         * Default is 8 KB (`8 * 1024` bytes). This value has no effect if [splitLargeFrames]{@link Client#splitLargeFrames} is `false`.
          */
         this.maxWebSocketChunkSize = 8 * 1024;
         /**
-         * Usually the
-         * [type of WebSocket frame]{@link https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send#Parameters}
-         * is automatically decided by type of the payload.
-         * Default is `false`, which should work with all compliant brokers.
+         * Forces all WebSocket frames to use binary transport, irrespective of payload type.
+         *
+         * Default behavior determines frame type based on payload (e.g., binary data for ArrayBuffers).
          *
-         * Set this flag to force binary frames.
+         * Example:
+         * ```javascript
+         * client.forceBinaryWSFrames = true;
+         * ```
          */
         this.forceBinaryWSFrames = false;
         /**
-         * A bug in ReactNative chops a string on occurrence of a NULL.
-         * See issue [https://github.com/stomp-js/stompjs/issues/89]{@link https://github.com/stomp-js/stompjs/issues/89}.
-         * This makes incoming WebSocket messages invalid STOMP packets.
-         * Setting this flag attempts to reverse the damage by appending a NULL.
-         * If the broker splits a large message into multiple WebSocket messages,
-         * this flag will cause data loss and abnormal termination of connection.
-         *
-         * This is not an ideal solution, but a stop gap until the underlying issue is fixed at ReactNative library.
+         * Workaround for a React Native WebSocket bug, where messages containing `NULL` are chopped.
+         *
+         * Enabling this appends a `NULL` character to incoming frames to ensure they remain valid STOMP packets.
+         *
+         * Warning:
+         * - For brokers that split large messages, this may cause data loss or connection termination.
+         *
+         * Example:
+         * ```javascript
+         * client.appendMissingNULLonIncoming = true;
+         * ```
          */
         this.appendMissingNULLonIncoming = false;
         /**
-         * Browsers do not immediately close WebSockets when `.close` is issued.
-         * This may cause reconnection to take a significantly long time in case
-         *  of some types of failures.
-         * In case of incoming heartbeat failure, this experimental flag instructs
-         * the library to discard the socket immediately
-         * (even before it is actually closed).
+         * Instruct the library to immediately terminate the socket on communication failures, even
+         * before the WebSocket is completely closed.
+         *
+         * This is particularly useful in browser environments where WebSocket closure may get delayed,
+         * causing prolonged reconnection intervals under certain failure conditions.
+         *
+         *
+         * Example:
+         * ```javascript
+         * client.discardWebsocketOnCommFailure = true; // Enable aggressive closing of WebSocket
+         * ```
+         *
+         * Default value: `false`.
          */
         this.discardWebsocketOnCommFailure = false;
         /**
-         * Activation state.
+         * Current activation state of the client.
+         *
+         * Possible states:
+         * - `ActivationState.ACTIVE`: Client is connected or actively attempting to connect.
+         * - `ActivationState.INACTIVE`: Client is disconnected and not attempting to reconnect.
+         * - `ActivationState.DEACTIVATING`: Client is in the process of disconnecting.
          *
-         * It will usually be ACTIVE or INACTIVE.
-         * When deactivating, it may go from ACTIVE to INACTIVE without entering DEACTIVATING.
+         * Note: The client may transition directly from `ACTIVE` to `INACTIVE` without entering
+         * the `DEACTIVATING` state.
          */
         this.state = ActivationState.INACTIVE;
         // No op callbacks
@@ -182,6 +340,8 @@ export class Client {
         this.onUnhandledMessage = noOp;
         this.onUnhandledReceipt = noOp;
         this.onUnhandledFrame = noOp;
+        this.onHeartbeatReceived = noOp;
+        this.onHeartbeatLost = noOp;
         this.onStompError = noOp;
         this.onWebSocketClose = noOp;
         this.onWebSocketError = noOp;
@@ -194,7 +354,22 @@ export class Client {
         this.configure(conf);
     }
     /**
-     * Update configuration.
+     * Updates the client's configuration.
+     *
+     * All properties in the provided configuration object will override the current settings.
+     *
+     * Additionally, a warning is logged if `maxReconnectDelay` is configured to a
+     * value lower than `reconnectDelay`, and `maxReconnectDelay` is adjusted to match `reconnectDelay`.
+     *
+     * Example:
+     * ```javascript
+     * client.configure({
+     *   reconnectDelay: 3000,
+     *   maxReconnectDelay: 10000
+     * });
+     * ```
+     *
+     * @param conf Configuration object containing the new settings.
      */
     configure(conf) {
         // bulk assign all properties to this
@@ -207,12 +382,20 @@ export class Client {
         }
     }
     /**
-     * Initiate the connection with the broker.
-     * If the connection breaks, as per [Client#reconnectDelay]{@link Client#reconnectDelay},
-     * it will keep trying to reconnect. If the [Client#reconnectTimeMode]{@link Client#reconnectTimeMode}
-     * is set to EXPONENTIAL it will increase the wait time exponentially
+     * Activates the client, initiating a connection to the STOMP broker.
+     *
+     * On activation, the client attempts to connect and sets its state to `ACTIVE`. If the connection
+     * is lost, it will automatically retry based on `reconnectDelay` or `maxReconnectDelay`. If
+     * `reconnectTimeMode` is set to `EXPONENTIAL`, the reconnect delay increases exponentially.
+     *
+     * To stop reconnection attempts and disconnect, call [Client#deactivate]{@link Client#deactivate}.
+     *
+     * Example:
+     * ```javascript
+     * client.activate(); // Connect to the broker
+     * ```
      *
-     * Call [Client#deactivate]{@link Client#deactivate} to disconnect and stop reconnection attempts.
+     * If the client is currently `DEACTIVATING`, connection is delayed until the deactivation process completes.
      */
     activate() {
         const _activate = () => {
@@ -270,6 +453,7 @@ export class Client {
             connectHeaders: this.connectHeaders,
             disconnectHeaders: this._disconnectHeaders,
             heartbeatIncoming: this.heartbeatIncoming,
+            heartbeatGracePeriods: this.heartbeatToleranceMultiplier,
             heartbeatOutgoing: this.heartbeatOutgoing,
             heartbeatStrategy: this.heartbeatStrategy,
             splitLargeFrames: this.splitLargeFrames,
@@ -322,6 +506,12 @@ export class Client {
             onUnhandledFrame: frame => {
                 this.onUnhandledFrame(frame);
             },
+            onHeartbeatReceived: () => {
+                this.onHeartbeatReceived();
+            },
+            onHeartbeatLost: () => {
+                this.onHeartbeatLost();
+            },
         });
         this._stompHandler.start();
     }
@@ -355,27 +545,36 @@ export class Client {
         }
     }
     /**
-     * Disconnect if connected and stop auto reconnect loop.
-     * Appropriate callbacks will be invoked if there is an underlying STOMP connection.
+     * Disconnects the client and stops the automatic reconnection loop.
+     *
+     * If there is an active STOMP connection at the time of invocation, the appropriate callbacks
+     * will be triggered during the shutdown sequence. Once deactivated, the client will enter the
+     * `INACTIVE` state, and no further reconnection attempts will be made.
      *
-     * This call is async. It will resolve immediately if there is no underlying active websocket,
-     * otherwise, it will resolve after the underlying websocket is properly disposed of.
+     * **Behavior**:
+     * - If there is no active WebSocket connection, this method resolves immediately.
+     * - If there is an active connection, the method waits for the underlying WebSocket
+     *   to properly close before resolving.
+     * - Multiple calls to this method are safe. Each invocation resolves upon completion.
+     * - To reactivate, call [Client#activate]{@link Client#activate}.
      *
-     * It is not an error to invoke this method more than once.
-     * Each of those would resolve on completion of deactivation.
+     * **Experimental Option:**
+     * - By specifying the `force: true` option, the WebSocket connection is discarded immediately,
+     *   bypassing both the STOMP and WebSocket shutdown sequences.
+     * - **Caution:** Using `force: true` may leave the WebSocket in an inconsistent state,
+     *   and brokers may not immediately detect the termination.
      *
-     * To reactivate, you can call [Client#activate]{@link Client#activate}.
+     * Example:
+     * ```javascript
+     * // Graceful disconnect
+     * await client.deactivate();
      *
-     * Experimental: pass `force: true` to immediately discard the underlying connection.
-     * This mode will skip both the STOMP and the Websocket shutdown sequences.
-     * In some cases, browsers take a long time in the Websocket shutdown
-     * if the underlying connection had gone stale.
-     * Using this mode can speed up.
-     * When this mode is used, the actual Websocket may linger for a while
-     * and the broker may not realize that the connection is no longer in use.
+     * // Forced disconnect to speed up shutdown when the connection is stale
+     * await client.deactivate({ force: true });
+     * ```
      *
-     * It is possible to invoke this method initially without the `force` option
-     * and subsequently, say after a wait, with the `force` option.
+     * @param options Configuration options for deactivation. Use `force: true` for immediate shutdown.
+     * @returns A Promise that resolves when the deactivation process completes.
      */
     async deactivate(options = {}) {
         const force = options.force || false;
@@ -420,10 +619,18 @@ export class Client {
         return retPromise;
     }
     /**
-     * Force disconnect if there is an active connection by directly closing the underlying WebSocket.
-     * This is different from a normal disconnect where a DISCONNECT sequence is carried out with the broker.
-     * After forcing disconnect, automatic reconnect will be attempted.
-     * To stop further reconnects call [Client#deactivate]{@link Client#deactivate} as well.
+     * Forces a disconnect by directly closing the WebSocket.
+     *
+     * Unlike a normal disconnect, this does not send a DISCONNECT sequence to the broker but
+     * instead closes the WebSocket connection directly. After forcing a disconnect, the client
+     * will automatically attempt to reconnect based on its `reconnectDelay` configuration.
+     *
+     * **Note:** To prevent further reconnect attempts, call [Client#deactivate]{@link Client#deactivate}.
+     *
+     * Example:
+     * ```javascript
+     * client.forceDisconnect();
+     * ```
      */
     forceDisconnect() {
         if (this._stompHandler) {
@@ -437,39 +644,38 @@ export class Client {
         }
     }
     /**
-     * Send a message to a named destination. Refer to your STOMP broker documentation for types
-     * and naming of destinations.
-     *
-     * STOMP protocol specifies and suggests some headers and also allows broker-specific headers.
+     * Sends a message to the specified destination on the STOMP broker.
      *
-     * `body` must be String.
-     * You will need to covert the payload to string in case it is not string (e.g. JSON).
+     * The `body` must be a `string`. For non-string payloads (e.g., JSON), encode it as a string before sending.
+     * If sending binary data, use the `binaryBody` parameter as a [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array).
      *
-     * To send a binary message body, use `binaryBody` parameter. It should be a
-     * [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array).
-     * Sometimes brokers may not support binary frames out of the box.
-     * Please check your broker documentation.
+     * **Content-Length Behavior**:
+     * - For non-binary messages, the `content-length` header is added by default.
+     * - The `content-length` header can be skipped for text frames by setting `skipContentLengthHeader: true` in the parameters.
+     * - For binary messages, the `content-length` header is always included.
      *
-     * `content-length` header is automatically added to the STOMP Frame sent to the broker.
-     * Set `skipContentLengthHeader` to indicate that `content-length` header should not be added.
-     * For binary messages, `content-length` header is always added.
-     *
-     * Caution: The broker will, most likely, report an error and disconnect
-     * if the message body has NULL octet(s) and `content-length` header is missing.
+     * **Notes**:
+     * - Ensure that brokers support binary frames before using `binaryBody`.
+     * - Sending messages with NULL octets and missing `content-length` headers can cause brokers to disconnect and throw errors.
      *
+     * Example:
      * ```javascript
-     *        client.publish({destination: "/queue/test", headers: {priority: 9}, body: "Hello, STOMP"});
-     *
-     *        // Only destination is mandatory parameter
-     *        client.publish({destination: "/queue/test", body: "Hello, STOMP"});
-     *
-     *        // Skip content-length header in the frame to the broker
-     *        client.publish({"/queue/test", body: "Hello, STOMP", skipContentLengthHeader: true});
-     *
-     *        var binaryData = generateBinaryData(); // This need to be of type Uint8Array
-     *        // setting content-type header is not mandatory, however a good practice
-     *        client.publish({destination: '/topic/special', binaryBody: binaryData,
-     *                         headers: {'content-type': 'application/octet-stream'}});
+     * // Basic text message
+     * client.publish({ destination: "/queue/test", body: "Hello, STOMP" });
+     *
+     * // Text message with additional headers
+     * client.publish({ destination: "/queue/test", headers: { priority: 9 }, body: "Hello, STOMP" });
+     *
+     * // Skip content-length header
+     * client.publish({ destination: "/queue/test", body: "Hello, STOMP", skipContentLengthHeader: true });
+     *
+     * // Binary message
+     * const binaryData = new Uint8Array([1, 2, 3, 4]);
+     * client.publish({
+     *   destination: '/topic/special',
+     *   binaryBody: binaryData,
+     *   headers: { 'content-type': 'application/octet-stream' }
+     * });
      * ```
      */
     publish(params) {
@@ -483,39 +689,27 @@ export class Client {
         }
     }
     /**
-     * STOMP brokers may carry out operation asynchronously and allow requesting for acknowledgement.
-     * To request an acknowledgement, a `receipt` header needs to be sent with the actual request.
-     * The value (say receipt-id) for this header needs to be unique for each use.
-     * Typically, a sequence, a UUID, a random number or a combination may be used.
+     * Monitors for a receipt acknowledgment from the broker for specific operations.
      *
-     * A complaint broker will send a RECEIPT frame when an operation has actually been completed.
-     * The operation needs to be matched based on the value of the receipt-id.
+     * Add a `receipt` header to the operation (like subscribe or publish), and use this method with
+     * the same receipt ID to detect when the broker has acknowledged the operation's completion.
      *
-     * This method allows watching for a receipt and invoking the callback
-     *  when the corresponding receipt has been received.
-     *
-     * The actual {@link IFrame} will be passed as parameter to the callback.
+     * The callback is invoked with the corresponding {@link IFrame} when the receipt is received.
      *
      * Example:
      * ```javascript
-     *        // Subscribing with acknowledgement
-     *        let receiptId = randomText();
-     *
-     *        client.watchForReceipt(receiptId, function() {
-     *          // Will be called after server acknowledges
-     *        });
+     * const receiptId = "unique-receipt-id";
      *
-     *        client.subscribe(TEST.destination, onMessage, {receipt: receiptId});
+     * client.watchForReceipt(receiptId, (frame) => {
+     *   console.log("Operation acknowledged by the broker:", frame);
+     * });
      *
-     *
-     *        // Publishing with acknowledgement
-     *        receiptId = randomText();
-     *
-     *        client.watchForReceipt(receiptId, function() {
-     *          // Will be called after server acknowledges
-     *        });
-     *        client.publish({destination: TEST.destination, headers: {receipt: receiptId}, body: msg});
+     * // Attach the receipt header to an operation
+     * client.publish({ destination: "/queue/test", headers: { receipt: receiptId }, body: "Hello" });
      * ```
+     *
+     * @param receiptId Unique identifier for the receipt.
+     * @param callback Callback function invoked on receiving the RECEIPT frame.
      */
     watchForReceipt(receiptId, callback) {
         this._checkConnection();
@@ -523,28 +717,33 @@ export class Client {
         this._stompHandler.watchForReceipt(receiptId, callback);
     }
     /**
-     * Subscribe to a STOMP Broker location. The callback will be invoked for each
-     * received message with the {@link IMessage} as argument.
+     * Subscribes to a destination on the STOMP broker.
      *
-     * Note: The library will generate a unique ID if there is none provided in the headers.
-     *       To use your own ID, pass it using the `headers` argument.
+     * The callback is triggered for each message received from the subscribed destination. The message
+     * is passed as an {@link IMessage} instance.
      *
+     * **Subscription ID**:
+     * - If no `id` is provided in `headers`, the library generates a unique subscription ID automatically.
+     * - Provide an explicit `id` in `headers` if you wish to manage the subscription ID manually.
+     *
+     * Example:
      * ```javascript
-     *        callback = function(message) {
-     *        // called when the client receives a STOMP message from the server
-     *          if (message.body) {
-     *            alert("got message with body " + message.body)
-     *          } else {
-     *            alert("got empty message");
-     *          }
-     *        });
-     *
-     *        var subscription = client.subscribe("/queue/test", callback);
-     *
-     *        // Explicit subscription id
-     *        var mySubId = 'my-subscription-id-001';
-     *        var subscription = client.subscribe(destination, callback, { id: mySubId });
+     * const callback = (message) => {
+     *   console.log("Received message:", message.body);
+     * };
+     *
+     * // Auto-generated subscription ID
+     * const subscription = client.subscribe("/queue/test", callback);
+     *
+     * // Explicit subscription ID
+     * const mySubId = "my-subscription-id";
+     * const subscription = client.subscribe("/queue/test", callback, { id: mySubId });
      * ```
+     *
+     * @param destination Destination to subscribe to.
+     * @param callback Function invoked for each received message.
+     * @param headers Optional headers for subscription, such as `id`.
+     * @returns A {@link StompSubscription} which can be used to manage the subscription.
      */
     subscribe(destination, callback, headers = {}) {
         this._checkConnection();
@@ -552,16 +751,24 @@ export class Client {
         return this._stompHandler.subscribe(destination, callback, headers);
     }
     /**
-     * It is preferable to unsubscribe from a subscription by calling
-     * `unsubscribe()` directly on {@link StompSubscription} returned by `client.subscribe()`:
+     * Unsubscribes from a subscription on the STOMP broker.
      *
+     * Prefer using the `unsubscribe` method directly on the {@link StompSubscription} returned from `subscribe` for cleaner management:
      * ```javascript
-     *        var subscription = client.subscribe(destination, onmessage);
-     *        // ...
-     *        subscription.unsubscribe();
+     * const subscription = client.subscribe("/queue/test", callback);
+     * // Unsubscribe using the subscription object
+     * subscription.unsubscribe();
      * ```
      *
-     * See: https://stomp.github.com/stomp-specification-1.2.html#UNSUBSCRIBE UNSUBSCRIBE Frame
+     * This method can also be used directly with the subscription ID.
+     *
+     * Example:
+     * ```javascript
+     * client.unsubscribe("my-subscription-id");
+     * ```
+     *
+     * @param id Subscription ID to unsubscribe.
+     * @param headers Optional headers to pass for the UNSUBSCRIBE frame.
      */
     unsubscribe(id, headers = {}) {
         this._checkConnection();
@@ -569,10 +776,21 @@ export class Client {
         this._stompHandler.unsubscribe(id, headers);
     }
     /**
-     * Start a transaction, the returned {@link ITransaction} has methods - [commit]{@link ITransaction#commit}
-     * and [abort]{@link ITransaction#abort}.
+     * Starts a new transaction. The returned {@link ITransaction} object provides
+     * methods for [commit]{@link ITransaction#commit} and [abort]{@link ITransaction#abort}.
+     *
+     * If `transactionId` is not provided, the library generates a unique ID internally.
+     *
+     * Example:
+     * ```javascript
+     * const tx = client.begin(); // Auto-generated ID
      *
-     * `transactionId` is optional, if not passed the library will generate it internally.
+     * // Or explicitly specify a transaction ID
+     * const tx = client.begin("my-transaction-id");
+     * ```
+     *
+     * @param transactionId Optional transaction ID.
+     * @returns An instance of {@link ITransaction}.
      */
     begin(transactionId) {
         this._checkConnection();
@@ -580,16 +798,19 @@ export class Client {
         return this._stompHandler.begin(transactionId);
     }
     /**
-     * Commit a transaction.
+     * Commits a transaction.
      *
-     * It is preferable to commit a transaction by calling [commit]{@link ITransaction#commit} directly on
-     * {@link ITransaction} returned by [client.begin]{@link Client#begin}.
+     * It is strongly recommended to call [commit]{@link ITransaction#commit} on
+     * the transaction object returned by [client#begin]{@link Client#begin}.
      *
+     * Example:
      * ```javascript
-     *        var tx = client.begin(txId);
-     *        //...
-     *        tx.commit();
+     * const tx = client.begin();
+     * // Perform operations under this transaction
+     * tx.commit();
      * ```
+     *
+     * @param transactionId The ID of the transaction to commit.
      */
     commit(transactionId) {
         this._checkConnection();
@@ -597,15 +818,19 @@ export class Client {
         this._stompHandler.commit(transactionId);
     }
     /**
-     * Abort a transaction.
-     * It is preferable to abort a transaction by calling [abort]{@link ITransaction#abort} directly on
-     * {@link ITransaction} returned by [client.begin]{@link Client#begin}.
+     * Aborts a transaction.
+     *
+     * It is strongly recommended to call [abort]{@link ITransaction#abort} directly
+     * on the transaction object returned by [client#begin]{@link Client#begin}.
      *
+     * Example:
      * ```javascript
-     *        var tx = client.begin(txId);
-     *        //...
-     *        tx.abort();
+     * const tx = client.begin();
+     * // Perform operations under this transaction
+     * tx.abort(); // Abort the transaction
      * ```
+     *
+     * @param transactionId The ID of the transaction to abort.
      */
     abort(transactionId) {
         this._checkConnection();
@@ -613,17 +838,23 @@ export class Client {
         this._stompHandler.abort(transactionId);
     }
     /**
-     * ACK a message. It is preferable to acknowledge a message by calling [ack]{@link IMessage#ack} directly
-     * on the {@link IMessage} handled by a subscription callback:
+     * Acknowledges receipt of a message. Typically, this should be done by calling
+     * [ack]{@link IMessage#ack} directly on the {@link IMessage} instance passed
+     * to the subscription callback.
      *
+     * Example:
      * ```javascript
-     *        var callback = function (message) {
-     *          // process the message
-     *          // acknowledge it
-     *          message.ack();
-     *        };
-     *        client.subscribe(destination, callback, {'ack': 'client'});
+     * const callback = (message) => {
+     *   // Process the message
+     *   message.ack(); // Acknowledge the message
+     * };
+     *
+     * client.subscribe("/queue/example", callback, { ack: "client" });
      * ```
+     *
+     * @param messageId The ID of the message to acknowledge.
+     * @param subscriptionId The ID of the subscription.
+     * @param headers Optional headers for the acknowledgment frame.
      */
     ack(messageId, subscriptionId, headers = {}) {
         this._checkConnection();
@@ -631,17 +862,25 @@ export class Client {
         this._stompHandler.ack(messageId, subscriptionId, headers);
     }
     /**
-     * NACK a message. It is preferable to acknowledge a message by calling [nack]{@link IMessage#nack} directly
-     * on the {@link IMessage} handled by a subscription callback:
+     * Rejects a message (negative acknowledgment). Like acknowledgments, this should
+     * typically be done by calling [nack]{@link IMessage#nack} directly on the {@link IMessage}
+     * instance passed to the subscription callback.
      *
+     * Example:
      * ```javascript
-     *        var callback = function (message) {
-     *          // process the message
-     *          // an error occurs, nack it
-     *          message.nack();
-     *        };
-     *        client.subscribe(destination, callback, {'ack': 'client'});
+     * const callback = (message) => {
+     *   // Process the message
+     *   if (isError(message)) {
+     *     message.nack(); // Reject the message
+     *   }
+     * };
+     *
+     * client.subscribe("/queue/example", callback, { ack: "client" });
      * ```
+     *
+     * @param messageId The ID of the message to negatively acknowledge.
+     * @param subscriptionId The ID of the subscription.
+     * @param headers Optional headers for the NACK frame.
      */
     nack(messageId, subscriptionId, headers = {}) {
         this._checkConnection();