@stomp/stompjs 7.1.0 → 7.2.0

package/src/client.ts

@@ -7,6 +7,7 @@ import {
   ActivationState,
   closeEventCallbackType,
   debugFnType,
+  emptyCallbackType,
   frameCallbackType,
   IPublishParams,
   IStompSocket,
@@ -30,173 +31,297 @@ declare const WebSocket: {
  * 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 {
   /**
    * The URL for the STOMP broker to connect to.
-   * Typically like `"ws://broker.329broker.com:15674/ws"` or `"wss://broker.329broker.com:15674/ws"`.
-   *
-   * Only one of this or [Client#webSocketFactory]{@link Client#webSocketFactory} need to be set.
-   * If both are set, [Client#webSocketFactory]{@link Client#webSocketFactory} will be used.
-   *
-   * If your environment does not support WebSockets natively, please refer to
-   * [Polyfills]{@link https://stomp-js.github.io/guide/stompjs/rx-stomp/ng2-stompjs/pollyfils-for-stompjs-v5.html}.
+   * Example: `"ws://broker.domain.com:15674/ws"` or `"wss://broker.domain.com:15674/ws"`.
+   *
+   * Use this property to define the broker's WebSocket endpoint.
+   * Note:
+   * - Only one of `brokerURL` or [Client#webSocketFactory]{@link Client#webSocketFactory} needs to be set.
+   * - If both are provided, [Client#webSocketFactory]{@link Client#webSocketFactory} takes precedence.
+   * - When targeting environments without native WebSocket support, refer to 
+   *   [Polyfills]{@link https://stomp-js.github.io/guide/stompjs/rx-stomp/ng2-stompjs/pollyfils-for-stompjs-v5.html}.
    */
   public brokerURL: string | undefined;
 
   /**
-   * 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']);
    * ```
    */
   public stompVersions = Versions.default;
 
   /**
-   * This function should return a WebSocket or a similar (e.g. SockJS) object.
-   * If your environment does not support WebSockets natively, please refer to
-   * [Polyfills]{@link https://stomp-js.github.io/guide/stompjs/rx-stomp/ng2-stompjs/pollyfils-for-stompjs-v5.html}.
-   * If your STOMP Broker supports WebSockets, prefer setting [Client#brokerURL]{@link Client#brokerURL}.
+   * A function that returns a WebSocket or a similar object (e.g., SockJS) to establish connections.
    *
-   * If both this and [Client#brokerURL]{@link Client#brokerURL} are set, this will be used.
+   * This is an alternative to [Client#brokerURL]{@link Client#brokerURL}.
+   * Using this allows finer control over WebSocket creation, especially for custom wrappers
+   * or when working in non-standard environments.
    *
    * Example:
    * ```javascript
-   *        // use a WebSocket
-   *        client.webSocketFactory= function () {
-   *          return new WebSocket("wss://broker.329broker.com:15674/ws");
-   *        };
-   *
-   *        // Typical usage with SockJS
-   *        client.webSocketFactory= function () {
-   *          return new SockJS("http://broker.329broker.com/stomp");
-   *        };
+   * client.webSocketFactory = function () {
+   *   return new WebSocket("ws://my-custom-websocket-endpoint");
+   * };
+   *
+   * // Typical usage with SockJS
+   * client.webSocketFactory= function () {
+   *   return new SockJS("http://broker.329broker.com/stomp");
+   * };
    * ```
+   *
+   * Note:
+   * - If both [Client#brokerURL]{@link Client#brokerURL} and this property are set, the factory will be used.
+   * - Refer to [Polyfills Guide]{@link https://stomp-js.github.io/guide/stompjs/rx-stomp/ng2-stompjs/pollyfils-for-stompjs-v5.html}
+   *   when running in environments without native WebSocket support.
    */
   public webSocketFactory: (() => IStompSocket) | undefined;
 
   /**
-   * 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
+   * ```
    */
   public connectionTimeout: number = 0;
 
-  // As per https://stackoverflow.com/questions/45802988/typescript-use-correct-version-of-settimeout-node-vs-window/56239226#56239226
-  private _connectionWatcher: ReturnType<typeof setTimeout> | undefined; // Timer
+  // Internal timer for handling connection timeout, if set.
+  // See https://stackoverflow.com/questions/45802988/typescript-use-correct-version-of-settimeout-node-vs-window/56239226#56239226
+  private _connectionWatcher: ReturnType<typeof setTimeout> | undefined;
 
   /**
-   *  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
+   * ```
    */
   public reconnectDelay: number = 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}.
    */
   private _nextReconnectDelay: number = 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
+   * ```
    */
-  public maxReconnectDelay: number = 15 * 60 * 1000; // 15 minutes in ms
+  public maxReconnectDelay: number = 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
+   * ```
    */
   public reconnectTimeMode: ReconnectionTimeMode = 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
+   * ```
    */
   public heartbeatIncoming: number = 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
+   * ```
+   */
+  public heartbeatToleranceMultiplier: number = 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
+   * ```
    */
   public heartbeatOutgoing: number = 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.
-   *
-   * 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.
-   *
-   * When used in a JS environment, use 'worker' or 'interval' as valid values.
-   *
-   * Defaults to `interval` strategy.
+   * Strategy for sending outgoing heartbeats.
+   * 
+   * Options:
+   * - `TickerStrategy.Worker`: Uses Web Workers for sending heartbeats (recommended for long-running or background sessions).
+   * - `TickerStrategy.Interval`: Uses standard JavaScript `setInterval` (default).
+   * 
+   * 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.
+   * 
+   * Example:
+   * ```javascript
+   * client.heartbeatStrategy = TickerStrategy.Worker;
+   * ```
    */
   public heartbeatStrategy: TickerStrategy = 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
+   * ```
    */
   public splitLargeFrames: boolean = 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`.
    */
   public maxWebSocketChunkSize: number = 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;
+   * ```
    */
   public forceBinaryWSFrames: boolean = 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.
    *
-   * This is not an ideal solution, but a stop gap until the underlying issue is fixed at ReactNative library.
+   * 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;
+   * ```
    */
   public appendMissingNULLonIncoming: boolean = false;
 
   /**
-   * 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(): IStompSocket | undefined {
     return this._stompHandler?._webSocket;
   }
 
   /**
-   * Connection headers, important keys - `login`, `passcode`, `host`.
-   * Though STOMP 1.2 standard marks these keys to be present, check your broker documentation for
-   * details specific to your broker.
+   * Connection headers to be sent during the connection handshake.
+   *
+   * Keys like `login`, `passcode`, and `host` are commonly expected for most brokers.
+   * Although STOMP 1.2 specifies these keys as mandatory, consult your broker's documentation
+   * for additional requirements or alternative header usage.
+   *
+   * Example:
+   * ```javascript
+   * client.connectHeaders = {
+   *   login: 'my-username',
+   *   passcode: 'my-password',
+   *   host: 'my-vhost'
+   * };
+   * ```
    */
   public connectHeaders: StompHeaders;
 
   /**
-   * 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(): StompHeaders {
     return this._disconnectHeaders;
@@ -211,139 +336,272 @@ export class Client {
   private _disconnectHeaders: StompHeaders;
 
   /**
-   * This function will be called for any unhandled messages.
-   * It is useful for receiving messages sent to RabbitMQ temporary queues.
+   * Callback invoked for any unhandled messages received from the broker.
    *
-   * It can also get invoked with stray messages while the server is processing
-   * a request to [Client#unsubscribe]{@link Client#unsubscribe}
-   * from an endpoint.
+   * This is particularly useful for handling messages sent to RabbitMQ temporary queues
+   * or other queues where no explicit subscription exists. It can also be triggered
+   * by stray messages received while a subscription is being unsubscribed.
    *
-   * The actual {@link IMessage} will be passed as parameter to the callback.
+   * Usage:
+   * ```javascript
+   * client.onUnhandledMessage = (message) => {
+   *   console.log('Unhandled message:', message);
+   * };
+   * ```
+   *
+   * @param message The actual {@link IMessage} received.
    */
   public onUnhandledMessage: messageCallbackType;
 
   /**
-   * STOMP brokers can be requested to notify when an operation is actually completed.
-   * Prefer using [Client#watchForReceipt]{@link Client#watchForReceipt}. See
-   * [Client#watchForReceipt]{@link Client#watchForReceipt} for examples.
+   * Callback invoked when the broker sends a receipt indicating the completion
+   * of an operation. Receipts are typically requested using the
+   * [Client#watchForReceipt]{@link Client#watchForReceipt} function.
    *
-   * The actual {@link IFrame} will be passed as parameter to the callback.
+   * Usage Example:
+   * See [Client#watchForReceipt]{@link Client#watchForReceipt}.
+   *
+   * @param frame The actual {@link IFrame} received from the broker.
    */
   public onUnhandledReceipt: frameCallbackType;
 
   /**
-   * Will be invoked if {@link IFrame} of an unknown type is received from the STOMP broker.
+   * Callback invoked when a frame of an unknown or unexpected type is received
+   * from the broker.
+   *
+   * This is intended as a fallback for handling unexpected or unsupported frames
+   * sent by the broker.
+   *
+   * Usage:
+   * ```javascript
+   * client.onUnhandledFrame = (frame) => {
+   *   console.warn('Unhandled frame received:', frame);
+   * };
+   * ```
    *
-   * The actual {@link IFrame} will be passed as parameter to the callback.
+   * @param frame The actual {@link IFrame} received from the broker.
    */
   public onUnhandledFrame: frameCallbackType;
 
   /**
-   * `true` if there is an active connection to STOMP Broker
+   * Callback invoked when a heartbeat message is received from the STOMP broker.
+   *
+   * Heartbeats ensure that the connection remains active and responsive. This callback
+   * is executed on every received heartbeat. It is useful for monitoring connection health
+   * or logging heartbeat activity.
+   *
+   * **Note**: The library handles heartbeats internally to maintain and verify connection status.
+   * Implementing this callback is optional and primarily for custom monitoring or debugging.
+   *
+   * Usage:
+   * ```javascript
+   * client.onHeartbeatReceived = () => {
+   *   console.log('Heartbeat received');
+   * };
+   * ```
+   */
+  public onHeartbeatReceived: emptyCallbackType;
+
+  /**
+   * Callback invoked when no heartbeat is received from the broker within
+   * the acceptable interval, indicating a potential communication issue or connection failure.
+   *
+   * This callback is triggered when the heartbeat interval defined by `heartbeatIncoming`
+   * elapses without a received heartbeat.
+   *
+   * **Note**: The library handles this condition internally and takes appropriate
+   * actions, such as marking the connection as failed. This callback is available
+   * for implementing custom recovery strategies or additional notifications.
+   *
+   * Usage:
+   * ```javascript
+   * client.onHeartbeatLost = () => {
+   *   console.error('Lost connection to the broker');
+   * };
+   * ```
+   */
+  public onHeartbeatLost: emptyCallbackType;
+
+  /**
+   * 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(): boolean {
     return !!this._stompHandler && this._stompHandler.connected;
   }
 
   /**
-   * Callback, invoked on before a connection to the STOMP broker.
+   * Callback executed before initiating a connection to the STOMP broker.
+   *
+   * This callback allows users to modify connection options dynamically,
+   * such as updating credentials or connection parameters, before the connection is made.
    *
-   * You can change options on the client, which will impact the immediate connecting.
-   * It is valid to call [Client#decativate]{@link Client#deactivate} in this callback.
+   * As of version 5.1, this callback supports `async/await`, enabling seamless integration
+   * with asynchronous operations, such as fetching tokens or credentials.
    *
-   * As of version 5.1, this callback can be
-   * [async](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)
-   * (i.e., it can return a
-   * [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)).
-   * In that case, connect will be called only after the Promise is resolved.
-   * This can be used to reliably fetch credentials, access token etc. from some other service
-   * in an asynchronous way.
+   * Example:
+   * ```javascript
+   * client.beforeConnect = async () => {
+   *   const token = await fetchToken();
+   *   client.connectHeaders = { Authorization: `Bearer ${token}` };
+   * };
+   * ```
    */
   public beforeConnect: (client: Client) => void | Promise<void>;
 
   /**
-   * Callback, invoked on every successful connection to the STOMP broker.
+   * Callback executed upon every successful connection to the STOMP broker.
+   *
+   * This callback is invoked after the connection is established and the CONNECTED frame
+   * is received from the broker. It provides access to the broker's response frame,
+   * allowing users to parse its headers or other data.
    *
-   * The actual {@link IFrame} will be passed as parameter to the callback.
-   * Sometimes clients will like to use headers from this frame.
+   * Example:
+   * ```javascript
+   * client.onConnect = (frame) => {
+   *   console.log('Connected to broker, session ID:', frame.headers['session']);
+   * };
+   * ```
    */
   public onConnect: frameCallbackType;
 
   /**
-   * Callback, invoked on every successful disconnection from the STOMP broker. It will not be invoked if
-   * the STOMP broker disconnected due to an error.
+   * Callback executed upon successful disconnection from the STOMP broker.
    *
-   * The actual Receipt {@link IFrame} acknowledging the DISCONNECT will be passed as parameter to the callback.
+   * The callback is invoked when the DISCONNECT receipt is received from the broker.
+   * Note that due to the design of the STOMP protocol or communication interrupts, the
+   * DISCONNECT receipt may not always be received. For handling such cases, use
+   * [Client#onWebSocketClose]{@link Client#onWebSocketClose}.
    *
-   * The way STOMP protocol is designed, the connection may close/terminate without the client
-   * receiving the Receipt {@link IFrame} acknowledging the DISCONNECT.
-   * You might find [Client#onWebSocketClose]{@link Client#onWebSocketClose} more appropriate to watch
-   * STOMP broker disconnects.
+   * Example:
+   * ```javascript
+   * client.onDisconnect = (frame) => {
+   *   console.log('Disconnected successfully');
+   * };
+   * ```
    */
   public onDisconnect: frameCallbackType;
 
   /**
-   * Callback, invoked on an ERROR frame received from the STOMP Broker.
-   * A compliant STOMP Broker will close the connection after this type of frame.
-   * Please check broker specific documentation for exact behavior.
+   * Callback executed when an ERROR frame is received from the STOMP broker.
+   *
+   * Receiving an ERROR frame typically indicates a problem with the subscription,
+   * message format, or protocol violation. The broker will usually close the connection
+   * after sending an ERROR frame.
    *
-   * The actual {@link IFrame} will be passed as parameter to the callback.
+   * Example:
+   * ```javascript
+   * client.onStompError = (frame) => {
+   *   console.error('Broker reported an error:', frame.body);
+   * };
+   * ```
    */
   public onStompError: frameCallbackType;
 
   /**
-   * Callback, invoked when underlying WebSocket is closed.
+   * Callback executed when the underlying WebSocket is closed.
+   *
+   * This can occur due to various reasons, such as network interruptions or broker shutdown.
+   * The callback provides the WebSocket [CloseEvent]{@link https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent},
+   * which contains details about the closure.
    *
-   * Actual [CloseEvent]{@link https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent}
-   * is passed as parameter to the callback.
+   * Example:
+   * ```javascript
+   * client.onWebSocketClose = (event) => {
+   *   console.log('WebSocket closed. Code:', event.code);
+   * };
+   * ```
    */
   public onWebSocketClose: closeEventCallbackType;
 
   /**
-   * Callback, invoked when underlying WebSocket raises an error.
+   * Callback executed when the underlying WebSocket raises an error.
    *
-   * Actual [Event]{@link https://developer.mozilla.org/en-US/docs/Web/API/Event}
-   * is passed as parameter to the callback.
+   * This callback provides an [Event]{@link https://developer.mozilla.org/en-US/docs/Web/API/Event}
+   * representing the error raised by the WebSocket.
+   *
+   * Example:
+   * ```javascript
+   * client.onWebSocketError = (event) => {
+   *   console.error('WebSocket error:', event);
+   * };
+   * ```
    */
   public onWebSocketError: wsErrorCallbackType;
 
   /**
-   * Set it to log the actual raw communication with the broker.
-   * When unset, it logs headers of the parsed frames.
+   * Enable or disable logging of the raw communication with the broker.
    *
-   * Changes effect from the next broker reconnect.
+   * When enabled, it logs the raw frames exchanged with the broker. If disabled,
+   * only the headers of the parsed frames will be logged.
    *
-   * **Caution: this assumes that frames only have valid UTF8 strings.**
+   * **Caution**: Raw communication frames must contain valid UTF-8 strings,
+   * as any non-compliant data can cause errors in the logging process.
+   *
+   * Changes to this setting will take effect during the next broker reconnect.
+   *
+   * Example:
+   * ```javascript
+   * client.logRawCommunication = true; // Enable logging raw communication
+   * ```
    */
   public logRawCommunication: boolean;
 
   /**
-   * By default, debug messages are discarded. To log to `console` following can be used:
+   * Set a custom debug function to capture debug messages.
    *
+   * By default, debug messages are discarded. To log messages to the console, you can use:
    * ```javascript
-   *        client.debug = function(str) {
-   *          console.log(str);
-   *        };
+   * client.debug = (str) => {
+   *   console.log(str);
+   * };
    * ```
    *
-   * Currently this method does not support levels of log. Be aware that the
-   * output can be quite verbose
-   * and may contain sensitive information (like passwords, tokens etc.).
+   * **Note**: This method does not support configurable log levels, and the output can be
+   * verbose. Be cautious as debug messages may contain sensitive information, such as
+   * credentials or tokens.
    */
   public debug: debugFnType;
 
   /**
-   * 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`.
    */
   public discardWebsocketOnCommFailure: boolean = false;
 
   /**
-   * 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(): string | undefined {
     return this._stompHandler ? this._stompHandler.connectedVersion : undefined;
@@ -352,16 +610,38 @@ export class Client {
   private _stompHandler: StompHandler | 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(): boolean {
     return this.state === ActivationState.ACTIVE;
   }
 
   /**
-   * It will be called on state change.
+   * Callback invoked whenever the client's state changes.
+   *
+   * This callback can be used to monitor transitions between various states, such as `ACTIVE`,
+   * `INACTIVE`, or `DEACTIVATING`. Note that in some scenarios, the client may transition
+   * directly from `ACTIVE` to `INACTIVE` without entering the `DEACTIVATING` state.
    *
-   * When deactivating, it may go from ACTIVE to INACTIVE without entering DEACTIVATING.
+   * Example:
+   * ```javascript
+   * client.onChangeState = (state) => {
+   *   console.log(`Client state changed to: ${state}`);
+   * };
+   * ```
    */
   public onChangeState: (state: ActivationState) => void;
 
@@ -371,17 +651,35 @@ export class Client {
   }
 
   /**
-   * 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.
    */
   public state: ActivationState = ActivationState.INACTIVE;
 
   private _reconnector: any;
 
   /**
-   * 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: StompConfig = {}) {
     // No op callbacks
@@ -393,6 +691,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;
@@ -408,8 +708,24 @@ export class Client {
   }
 
   /**
-   * 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.
    */
+
   public configure(conf: StompConfig): void {
     // bulk assign all properties to this
     (Object as any).assign(this, conf);
@@ -427,12 +743,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.
    */
   public activate(): void {
     const _activate = () => {
@@ -505,6 +829,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,
@@ -564,6 +889,12 @@ export class Client {
       onUnhandledFrame: frame => {
         this.onUnhandledFrame(frame);
       },
+      onHeartbeatReceived: () => {
+        this.onHeartbeatReceived();
+      },
+      onHeartbeatLost: () => {
+        this.onHeartbeatLost();
+      },
     });
 
     this._stompHandler.start();
@@ -611,27 +942,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.
    *
-   * 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();
    *
-   * It is possible to invoke this method initially without the `force` option
-   * and subsequently, say after a wait, with the `force` option.
+   * // Forced disconnect to speed up shutdown when the connection is stale
+   * await client.deactivate({ force: true });
+   * ```
+   *
+   * @param options Configuration options for deactivation. Use `force: true` for immediate shutdown.
+   * @returns A Promise that resolves when the deactivation process completes.
    */
   public async deactivate(options: { force?: boolean } = {}): Promise<void> {
     const force: boolean = options.force || false;
@@ -684,10 +1024,18 @@ export class Client {
   }
 
   /**
-   * 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();
+   * ```
    */
   public forceDisconnect() {
     if (this._stompHandler) {
@@ -703,39 +1051,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.
-   *
-   * `body` must be String.
-   * You will need to covert the payload to string in case it is not string (e.g. JSON).
+   * Sends a message to the specified destination on the STOMP broker.
    *
-   * 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.
+   * 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).
    *
-   * `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.
+   * **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.
    *
-   * 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' }
+   * });
    * ```
    */
   public publish(params: IPublishParams) {
@@ -751,39 +1098,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.
-   *
-   * 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.
+   * Monitors for a receipt acknowledgment from the broker for specific operations.
    *
-   * This method allows watching for a receipt and invoking the callback
-   *  when the corresponding receipt has been received.
+   * 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.
    *
-   * 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.
    */
   public watchForReceipt(receiptId: string, callback: frameCallbackType): void {
     this._checkConnection();
@@ -792,28 +1127,33 @@ export class Client {
   }
 
   /**
-   * 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.
+   *
+   * The callback is triggered for each message received from the subscribed destination. The message
+   * is passed as an {@link IMessage} instance.
    *
-   * 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.
+   * **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.
    */
   public subscribe(
     destination: string,
@@ -826,16 +1166,24 @@ export class Client {
   }
 
   /**
-   * 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.
    */
   public unsubscribe(id: string, headers: StompHeaders = {}): void {
     this._checkConnection();
@@ -844,10 +1192,21 @@ export class Client {
   }
 
   /**
-   * 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}.
    */
   public begin(transactionId?: string): ITransaction {
     this._checkConnection();
@@ -856,16 +1215,19 @@ export class Client {
   }
 
   /**
-   * Commit 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}.
-   *
+   * Commits a transaction.
+   * 
+   * 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.
    */
   public commit(transactionId: string): void {
     this._checkConnection();
@@ -874,15 +1236,19 @@ export class Client {
   }
 
   /**
-   * 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.
    */
   public abort(transactionId: string): void {
     this._checkConnection();
@@ -891,17 +1257,23 @@ export class Client {
   }
 
   /**
-   * 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.
    */
   public ack(
     messageId: string,
@@ -914,17 +1286,25 @@ export class Client {
   }
 
   /**
-   * 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.
    */
   public nack(
     messageId: string,