@stomp/stompjs 7.1.0 → 7.2.0

package/bundles/stomp.umd.js

@@ -499,13 +499,13 @@
             this.disposeInterval();
         }
         shouldUseWorker() {
-            return typeof (Worker) !== 'undefined' && this._strategy === exports.TickerStrategy.Worker;
+            return (typeof Worker !== 'undefined' && this._strategy === exports.TickerStrategy.Worker);
         }
         runWorker(tick) {
             this._debug('Using runWorker for outgoing pings');
             if (!this._worker) {
                 this._worker = new Worker(URL.createObjectURL(new Blob([this._workerScript], { type: 'text/javascript' })));
-                this._worker.onmessage = (message) => tick(message.data);
+                this._worker.onmessage = message => tick(message.data);
             }
         }
         runInterval(tick) {
@@ -671,6 +671,7 @@
             this.connectHeaders = config.connectHeaders;
             this.disconnectHeaders = config.disconnectHeaders;
             this.heartbeatIncoming = config.heartbeatIncoming;
+            this.heartbeatToleranceMultiplier = config.heartbeatGracePeriods;
             this.heartbeatOutgoing = config.heartbeatOutgoing;
             this.splitLargeFrames = config.splitLargeFrames;
             this.maxWebSocketChunkSize = config.maxWebSocketChunkSize;
@@ -686,6 +687,8 @@
             this.onUnhandledMessage = config.onUnhandledMessage;
             this.onUnhandledReceipt = config.onUnhandledReceipt;
             this.onUnhandledFrame = config.onUnhandledFrame;
+            this.onHeartbeatReceived = config.onHeartbeatReceived;
+            this.onHeartbeatLost = config.onHeartbeatLost;
         }
         start() {
             const parser = new Parser(
@@ -702,6 +705,7 @@
             // On Incoming Ping
             () => {
                 this.debug('<<< PONG');
+                this.onHeartbeatReceived();
             });
             this._webSocket.onmessage = (evt) => {
                 this.debug('Received data');
@@ -766,9 +770,10 @@
                 this.debug(`check PONG every ${ttl}ms`);
                 this._ponger = setInterval(() => {
                     const delta = Date.now() - this._lastServerActivityTS;
-                    // We wait twice the TTL to be flexible on window's setInterval calls
-                    if (delta > ttl * 2) {
+                    // We wait multiple grace periods to be flexible on window's setInterval calls
+                    if (delta > ttl * this.heartbeatToleranceMultiplier) {
                         this.debug(`did not receive server activity for the last ${delta}ms`);
+                        this.onHeartbeatLost();
                         this._closeOrDiscardWebsocket();
                     }
                 }, ttl);
@@ -972,16 +977,52 @@
      * 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.
      */
     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;
@@ -993,19 +1034,53 @@
             }
         }
         /**
-         * `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 === exports.ActivationState.ACTIVE;
@@ -1015,121 +1090,217 @@
             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 reconnectTimeMode not LINEAR (e.g. EXPONENTIAL).
-             * Set to 0 to wait indefinitely.
+             * 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.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 = exports.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.heartbeatOutgoing = 10000;
+            this.heartbeatToleranceMultiplier = 2;
             /**
-             * Outgoing heartbeat strategy.
-             * See https://github.com/stomp-js/stompjs/pull/579
+             * 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.
              *
-             * Can be worker or interval strategy, but will always use `interval`
-             * if web workers are unavailable, for example, in a non-browser environment.
+             * Example:
+             * ```javascript
+             * client.heartbeatOutgoing = 5000; // Send a heartbeat every 5 seconds
+             * ```
+             */
+            this.heartbeatOutgoing = 10000;
+            /**
+             * 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 = exports.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.
              *
-             * Set this flag to force binary frames.
+             * Default behavior determines frame type based on payload (e.g., binary data for ArrayBuffers).
+             *
+             * 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.
+             * 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.
              *
-             * This is not an ideal solution, but a stop gap until the underlying issue is fixed at ReactNative library.
+             * 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.
              *
-             * It will usually be ACTIVE or INACTIVE.
-             * When deactivating, it may go from ACTIVE to INACTIVE without entering DEACTIVATING.
+             * 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.
+             *
+             * Note: The client may transition directly from `ACTIVE` to `INACTIVE` without entering
+             * the `DEACTIVATING` state.
              */
             this.state = exports.ActivationState.INACTIVE;
             // No op callbacks
@@ -1141,6 +1312,8 @@
             this.onUnhandledMessage = noOp;
             this.onUnhandledReceipt = noOp;
             this.onUnhandledFrame = noOp;
+            this.onHeartbeatReceived = noOp;
+            this.onHeartbeatLost = noOp;
             this.onStompError = noOp;
             this.onWebSocketClose = noOp;
             this.onWebSocketError = noOp;
@@ -1153,7 +1326,22 @@
             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
@@ -1166,12 +1354,20 @@
             }
         }
         /**
-         * 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}.
          *
-         * Call [Client#deactivate]{@link Client#deactivate} to disconnect and stop reconnection attempts.
+         * Example:
+         * ```javascript
+         * client.activate(); // Connect to the broker
+         * ```
+         *
+         * If the client is currently `DEACTIVATING`, connection is delayed until the deactivation process completes.
          */
         activate() {
             const _activate = () => {
@@ -1229,6 +1425,7 @@
                 connectHeaders: this.connectHeaders,
                 disconnectHeaders: this._disconnectHeaders,
                 heartbeatIncoming: this.heartbeatIncoming,
+                heartbeatGracePeriods: this.heartbeatToleranceMultiplier,
                 heartbeatOutgoing: this.heartbeatOutgoing,
                 heartbeatStrategy: this.heartbeatStrategy,
                 splitLargeFrames: this.splitLargeFrames,
@@ -1281,6 +1478,12 @@
                 onUnhandledFrame: frame => {
                     this.onUnhandledFrame(frame);
                 },
+                onHeartbeatReceived: () => {
+                    this.onHeartbeatReceived();
+                },
+                onHeartbeatLost: () => {
+                    this.onHeartbeatLost();
+                },
             });
             this._stompHandler.start();
         }
@@ -1314,27 +1517,36 @@
             }
         }
         /**
-         * 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.
          *
-         * 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.
+         * 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.
          *
-         * It is not an error to invoke this method more than once.
-         * Each of those would resolve on completion of deactivation.
+         * **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}.
          *
-         * To reactivate, you can call [Client#activate]{@link Client#activate}.
+         * **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.
          *
-         * 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.
+         * Example:
+         * ```javascript
+         * // Graceful disconnect
+         * await client.deactivate();
+         *
+         * // 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;
@@ -1379,10 +1591,18 @@
             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) {
@@ -1396,39 +1616,38 @@
             }
         }
         /**
-         * 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) {
@@ -1442,39 +1661,27 @@
             }
         }
         /**
-         * 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
-         *        });
-         *
-         *        client.subscribe(TEST.destination, onMessage, {receipt: receiptId});
-         *
+         * const receiptId = "unique-receipt-id";
          *
-         *        // Publishing with acknowledgement
-         *        receiptId = randomText();
+         * client.watchForReceipt(receiptId, (frame) => {
+         *   console.log("Operation acknowledged by the broker:", frame);
+         * });
          *
-         *        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();
@@ -1482,28 +1689,33 @@
             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");
-         *          }
-         *        });
+         * const callback = (message) => {
+         *   console.log("Received message:", message.body);
+         * };
          *
-         *        var subscription = client.subscribe("/queue/test", callback);
+         * // Auto-generated subscription ID
+         * const subscription = client.subscribe("/queue/test", callback);
          *
-         *        // Explicit subscription id
-         *        var mySubId = 'my-subscription-id-001';
-         *        var subscription = client.subscribe(destination, callback, { id: mySubId });
+         * // 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();
@@ -1511,16 +1723,24 @@
             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
+         * const subscription = client.subscribe("/queue/test", callback);
+         * // Unsubscribe using the subscription object
+         * subscription.unsubscribe();
+         * ```
+         *
+         * This method can also be used directly with the subscription ID.
          *
+         * Example:
          * ```javascript
-         *        var subscription = client.subscribe(destination, onmessage);
-         *        // ...
-         *        subscription.unsubscribe();
+         * client.unsubscribe("my-subscription-id");
          * ```
          *
-         * See: https://stomp.github.com/stomp-specification-1.2.html#UNSUBSCRIBE UNSUBSCRIBE Frame
+         * @param id Subscription ID to unsubscribe.
+         * @param headers Optional headers to pass for the UNSUBSCRIBE frame.
          */
         unsubscribe(id, headers = {}) {
             this._checkConnection();
@@ -1528,10 +1748,21 @@
             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
+         *
+         * // Or explicitly specify a transaction ID
+         * const tx = client.begin("my-transaction-id");
+         * ```
          *
-         * `transactionId` is optional, if not passed the library will generate it internally.
+         * @param transactionId Optional transaction ID.
+         * @returns An instance of {@link ITransaction}.
          */
         begin(transactionId) {
             this._checkConnection();
@@ -1539,16 +1770,19 @@
             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();
@@ -1556,15 +1790,19 @@
             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();
@@ -1572,17 +1810,23 @@
             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();
@@ -1590,17 +1834,25 @@
             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();
@@ -1620,7 +1872,7 @@
     }
 
     /**
-     * STOMP headers. Many functions calls will accept headers as parameters.
+     * STOMP headers. Many function calls will accept headers as parameters.
      * The headers sent by Broker will be available as [IFrame#headers]{@link IFrame#headers}.
      *
      * `key` and `value` must be valid strings.