@stomp/stompjs 7.1.0 → 7.2.0

package/esm6/client.d.ts

@@ -2,527 +2,892 @@ import { ITransaction } from './i-transaction.js';
 import { StompConfig } from './stomp-config.js';
 import { StompHeaders } from './stomp-headers.js';
 import { StompSubscription } from './stomp-subscription.js';
-import { ActivationState, closeEventCallbackType, debugFnType, frameCallbackType, IPublishParams, IStompSocket, messageCallbackType, ReconnectionTimeMode, TickerStrategy, wsErrorCallbackType } from './types.js';
+import { ActivationState, closeEventCallbackType, debugFnType, emptyCallbackType, frameCallbackType, IPublishParams, IStompSocket, messageCallbackType, ReconnectionTimeMode, TickerStrategy, wsErrorCallbackType } from './types.js';
 import { Versions } from './versions.js';
 /**
  * STOMP Client Class.
  *
  * Part of `@stomp/stompjs`.
+ *
+ * This class provides a robust implementation for connecting to and interacting with a
+ * STOMP-compliant messaging broker over WebSocket. It supports STOMP versions 1.2, 1.1, and 1.0.
+ *
+ * Features:
+ * - Handles automatic reconnections.
+ * - Supports heartbeat mechanisms to detect and report communication failures.
+ * - Allows customization of connection and WebSocket behaviors through configurations.
+ * - Compatible with both browser environments and Node.js with polyfill support for WebSocket.
  */
 export declare 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"`.
+     * Example: `"ws://broker.domain.com:15674/ws"` or `"wss://broker.domain.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}.
+     * 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}.
      */
     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']);
      * ```
      */
     stompVersions: Versions;
     /**
-     * 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.
      */
     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
+     * ```
      */
     connectionTimeout: number;
     private _connectionWatcher;
     /**
-     *  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
+     * ```
      */
     reconnectDelay: number;
     /**
-     * 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;
     /**
-     * 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
+     * ```
      */
     maxReconnectDelay: number;
     /**
-     * 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
+     * ```
      */
     reconnectTimeMode: ReconnectionTimeMode;
     /**
-     * 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
+     * ```
      */
     heartbeatIncoming: number;
     /**
-     * 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
+     * ```
      */
-    heartbeatOutgoing: number;
+    heartbeatToleranceMultiplier: number;
     /**
-     * Outgoing heartbeat strategy.
-     * See https://github.com/stomp-js/stompjs/pull/579
+     * Interval (in milliseconds) for sending heartbeat signals to the server.
      *
-     * Can be worker or interval strategy, but will always use `interval`
-     * if web workers are unavailable, for example, in a non-browser environment.
+     * Specifies how frequently heartbeats should be sent to the server. Set to `0` to disable.
      *
-     * 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.
+     * Example:
+     * ```javascript
+     * client.heartbeatOutgoing = 5000; // Send a heartbeat every 5 seconds
+     * ```
+     */
+    heartbeatOutgoing: number;
+    /**
+     * 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).
      *
-     * 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;
+     * ```
      */
     heartbeatStrategy: TickerStrategy;
     /**
-     * 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
+     * ```
      */
     splitLargeFrames: boolean;
     /**
-     * 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`.
      */
     maxWebSocketChunkSize: number;
     /**
-     * Usually the
-     * [type of WebSocket frame]{@link https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send#Parameters}
-     * is automatically decided by type of the payload.
-     * Default is `false`, which should work with all compliant brokers.
+     * Forces all WebSocket frames to use binary transport, irrespective of payload type.
+     *
+     * Default behavior determines frame type based on payload (e.g., binary data for ArrayBuffers).
      *
-     * Set this flag to force binary frames.
+     * Example:
+     * ```javascript
+     * client.forceBinaryWSFrames = true;
+     * ```
      */
     forceBinaryWSFrames: boolean;
     /**
-     * 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;
+     * ```
      */
     appendMissingNULLonIncoming: boolean;
     /**
-     * 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;
     /**
-     * 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'
+     * };
+     * ```
      */
     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;
     set disconnectHeaders(value: StompHeaders);
     private _disconnectHeaders;
     /**
-     * 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.
+     *
+     * 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.
      *
-     * It can also get invoked with stray messages while the server is processing
-     * a request to [Client#unsubscribe]{@link Client#unsubscribe}
-     * from an endpoint.
+     * Usage:
+     * ```javascript
+     * client.onUnhandledMessage = (message) => {
+     *   console.log('Unhandled message:', message);
+     * };
+     * ```
      *
-     * The actual {@link IMessage} will be passed as parameter to the callback.
+     * @param message The actual {@link IMessage} received.
      */
     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.
      */
     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.
      *
-     * The actual {@link IFrame} will be passed as parameter to the callback.
+     * Usage:
+     * ```javascript
+     * client.onUnhandledFrame = (frame) => {
+     *   console.warn('Unhandled frame received:', frame);
+     * };
+     * ```
+     *
+     * @param frame The actual {@link IFrame} received from the broker.
      */
     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');
+     * };
+     * ```
+     */
+    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');
+     * };
+     * ```
+     */
+    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;
     /**
-     * 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}` };
+     * };
+     * ```
      */
     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.
      *
-     * The actual {@link IFrame} will be passed as parameter to the callback.
-     * Sometimes clients will like to use headers from this frame.
+     * 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.
+     *
+     * Example:
+     * ```javascript
+     * client.onConnect = (frame) => {
+     *   console.log('Connected to broker, session ID:', frame.headers['session']);
+     * };
+     * ```
      */
     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');
+     * };
+     * ```
      */
     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.
      *
-     * The actual {@link IFrame} will be passed as parameter to the callback.
+     * 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.
+     *
+     * Example:
+     * ```javascript
+     * client.onStompError = (frame) => {
+     *   console.error('Broker reported an error:', frame.body);
+     * };
+     * ```
      */
     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);
+     * };
+     * ```
      */
     onWebSocketClose: closeEventCallbackType;
     /**
-     * Callback, invoked when underlying WebSocket raises an error.
+     * Callback executed when the underlying WebSocket raises an error.
+     *
+     * This callback provides an [Event]{@link https://developer.mozilla.org/en-US/docs/Web/API/Event}
+     * representing the error raised by the WebSocket.
      *
-     * Actual [Event]{@link https://developer.mozilla.org/en-US/docs/Web/API/Event}
-     * is passed as parameter to the callback.
+     * Example:
+     * ```javascript
+     * client.onWebSocketError = (event) => {
+     *   console.error('WebSocket error:', event);
+     * };
+     * ```
      */
     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.
+     *
+     * When enabled, it logs the raw frames exchanged with the broker. If disabled,
+     * only the headers of the parsed frames will be logged.
+     *
+     * **Caution**: Raw communication frames must contain valid UTF-8 strings,
+     * as any non-compliant data can cause errors in the logging process.
      *
-     * Changes effect from the next broker reconnect.
+     * Changes to this setting will take effect during the next broker reconnect.
      *
-     * **Caution: this assumes that frames only have valid UTF8 strings.**
+     * Example:
+     * ```javascript
+     * client.logRawCommunication = true; // Enable logging raw communication
+     * ```
      */
     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.
      */
     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`.
      */
     discardWebsocketOnCommFailure: boolean;
     /**
-     * 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;
     private _stompHandler;
     /**
-     * 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;
     /**
-     * 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}`);
+     * };
+     * ```
      */
     onChangeState: (state: ActivationState) => void;
     private _changeState;
     /**
-     * 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.
      */
     state: ActivationState;
     private _reconnector;
     /**
-     * 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);
     /**
-     * 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: StompConfig): void;
     /**
-     * Initiate the connection with the broker.
-     * If the connection breaks, as per [Client#reconnectDelay]{@link Client#reconnectDelay},
-     * it will keep trying to reconnect. If the [Client#reconnectTimeMode]{@link Client#reconnectTimeMode}
-     * is set to EXPONENTIAL it will increase the wait time exponentially
+     * Activates the client, initiating a connection to the STOMP broker.
+     *
+     * On activation, the client attempts to connect and sets its state to `ACTIVE`. If the connection
+     * is lost, it will automatically retry based on `reconnectDelay` or `maxReconnectDelay`. If
+     * `reconnectTimeMode` is set to `EXPONENTIAL`, the reconnect delay increases exponentially.
+     *
+     * To stop reconnection attempts and disconnect, call [Client#deactivate]{@link Client#deactivate}.
+     *
+     * Example:
+     * ```javascript
+     * client.activate(); // Connect to the broker
+     * ```
      *
-     * Call [Client#deactivate]{@link Client#deactivate} to disconnect and stop reconnection attempts.
+     * If the client is currently `DEACTIVATING`, connection is delayed until the deactivation process completes.
      */
     activate(): void;
     private _connect;
     private _createWebSocket;
     private _schedule_reconnect;
     /**
-     * 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.
      */
     deactivate(options?: {
         force?: boolean;
     }): Promise<void>;
     /**
-     * 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(): void;
     private _disposeStompHandler;
     /**
-     * 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' }
+     * });
      * ```
      */
     publish(params: IPublishParams): void;
     private _checkConnection;
     /**
-     * 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.
      */
     watchForReceipt(receiptId: string, callback: frameCallbackType): void;
     /**
-     * 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.
      */
     subscribe(destination: string, callback: messageCallbackType, headers?: StompHeaders): StompSubscription;
     /**
-     * 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: string, headers?: StompHeaders): void;
     /**
-     * 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}.
      *
-     * `transactionId` is optional, if not passed the library will generate it internally.
+     * 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");
+     * ```
+     *
+     * @param transactionId Optional transaction ID.
+     * @returns An instance of {@link ITransaction}.
      */
     begin(transactionId?: string): ITransaction;
     /**
-     * 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: string): void;
     /**
-     * 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: string): void;
     /**
-     * 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: string, subscriptionId: string, headers?: StompHeaders): void;
     /**
-     * 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: string, subscriptionId: string, headers?: StompHeaders): void;
 }